MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
DuctLoss.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "DuctGrid.hpp"
4
5/**
6 * @file DuctLoss.hpp
7 * @brief Wall losses of a duct as friction and viscosity on the volume velocity.
8 *
9 * A lossless duct rings forever and keeps every harmonic, which sounds bright,
10 * buzzy and saturated. In a real tube the walls take energy from the flow in
11 * a boundary layer a fraction of a millimetre thick, and they take more from
12 * high frequencies than from low ones. Two terms in the momentum equation
13 * stand for that:
14 *
15 * du/dt = ... - friction u + viscosity d2u/dx2
16 *
17 * Friction takes the same fraction of every frequency. Viscosity takes
18 * more of the shorter waves: a plane wave of frequency f loses amplitude at
19 * rate alpha = friction / (2 c) + viscosity (2 pi f)^2 / (2 c^3) per metre.
20 * Between them they can follow the measured loss of a tube over the range that
21 * matters, and viscothermal_rates fits the two to the Kirchhoff attenuation at
22 * a low and a high frequency. The true loss grows as the square root of the
23 * frequency, so this is a fit and not the law; a passive fractional model of
24 * the square root is the later refinement.
25 *
26 * The step is implicit: the velocity after the wave update is replaced by the
27 * solution of a tridiagonal system, weighted by each section's inertance, so
28 * the step cannot add energy and is stable for any coefficients.
29 */
30
32
33/**
34 * @brief Plane wave attenuation of a circular tube from its wall boundary layers.
35 * @param radius Tube radius in metres
36 * @param frequency Frequency in Hz
37 * @param sound_speed Speed of sound
38 * @param air_density Air density
39 * @return Amplitude attenuation in nepers per metre, from the Kirchhoff
40 * low reduced frequency result for air, viscous and thermal terms
41 * together. Zero for a value that is not positive and finite.
42 */
43[[nodiscard]] MAYAFLUX_API double viscothermal_attenuation(
44 double radius, double frequency, double sound_speed = 343.0, double air_density = 1.2) noexcept;
45
46/**
47 * @brief Friction and viscosity that match the tube's attenuation at two frequencies.
48 * @param radius Tube radius in metres
49 * @param sound_speed Speed of sound
50 * @param air_density Air density
51 * @param low_frequency Lower frequency of the fit in Hz
52 * @param high_frequency Upper frequency of the fit in Hz
53 * @return Friction in 1/s, then viscosity in m^2/s. Both zero for inputs that
54 * are not positive and finite, or a lower frequency not below the upper.
55 */
56[[nodiscard]] MAYAFLUX_API std::pair<double, double> viscothermal_rates(
57 double radius,
58 double sound_speed = 343.0,
59 double air_density = 1.2,
60 double low_frequency = 150.0,
61 double high_frequency = 3000.0) noexcept;
62
63/**
64 * @class DuctLoss
65 * @brief Prepared implicit loss step for one duct grid.
66 */
67class MAYAFLUX_API DuctLoss {
68public:
69 /**
70 * @brief Factor the loss for a grid.
71 * @param grid Grid the velocities belong to
72 * @param friction Friction in 1/s, not negative
73 * @param viscosity Viscosity in m^2/s, not negative
74 * @return False, leaving the loss as it was, for a grid of fewer than two
75 * intervals or a rate that is negative or not finite
76 * @note Allocates only when the grid size changes, so a retune at a block
77 * boundary on the same grid allocates nothing.
78 */
79 [[nodiscard]] bool configure(const DuctGrid& grid, double friction, double viscosity);
80
81 /**
82 * @brief Apply the loss to the velocities of a sample, in place.
83 * @param velocity N volume velocities just after the wave update
84 *
85 * Does nothing when both rates are zero, or when the size does not match
86 * the grid. Allocates nothing.
87 */
88 void apply(std::span<double> velocity) const noexcept;
89
90 [[nodiscard]] bool active() const noexcept { return m_active; }
91 [[nodiscard]] double friction() const noexcept { return m_friction; }
92 [[nodiscard]] double viscosity() const noexcept { return m_viscosity; }
93
94private:
95 std::vector<double> m_mass;
96 std::vector<double> m_edge;
97 std::vector<double> m_upper;
98 std::vector<double> m_inverse_pivot;
99 double m_friction {};
100 double m_viscosity {};
101 bool m_active { false };
102};
103
104} // namespace MayaFlux::Kinesis::Acoustics
Interleaved grid of a one dimensional acoustic bore.
double friction() const noexcept
Definition DuctLoss.hpp:91
double viscosity() const noexcept
Definition DuctLoss.hpp:92
std::vector< double > m_inverse_pivot
Definition DuctLoss.hpp:98
bool configure(const DuctGrid &grid, double friction, double viscosity)
Factor the loss for a grid.
Definition DuctLoss.cpp:57
void apply(std::span< double > velocity) const noexcept
Apply the loss to the velocities of a sample, in place.
Definition DuctLoss.cpp:101
Prepared implicit loss step for one duct grid.
Definition DuctLoss.hpp:67
double viscothermal_attenuation(double radius, double frequency, double sound_speed, double air_density) noexcept
Plane wave attenuation of a circular tube from its wall boundary layers.
Definition DuctLoss.cpp:23
std::pair< double, double > viscothermal_rates(double radius, double sound_speed, double air_density, double low_frequency, double high_frequency) noexcept
Friction and viscosity that match the tube's attenuation at two frequencies.
Definition DuctLoss.cpp:35
T velocity(const Memory::HistoryBuffer< T > &history, double dt) noexcept
First difference: rate of change of position.
Prepared grid and update gains of one bore.
Definition DuctGrid.hpp:66