MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
DuctGrid.hpp
Go to the documentation of this file.
1#pragma once
2
3#include <expected>
4
5/**
6 * @file DuctGrid.hpp
7 * @brief Interleaved grid of a one dimensional acoustic bore.
8 *
9 * Pressure sits at N + 1 points and volume velocity at the N half points
10 * between them. Each pressure point owns the volume of the two half sections
11 * around it, so the compliance of a cell is its volume over rho c^2, and the
12 * end cells are half cells. The interior and end updates all draw their
13 * gains from the two arrays prepared here.
14 *
15 * Nothing here logs or reads a global sample rate; every value comes from
16 * the spec.
17 */
18
20
21/**
22 * @struct DuctSpec
23 * @brief Physical and sampling constants a grid is built from.
24 *
25 * mouth_volume is extra air behind the first cell in cubic metres, which adds
26 * compliance there. It stands for a mouthpiece cavity, or for the tip a
27 * truncated cone lacks, whose volume is pi r^2 x / 3 for the apex radius r and
28 * the distance x to the apex. Without it the modes of a truncated cone are
29 * stretched away from a whole number series.
30 */
31struct DuctSpec {
32 double length {};
33 double sample_rate {};
34 double sound_speed { 343.0 };
35 double air_density { 1.2 };
36 double mouth_volume { 0.0 };
37};
38
39/**
40 * @enum DuctError
41 * @brief Why no grid was built.
42 *
43 * INVALID_SPEC covers a length, rate, sound speed or density that is not
44 * positive and finite, or a grid beyond sixteen million intervals.
45 * INVALID_PROFILE covers a radius that is not positive and finite, or fewer
46 * than two samples. TOO_SHORT is a valid spec that gives fewer than two
47 * intervals.
48 */
54
55/**
56 * @struct DuctGrid
57 * @brief Prepared grid and update gains of one bore.
58 *
59 * With N = intervals, area and velocity_gain hold N values at the half points
60 * and pressure_gain holds N + 1 values at the pressure points.
61 * velocity_gain is k S / (rho h) and pressure_gain is rho c^2 k / V, with V the
62 * volume of the cell, for time step k and spacing h. courant is c k / h, at
63 * most one, and bandwidth is the highest frequency the grid carries,
64 * fs asin(courant) / pi.
65 */
66struct DuctGrid {
67 size_t intervals {};
68 double spacing {};
69 double time_step {};
70 double courant {};
71 double bandwidth {};
72 double start_radius {};
73 double end_radius {};
74 std::vector<double> area;
75 std::vector<double> velocity_gain;
76 std::vector<double> pressure_gain;
77};
78
79/**
80 * @brief Number of grid intervals a spec allows.
81 * @return floor(length / (c k)), the most that keeps c k / h at most one, or
82 * zero when the spec is invalid
83 */
84[[nodiscard]] MAYAFLUX_API size_t duct_intervals(const DuctSpec& spec) noexcept;
85
86/**
87 * @brief Build a grid from radii sampled evenly along the bore.
88 * @param spec Length, sample rate and air constants
89 * @param radii At least two radii, evenly spaced from the start to the end
90 * of the bore. They are linearly interpolated to the half points.
91 * @return The grid, or why none was built
92 *
93 * The grid spacing is length / N with N the largest count keeping the
94 * Courant number at most one. A length that is not a whole number of
95 * intervals leaves it a little under one, which lowers the bandwidth.
96 */
97[[nodiscard]] MAYAFLUX_API std::expected<DuctGrid, DuctError> make_duct_grid(
98 const DuctSpec& spec, std::span<const double> radii);
99
100namespace detail {
101
102 [[nodiscard]] MAYAFLUX_API std::expected<DuctGrid, DuctError> begin_duct_grid(const DuctSpec& spec);
103
104 [[nodiscard]] MAYAFLUX_API std::expected<DuctGrid, DuctError> finish_duct_grid(
105 DuctGrid grid, const DuctSpec& spec);
106
107}
108
109/**
110 * @brief Build a grid from a radius function of position.
111 * @param spec Length, sample rate and air constants
112 * @param radius Callable giving the radius in metres at a distance in metres
113 * from the start, evaluated at the half points and at both ends
114 * @return As the span overload
115 */
116template <typename Radius>
117 requires std::is_invocable_r_v<double, Radius&, double>
118[[nodiscard]] std::expected<DuctGrid, DuctError> make_duct_grid(const DuctSpec& spec, Radius radius)
119{
120 auto begun = detail::begin_duct_grid(spec);
121 if (!begun) {
122 return begun;
123 }
124
125 DuctGrid grid = std::move(*begun);
126 for (size_t l = 0; l < grid.intervals; ++l) {
127 const double r = radius((static_cast<double>(l) + 0.5) * grid.spacing);
128 grid.area[l] = std::numbers::pi * r * r;
129 }
130 grid.start_radius = radius(0.0);
131 grid.end_radius = radius(spec.length);
132
133 return detail::finish_duct_grid(std::move(grid), spec);
134}
135
136} // namespace MayaFlux::Kinesis::Acoustics
std::expected< DuctGrid, DuctError > finish_duct_grid(DuctGrid grid, const DuctSpec &spec)
Definition DuctGrid.cpp:58
std::expected< DuctGrid, DuctError > begin_duct_grid(const DuctSpec &spec)
Definition DuctGrid.cpp:36
size_t duct_intervals(const DuctSpec &spec) noexcept
Number of grid intervals a spec allows.
Definition DuctGrid.cpp:29
DuctError
Why no grid was built.
Definition DuctGrid.hpp:49
std::expected< DuctGrid, DuctError > make_duct_grid(const DuctSpec &spec, std::span< const double > radii)
Build a grid from radii sampled evenly along the bore.
Definition DuctGrid.cpp:90
std::vector< double > velocity_gain
Definition DuctGrid.hpp:75
std::vector< double > pressure_gain
Definition DuctGrid.hpp:76
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