MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
StaggeredLine.hpp
Go to the documentation of this file.
1#pragma once
2
3/**
4 * @file StaggeredLine.hpp
5 * @brief Interior propagation of a bore on its interleaved grid, with the
6 * discrete energy and a pickup.
7 *
8 * Pressure p^n lives at integer steps and volume velocity u^(n+1/2) at half
9 * steps, so one sample is: advance_velocity from the current pressure, then
10 * the end cells, then advance_pressure for the interior. The end cells are
11 * updated by an end law, which is where a reed, a wall or a radiation load
12 * acts. Nothing here allocates, and every function runs over spans the
13 * caller owns.
14 *
15 * With a Courant number of one the interior is exact for a cylinder.
16 * Below one it adds numerical dispersion and lowers the bandwidth, and it
17 * stays stable for any Courant number up to one.
18 */
19
21
22/**
23 * @brief Advance the half step velocities from the pressure.
24 * @param velocity N volume velocities, updated in place
25 * @param pressure N + 1 pressures at the start of the sample
26 * @param velocity_gain N gains from DuctGrid
27 *
28 * Each velocity falls by its gain times the pressure rise across it.
29 */
30MAYAFLUX_API void advance_velocity(
31 std::span<double> velocity,
32 std::span<const double> pressure,
33 std::span<const double> velocity_gain) noexcept;
34
35/**
36 * @brief Advance the interior pressures from the new velocities.
37 * @param pressure N + 1 pressures, points 1 to N - 1 updated in place
38 * @param velocity N volume velocities from advance_velocity
39 * @param pressure_gain N + 1 gains from DuctGrid
40 *
41 * The two end points are left alone for the end laws.
42 */
43MAYAFLUX_API void advance_pressure(
44 std::span<double> pressure,
45 std::span<const double> velocity,
46 std::span<const double> pressure_gain) noexcept;
47
48/**
49 * @brief New pressure of an end cell from the flow into it.
50 * @param pressure Pressure of the cell
51 * @param pressure_gain Gain of the cell from DuctGrid
52 * @param net_inflow Flow in through one face minus flow out through the other
53 *
54 * With no flow through the outer face this is a rigid wall: pass only the
55 * flow arriving from the neighbouring half section.
56 */
57[[nodiscard]] constexpr double end_cell_pressure(double pressure, double pressure_gain, double net_inflow) noexcept
58{
59 return pressure + pressure_gain * net_inflow;
60}
61
62/**
63 * @brief Discrete energy of the bore in joules.
64 * @param pressure N + 1 pressures at step n
65 * @param velocity_previous N velocities at step n - 1/2
66 * @param velocity_current N velocities at step n + 1/2
67 * @param pressure_gain N + 1 gains from DuctGrid
68 * @param velocity_gain N gains from DuctGrid
69 * @param time_step Time step in seconds
70 *
71 * The sum of cell compliance times pressure squared and section inertance
72 * times the product of the velocities at the two time levels, each halved.
73 * With sealed ends it is constant to rounding from sample to sample, and
74 * with lossy ends it only falls. It is not negative while the Courant number
75 * is at most one.
76 */
77[[nodiscard]] MAYAFLUX_API double discrete_energy(
78 std::span<const double> pressure,
79 std::span<const double> velocity_previous,
80 std::span<const double> velocity_current,
81 std::span<const double> pressure_gain,
82 std::span<const double> velocity_gain,
83 double time_step) noexcept;
84
85/**
86 * @brief Pressure at a position along the bore, linearly interpolated.
87 * @param pressure N + 1 pressures
88 * @param position Fraction of the length, clamped to 0 to 1
89 * @return Zero for an empty span
90 */
91[[nodiscard]] MAYAFLUX_API double sample_pressure(std::span<const double> pressure, double position) noexcept;
92
93/**
94 * @brief Linearly interpolate a line of values onto another of a different size
95 * by relative position.
96 * @param source Values on the old line
97 * @param target Receives the values on the new line, every element is written
98 * @param offset Where the first value sits in units of the spacing: 0 for the
99 * N + 1 pressures, which lie on the grid points, and 0.5 for the N
100 * velocities, which lie on the half points
101 *
102 * The i-th of m values lies at (i + offset) / (m - 1 + 2 offset) of the
103 * length. Positions outside the source are clamped to its ends. An empty
104 * source leaves the target zero. Allocates nothing.
105 */
106MAYAFLUX_API void resample_line(
107 std::span<const double> source,
108 std::span<double> target,
109 double offset = 0.0) noexcept;
110
111} // namespace MayaFlux::Kinesis::Acoustics
void resample_line(std::span< const double > source, std::span< double > target, double offset) noexcept
Linearly interpolate a line of values onto another of a different size by relative position.
void advance_velocity(std::span< double > velocity, std::span< const double > pressure, std::span< const double > velocity_gain) noexcept
Advance the half step velocities from the pressure.
double sample_pressure(std::span< const double > pressure, double position) noexcept
Pressure at a position along the bore, linearly interpolated.
void advance_pressure(std::span< double > pressure, std::span< const double > velocity, std::span< const double > pressure_gain) noexcept
Advance the interior pressures from the new velocities.
constexpr double end_cell_pressure(double pressure, double pressure_gain, double net_inflow) noexcept
New pressure of an end cell from the flow into it.
double discrete_energy(std::span< const double > pressure, std::span< const double > velocity_previous, std::span< const double > velocity_current, std::span< const double > pressure_gain, std::span< const double > velocity_gain, double time_step) noexcept
Discrete energy of the bore in joules.
T velocity(const Memory::HistoryBuffer< T > &history, double dt) noexcept
First difference: rate of change of position.