MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Reed.hpp
Go to the documentation of this file.
1#pragma once
2
4
5/**
6 * @file Reed.hpp
7 * @brief Quasi-static single reed and its same-sample coupling to the bore.
8 *
9 * The reed channel opens by H (1 - d / pM) for a mouth to bore pressure
10 * difference d, and shuts once d reaches the closing pressure pM. Through
11 * the opening the flow is Bernoulli:
12 *
13 * U(d) = w H (1 - d / pM) sign(d) sqrt(2 |d| / rho)
14 *
15 * It rises with d until a third of pM, then falls to zero at pM, and that
16 * falling part is what lets the bore drive the reed into oscillation.
17 *
18 * Coupled to the first cell of the bore the equation d + gain U(d) = target
19 * has a slope of infinity at d = 0 in d, which stalls Newton steps there.
20 * With s = sign(d) sqrt(|d|), so d = s |s|, the flow is a polynomial in s,
21 *
22 * s |s| + gain w H sqrt(2 / rho) s (1 - s |s| / pM) = target
23 *
24 * which is smooth through zero, and for either sign of the target the
25 * solution is held in an interval known beforehand, so the search is
26 * bracketed from its first step and typically needs two or three
27 * evaluations from the previous sample's solution.
28 */
29
31
32/**
33 * @struct ReedChannel
34 * @brief Geometry and constants of the reed channel.
35 */
37 double width {};
38 double rest_opening {};
40 double air_density { 1.2 };
41};
42
43/**
44 * @brief w H sqrt(2 / rho), the flow per unit of (1 - d / pM) sign(d) sqrt|d|.
45 */
46[[nodiscard]] MAYAFLUX_API double reed_flow_coefficient(const ReedChannel& reed) noexcept;
47
48/**
49 * @brief Volume velocity through the channel for a pressure difference.
50 * @param reed Channel
51 * @param difference Mouth pressure minus bore pressure
52 * @return Zero from the closing pressure up, and for a channel with any
53 * non-positive or non-finite field
54 */
55[[nodiscard]] MAYAFLUX_API double reed_flow(const ReedChannel& reed, double difference) noexcept;
56
57/**
58 * @brief Whether a coupling gain keeps the solution unique.
59 * @param reed Channel
60 * @param gain From flow_coupling_gain
61 * @return True while gain times the flow coefficient stays under the root of
62 * the closing pressure, which is zeta lambda under one
63 *
64 * Past it the coupling can have more than one solution, and the one found
65 * depends on the previous sample's. Check it whenever the channel, the
66 * length or the sample rate changes.
67 */
68[[nodiscard]] MAYAFLUX_API bool reed_coupling_is_unique(const ReedChannel& reed, double gain) noexcept;
69
70/**
71 * @brief Couple the reed to the first cell of the bore for one sample.
72 * @param reed Channel
73 * @param warm_start Root of |d| from the previous sample, updated here; start
74 * it at zero. The search begins at the end of its bracket from which
75 * Newton steps approach the root monotonically, which is every case
76 * but a root straddling the inflection of the equation, where it
77 * begins here.
78 * @param end_pressure_gain Gain of the first pressure point from DuctGrid
79 * @param mouth_pressure Blowing pressure at the half step
80 * @param end_pressure Pressure of the first point at the start of the sample
81 * @param downstream_flow Volume velocity of the first half section, from the
82 * same sample
83 * @return The first point's pressure after the sample, the flow into the bore
84 * at the half step, the pressure difference across the reed, and how
85 * the search ended
86 *
87 * A reed shut by the mouth pressure acts as a wall. A channel with a field
88 * that is not positive and finite does the same and reports NOT_FINITE.
89 * The result is the one solution only while reed_coupling_is_unique holds
90 * for the coupling gain, flow_coupling_gain of end_pressure_gain.
91 */
92[[nodiscard]] MAYAFLUX_API std::tuple<double, double, double, RootStatus> reed_mouth_step(
93 const ReedChannel& reed,
94 double& warm_start,
95 double end_pressure_gain,
96 double mouth_pressure,
97 double end_pressure,
98 double downstream_flow) noexcept;
99
100/**
101 * @brief Couple a reed with its own dynamics to the first cell of the bore.
102 * @param reed Channel. closing_pressure sets the static compliance, so the
103 * reed settles at H (1 - d / pM) under a steady difference d.
104 * @param resonance Resonance of the reed in Hz, positive
105 * @param damping Damping of the reed in 1/s, not negative
106 * @param reed_area Effective area in square metres over which the reed moves
107 * air, not negative; zero leaves the reed's own flow out
108 * @param time_step Time step in seconds
109 * @param motion Displacement of the reed from rest, then the previous one, in
110 * metres, updated here; start both at zero
111 * @param end_pressure_gain Gain of the first pressure point from DuctGrid
112 * @param mouth_pressure Blowing pressure at the half step
113 * @param end_pressure Pressure of the first point at the start of the sample
114 * @param downstream_flow Volume velocity of the first half section, from the
115 * same sample
116 * @return The first point's pressure after the sample, the flow into the bore
117 * at the half step, and the pressure difference across the reed
118 *
119 * The reed is a damped oscillator, y'' + damping y' + w0^2 y = -w0^2 H d / pM,
120 * stepped by a centred scheme that is stable for any step. The opening during
121 * a sample is the one the previous sample left, which makes the coupling an
122 * exact closed form, s |s| + a s = target with s = sign(d) sqrt|d|, solved by
123 * its stable root. The solution is unique for every parameter, with no
124 * condition to check. The lag is half a sample, small beside the period of a
125 * reed resonance. A reed driven past the lay is held there without bouncing.
126 * With a reed_area the moving reed also pushes air, a flow of -reed_area times
127 * its velocity into the bore, which is added to the flow returned and enters
128 * the coupling like any other known flow (Avanzini and Rocchesso). An invalid
129 * channel or resonance acts as a wall.
130 */
131[[nodiscard]] MAYAFLUX_API std::tuple<double, double, double> dynamic_reed_mouth_step(
132 const ReedChannel& reed,
133 double resonance,
134 double damping,
135 double reed_area,
136 double time_step,
137 std::array<double, 2>& motion,
138 double end_pressure_gain,
139 double mouth_pressure,
140 double end_pressure,
141 double downstream_flow) noexcept;
142
143} // namespace MayaFlux::Kinesis::Acoustics
Same-sample coupling of an end cell to a flow that depends on the pressure across it.
std::tuple< double, double, double, RootStatus > reed_mouth_step(const ReedChannel &reed, double &warm_start, double end_pressure_gain, double mouth_pressure, double end_pressure, double downstream_flow) noexcept
Couple the reed to the first cell of the bore for one sample.
Definition Reed.cpp:43
double reed_flow_coefficient(const ReedChannel &reed) noexcept
w H sqrt(2 / rho), the flow per unit of (1 - d / pM) sign(d) sqrt|d|.
Definition Reed.cpp:20
std::tuple< double, double, double > dynamic_reed_mouth_step(const ReedChannel &reed, double resonance, double damping, double reed_area, double time_step, std::array< double, 2 > &motion, double end_pressure_gain, double mouth_pressure, double end_pressure, double downstream_flow) noexcept
Couple a reed with its own dynamics to the first cell of the bore.
Definition Reed.cpp:111
double reed_flow(const ReedChannel &reed, double difference) noexcept
Volume velocity through the channel for a pressure difference.
Definition Reed.cpp:25
bool reed_coupling_is_unique(const ReedChannel &reed, double gain) noexcept
Whether a coupling gain keeps the solution unique.
Definition Reed.cpp:38
Geometry and constants of the reed channel.
Definition Reed.hpp:36