MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
TerminationOperators.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "NetworkOperator.hpp"
4
10
12
13/**
14 * @enum DuctEnd
15 * @brief Which end of a duct an operator terminates.
16 */
17enum class DuctEnd : uint8_t {
20};
21
22/**
23 * @class TerminationOperator
24 * @brief What closes one end of a DuctNetwork: a wall, a reed, a radiating
25 * opening, or any pressure dependent flow.
26 *
27 * A termination couples the end cell to a flow within the same sample, which a
28 * per-block process() cannot do, so it has a per-sample couple() that the
29 * network calls directly. process() is left for block housekeeping.
30 *
31 * Both ends are described in their own inward frame: interior_flow is the
32 * volume velocity leaving the end cell into the duct, and the returned flow is
33 * the volume velocity entering the duct through the end face. One operator
34 * therefore serves either end, and a bell that radiates reports a negative
35 * inflow while sound leaves.
36 *
37 * Parameters are atomics or set between blocks. couple() runs on the audio
38 * thread, and so does any callable an operator holds. Replacing an operator on
39 * a network happens outside process_batch(), through the network.
40 */
41class MAYAFLUX_API TerminationOperator : public NetworkOperator {
42public:
43 /**
44 * @brief Whether prepare would succeed for this grid and end.
45 * @note Safe from any thread, and does not change the operator.
46 */
47 [[nodiscard]] virtual bool accepts(
50 DuctEnd end) const
51 = 0;
52
53 /**
54 * @brief Bind to a grid and end, and reset the state.
55 * @note Allocates nothing. Called by the network on the audio thread when
56 * a grid is installed, after accepts returned true.
57 */
58 virtual void prepare(
61 DuctEnd end)
62 = 0;
63
64 /**
65 * @brief Bind to a new grid of the same duct while it keeps sounding.
66 * @note Allocates nothing. Called instead of prepare when the shape,
67 * losses or mouth volume change, so a slide of length does not
68 * restart the sound. The default is prepare, which resets.
69 */
70 virtual void retarget(
73 DuctEnd end)
74 {
75 prepare(grid, spec, end);
76 }
77
78 /**
79 * @brief Advance the end cell and its coupling by one sample.
80 * @param end_pressure Pressure of the end cell at the start of the sample
81 * @param interior_flow Volume velocity leaving the end cell into the duct,
82 * from the same sample
83 * @return The end pressure after the sample, then the volume velocity
84 * entering the duct through the end face
85 */
86 [[nodiscard]] virtual std::pair<double, double> couple(double end_pressure, double interior_flow) = 0;
87
88 /** @brief Clear the state, keeping the parameters. */
89 virtual void reset() { }
90
91 void process(float /*frames*/) override { }
92 void set_parameter(std::string_view /*param*/, double /*value*/) override { }
93 [[nodiscard]] std::optional<double> query_state(std::string_view /*query*/) const override { return std::nullopt; }
94};
95
96/**
97 * @class WallOperator
98 * @brief A rigid closed end: no flow through the face.
99 */
100class MAYAFLUX_API WallOperator final : public TerminationOperator {
101public:
102 [[nodiscard]] bool accepts(const Kinesis::Acoustics::DuctGrid& grid,
103 const Kinesis::Acoustics::DuctSpec& spec, DuctEnd end) const override;
104 void prepare(const Kinesis::Acoustics::DuctGrid& grid,
105 const Kinesis::Acoustics::DuctSpec& spec, DuctEnd end) override;
106 [[nodiscard]] std::pair<double, double> couple(double end_pressure, double interior_flow) override;
107 [[nodiscard]] std::string_view get_type_name() const override { return "Wall"; }
108
109private:
110 double m_end_gain {};
111};
112
113/**
114 * @struct ReedControls
115 * @brief Controls of a ReedOperator, each a number or a mapped node.
116 *
117 * Each is checked as the parameter of the same name always was: non negative
118 * where it cannot be negative, lip between 0 and 1, and closing_pressure,
119 * opening and width only when positive. A value that fails is left out. A
120 * network source is per element and is not used.
121 */
135
137
138/**
139 * @struct JunctionControls
140 * @brief Controls of a JunctionOperator, each a number or a mapped node.
141 *
142 * maximum_flow is only taken when positive.
143 */
148
150
151/**
152 * @class ReedOperator
153 * @brief Quasi-static single reed driven by a blowing pressure.
154 *
155 * Parameters: "pressure" (Pa, smoothed per sample), "closing_pressure",
156 * "opening", "width" and "smoothing" (seconds of the blowing pressure's
157 * one pole smoothing, zero for none). query_state also answers "unique": 1
158 * while the coupling has a single solution for the current values, which is
159 * checked at the start of each block. When it is 0 the solution follows the
160 * branch of the previous sample.
161 *
162 * Four more give the reed a life of its own. "resonance" (Hz) turns the
163 * rigid reed into a damped oscillator at that frequency, with "reed_damping"
164 * (1/s, 15000 by default) as its loss; zero resonance, the default, keeps the
165 * quasi-static reed. A reed with dynamics puts a formant at its resonance,
166 * shapes the attack, and is unique for every value. With the damping below
167 * about 5000 and a resonance near 2500 the reed sustains its own oscillation,
168 * a squeal near the resonance, instead of the note of the duct.
169 *
170 * "reed_area" (m^2, zero by default) adds the air the moving reed pushes,
171 * minus that area times the reed's velocity, to the flow into the duct;
172 * 1.46e-4 is the value used by Avanzini and Rocchesso for a clarinet. "lip"
173 * (0 to 1) is the embouchure, a lip pressed against the reed: at 1 the rest
174 * opening is reduced by a fifth, the resonance and the closing pressure rise by
175 * 40 percent and the damping doubles. A narrower opening lowers the loop gain,
176 * so a note near its threshold goes quiet as the lip closes unless the blowing
177 * pressure rises with it.
178 * The coefficients are a first approximation.
179 *
180 * "noise" is the breath: an extra flow into the duct, with an rms of that
181 * fraction of the reed's own flow, so it swells and fades with the note and is
182 * silent when the reed is shut. Its colour is a one pole low-pass at
183 * "noise_cutoff" (Hz, 3000 by default). A few hundredths is a hint of breath,
184 * a few tenths a breathy note. The noise is a fixed, repeatable sequence.
185 */
186class MAYAFLUX_API ReedOperator final : public TerminationOperator {
187public:
189
190 explicit ReedOperator(double width = 0.012, double rest_opening = 4.0e-4, double closing_pressure = 3000.0);
191
192 [[nodiscard]] bool accepts(const Kinesis::Acoustics::DuctGrid& grid,
193 const Kinesis::Acoustics::DuctSpec& spec, DuctEnd end) const override;
194 void prepare(const Kinesis::Acoustics::DuctGrid& grid,
195 const Kinesis::Acoustics::DuctSpec& spec, DuctEnd end) override;
196 void retarget(const Kinesis::Acoustics::DuctGrid& grid,
197 const Kinesis::Acoustics::DuctSpec& spec, DuctEnd end) override;
198 [[nodiscard]] std::pair<double, double> couple(double end_pressure, double interior_flow) override;
199 void reset() override;
200
201 void process(float frames) override;
202 void set_parameter(std::string_view param, double value) override;
203 [[nodiscard]] std::optional<double> query_state(std::string_view query) const override;
204 [[nodiscard]] std::string_view get_type_name() const override { return "Reed"; }
205
206 /** @brief Fills every control with the value the reed holds now. */
207 void read_controls(ReedControls& controls) const;
208
209private:
211
212 void apply_controls();
213
214 [[nodiscard]] Kinesis::Acoustics::ReedChannel channel() const noexcept;
215 [[nodiscard]] double next_white() noexcept;
216
217 std::atomic<double> m_target_pressure { 0.0 };
218 std::atomic<double> m_width;
219 std::atomic<double> m_rest_opening;
220 std::atomic<double> m_closing_pressure;
221 std::atomic<double> m_smoothing { 0.005 };
222 std::atomic<double> m_resonance { 0.0 };
223 std::atomic<double> m_reed_damping { 15000.0 };
224 std::atomic<double> m_noise { 0.0 };
225 std::atomic<double> m_noise_cutoff { 3000.0 };
226 std::atomic<double> m_reed_area { 0.0 };
227 std::atomic<double> m_lip { 0.0 };
228 std::atomic<bool> m_unique { true };
229
230 double m_end_gain {};
231 double m_density { 1.2 };
232 double m_time_step {};
233 double m_alpha { 1.0 };
234 double m_noise_alpha { 1.0 };
235 double m_noise_scale { 1.0 };
236 double m_noise_state {};
237 double m_last_flow {};
238 double m_pressure {};
239 double m_warm_start {};
240 std::array<double, 2> m_motion {};
241 uint64_t m_random { 0x9E3779B97F4A7C15ULL };
242};
243
244/**
245 * @class RadiationOperator
246 * @brief An open end radiating into free space, as a passive second order load.
247 */
248class MAYAFLUX_API RadiationOperator final : public TerminationOperator {
249public:
250 /**
251 * @param model Network constants, unflanged by default
252 */
253 explicit RadiationOperator(
255
256 [[nodiscard]] bool accepts(const Kinesis::Acoustics::DuctGrid& grid,
257 const Kinesis::Acoustics::DuctSpec& spec, DuctEnd end) const override;
258 void prepare(const Kinesis::Acoustics::DuctGrid& grid,
259 const Kinesis::Acoustics::DuctSpec& spec, DuctEnd end) override;
260 void retarget(const Kinesis::Acoustics::DuctGrid& grid,
261 const Kinesis::Acoustics::DuctSpec& spec, DuctEnd end) override;
262 [[nodiscard]] std::pair<double, double> couple(double end_pressure, double interior_flow) override;
263 void reset() override;
264
265 [[nodiscard]] std::string_view get_type_name() const override { return "Radiation"; }
266
267private:
268 [[nodiscard]] std::optional<Kinesis::Acoustics::RadiationCoefficients> coefficients_for(
271 DuctEnd end) const;
272
276 double m_end_gain {};
277 bool m_ready { false };
278};
279
280/**
281 * @class JunctionOperator
282 * @brief Any flow that depends on the pressure difference across it.
283 *
284 * The flow law maps a pressure difference, driving pressure minus end
285 * pressure, to a FlowSample of flow and slope. It runs on the audio thread
286 * and must not throw. The law must make d + gain * flow(d) increasing, and
287 * its flow must stay within maximum_flow, which sets the bracket of the
288 * solve. Parameters: "driving_pressure" and "maximum_flow". query_state
289 * "status" answers the last solve's RootStatus as a number.
290 */
291class MAYAFLUX_API JunctionOperator final : public TerminationOperator {
292public:
293 using FlowLaw = std::function<Kinesis::Acoustics::FlowSample(double)>;
294
295 /**
296 * @param law Flow and slope for a pressure difference
297 * @param maximum_flow Largest flow magnitude the law can give
298 * @param driving_pressure Pressure on the far side of the junction
299 */
301
302 JunctionOperator(FlowLaw law, double maximum_flow, double driving_pressure = 0.0);
303
304 [[nodiscard]] bool accepts(const Kinesis::Acoustics::DuctGrid& grid,
305 const Kinesis::Acoustics::DuctSpec& spec, DuctEnd end) const override;
306 void prepare(const Kinesis::Acoustics::DuctGrid& grid,
307 const Kinesis::Acoustics::DuctSpec& spec, DuctEnd end) override;
308 void retarget(const Kinesis::Acoustics::DuctGrid& grid,
309 const Kinesis::Acoustics::DuctSpec& spec, DuctEnd end) override;
310 [[nodiscard]] std::pair<double, double> couple(double end_pressure, double interior_flow) override;
311 void reset() override;
312
313 void process(float frames) override;
314 void set_parameter(std::string_view param, double value) override;
315 [[nodiscard]] std::optional<double> query_state(std::string_view query) const override;
316 [[nodiscard]] std::string_view get_type_name() const override { return "Junction"; }
317
318 /** @brief Fills every control with the value the junction holds now. */
319 void read_controls(JunctionControls& controls) const;
320
321private:
323
324 void apply_controls();
325
327 std::atomic<double> m_maximum_flow;
328 std::atomic<double> m_driving_pressure;
329 std::atomic<uint8_t> m_status { 0 };
330
331 double m_end_gain {};
332 double m_guess {};
333};
334
335} // namespace MayaFlux::Nodes::Network
#define MF_DESCRIBE(...)
Requests a generated member description for a struct at namespace scope.
Definition Describe.hpp:14
Interleaved grid of a one dimensional acoustic bore.
Same-sample coupling of an end cell to a flow that depends on the pressure across it.
Open end of a bore as a passive second order radiation load.
Quasi-static single reed and its same-sample coupling to the bore.
Interior propagation of a bore on its interleaved grid, with the discrete energy and a pickup.
One named control of a network or operator: empty, a value, or a mapped source.
Definition Control.hpp:34
void prepare(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end) override
Bind to a grid and end, and reset the state.
std::function< Kinesis::Acoustics::FlowSample(double)> FlowLaw
void reset() override
Clear the state, keeping the parameters.
void set_parameter(std::string_view param, double value) override
Set operator parameter.
std::string_view get_type_name() const override
Type name for introspection.
void retarget(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end) override
Bind to a new grid of the same duct while it keeps sounding.
std::pair< double, double > couple(double end_pressure, double interior_flow) override
Advance the end cell and its coupling by one sample.
std::optional< double > query_state(std::string_view query) const override
Query operator internal state.
JunctionOperator(FlowLaw law, double maximum_flow, double driving_pressure=0.0)
void process(float frames) override
Process for one batch cycle.
bool accepts(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end) const override
Whether prepare would succeed for this grid and end.
Domain-agnostic interpretive lens for network processing.
Kinesis::Acoustics::RadiationCoefficients m_coefficients
void prepare(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end) override
Bind to a grid and end, and reset the state.
std::pair< double, double > couple(double end_pressure, double interior_flow) override
Advance the end cell and its coupling by one sample.
void retarget(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end) override
Bind to a new grid of the same duct while it keeps sounding.
void reset() override
Clear the state, keeping the parameters.
std::string_view get_type_name() const override
Type name for introspection.
bool accepts(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end) const override
Whether prepare would succeed for this grid and end.
RadiationOperator(Kinesis::Acoustics::RadiationModel model=Kinesis::Acoustics::unflanged_radiation)
void retarget(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end) override
Bind to a new grid of the same duct while it keeps sounding.
std::string_view get_type_name() const override
Type name for introspection.
std::optional< double > query_state(std::string_view query) const override
Query operator internal state.
void set_parameter(std::string_view param, double value) override
Set operator parameter.
void prepare(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end) override
Bind to a grid and end, and reset the state.
ReedOperator(double width=0.012, double rest_opening=4.0e-4, double closing_pressure=3000.0)
void reset() override
Clear the state, keeping the parameters.
void process(float frames) override
Process for one batch cycle.
std::pair< double, double > couple(double end_pressure, double interior_flow) override
Advance the end cell and its coupling by one sample.
bool accepts(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end) const override
Whether prepare would succeed for this grid and end.
Kinesis::Acoustics::ReedChannel channel() const noexcept
virtual void reset()
Clear the state, keeping the parameters.
virtual std::pair< double, double > couple(double end_pressure, double interior_flow)=0
Advance the end cell and its coupling by one sample.
void process(float) override
Process for one batch cycle.
std::optional< double > query_state(std::string_view) const override
Query operator internal state.
virtual void prepare(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end)=0
Bind to a grid and end, and reset the state.
virtual bool accepts(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end) const =0
Whether prepare would succeed for this grid and end.
virtual void retarget(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end)
Bind to a new grid of the same duct while it keeps sounding.
void set_parameter(std::string_view, double) override
Set operator parameter.
What closes one end of a DuctNetwork: a wall, a reed, a radiating opening, or any pressure dependent ...
bool accepts(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end) const override
Whether prepare would succeed for this grid and end.
void prepare(const Kinesis::Acoustics::DuctGrid &grid, const Kinesis::Acoustics::DuctSpec &spec, DuctEnd end) override
Bind to a grid and end, and reset the state.
std::pair< double, double > couple(double end_pressure, double interior_flow) override
Advance the end cell and its coupling by one sample.
std::string_view get_type_name() const override
Type name for introspection.
A rigid closed end: no flow through the face.
std::array< double, 3 > RadiationModel
The three dimensionless constants of the radiation network, as gamma, lambda and theta.
Definition Radiation.hpp:34
constexpr RadiationModel unflanged_radiation
Unflanged circular pipe, end correction 0.6133 a.
Definition Radiation.hpp:54
std::pair< double, double > FlowSample
Flow through a coupling, then its slope against the pressure difference.
DuctEnd
Which end of a duct an operator terminates.
Prepared grid and update gains of one bore.
Definition DuctGrid.hpp:66
Physical and sampling constants a grid is built from.
Definition DuctGrid.hpp:31
Prepared coefficients of one end, built once per bore or step change.
Definition Radiation.hpp:75
Inductor flow and branch pressure, zero at rest.
Definition Radiation.hpp:89
Geometry and constants of the reed channel.
Definition Reed.hpp:36
Controls of a JunctionOperator, each a number or a mapped node.
Controls of a ReedOperator, each a number or a mapped node.