load_junction.hpp

Go to the documentation of this file.

// sbl/dsp/pm/load_junction.hpp — Where the string meets its bridge (Physical modeling — composition)
//
// A waveguide's end is a rigid wall until something sits there. This is the
// something: a lumped load with a driving-point admittance, and the
// scattering of the string's velocity wave against it. Velocity at the
// junction is incoming plus reflected; the force the string exerts is their
// difference times the wave impedance, which the loop normalises to 1:
//
//     v_b = v_in + v_ref          F = v_in − v_ref = 2 v_in − v_b
//
// The load answers v_b = g F + h (see MassSpringDamper), so the junction is
// one algebraic solve — no delay-free loop, no iteration:
//
//     v_b = (2 Z g v_in + h) / (1 + Z g)      F = Z (2 v_in − v_b)      v_ref = v_b − v_in
//
// with Z the guide's wave impedance (1 unless set), so a load's g and h stay
// physical whatever guide it sits on.
//
// The limits are the checks: a load too heavy to move (g → 0, h → 0) gives
// v_ref = −v_in, the rigid wall the loop had before; a load too light to
// resist (g → ∞) gives v_b = 2 v_in and v_ref = +v_in, a free end. In
// between, where the body is easy to move the string's energy leaves into
// it — that partial decays faster — and where it resists, energy comes back
// with a phase shift that pulls the string's pitch. This is the mechanism a
// body adds; the load decides how much and where.
//
// Energy: the junction itself is lossless — what does not come back went
// into the load — and the load is passive, so the string cannot gain here
// (RPT-029 Part 4 rule 1).
//
// Usage:
//   sbl::dsp::pm::MassSpringDamper body;
//   sbl::dsp::pm::LoadJunction<sbl::dsp::pm::MassSpringDamper> bridge(body);
//   float out = loop.tick(bow, [&](float arriving) { return bridge.reflect(arriving); });
//   float radiated = bridge.load_velocity();
 
#ifndef SBL_DSP_PM_LOAD_JUNCTION_HPP_
#define SBL_DSP_PM_LOAD_JUNCTION_HPP_
 
#include <cstdint>
 
#include <sbl/dsp/diagram/graph.hpp>
#include <sbl/dsp/pm/contracts.hpp>
 
namespace sbl::dsp::pm {
 
/**
 * @brief The scattering junction between a waveguide and a lumped load
 *
 * @tparam Load anything with admittance(), history() and commit(force):
 *         the velocity it produces for a force, split into an instantaneous
 *         part and a history part.
 *
 * @note All public methods are ISR-safe — bounded computation, no I/O.
 */
template<typename Load>
class LoadJunction {
    static_assert(is_load_v<Load>, "LoadJunction needs a Load (physical-modeling.md §4.1)");
 
public:
    explicit LoadJunction(Load& load) : load_(load) {}
 
    /// The wave impedance of the guide this junction terminates: the load's g
    /// and h are physical, the waves are the guide's.
    void set_impedance(float z) { impedance_ = z > 0.0f ? z : 1.0f; }
    float impedance() const { return impedance_; }
 
    /**
     * @brief Scatter one sample: the wave arriving at the bridge in, the reflection out
     *
     * The force found here is committed to the load, so load_velocity() and
     * force() read this sample's values afterwards.
     */
    float reflect(float incoming) {
        const float g = load_.admittance();
        const float h = load_.history();
        const float zg = impedance_ * g;
        const float v_load = (TWO * zg * incoming + h) / (1.0f + zg);
        force_ = impedance_ * (TWO * incoming - v_load);
        v_load_ = load_.commit(force_);
        return v_load_ - incoming;
    }
 
    /// The body's velocity at the junction this sample — what it radiates, to first order.
    float load_velocity() const { return v_load_; }
 
    /// The force the string put into the body this sample.
    float force() const { return force_; }
 
    Load& load() { return load_; }
    const Load& load() const { return load_; }
 
    /// The junction stores nothing itself; what is behind it does.
    float energy() const { return load_.energy(); }
 
    void reset() {
        load_.reset();
        v_load_ = 0.0f;
        force_ = 0.0f;
    }
 
    /**
     * @brief The junction and its load, wired: force into the load, velocity back
     *
     * `in`/`out` are the junction (the guide side); the named port "load" is
     * the load, for a tap on what it radiates. Never called from audio code (AP-037).
     */
    diagram::Ports describe(diagram::Graph& g, uint8_t parent) const {
        diagram::Ports p;
        p.group = g.add_group("LoadJunction", parent);
        p.in = p.out = g.add_node(diagram::Kind::Junction, "load junction", p.group);
        const diagram::Ports load = load_.describe(g, p.group);
        g.add_edge(p.in, load.in, diagram::Wave::Force);
        g.add_edge(load.out, p.in, diagram::Wave::Velocity);
        p.add("load", load.out);
        return p;
    }
 
private:
    static constexpr float TWO = 2.0f;
 
    Load& load_;
    float impedance_ = 1.0f;
    float v_load_ = 0.0f;
    float force_ = 0.0f;
};
 
} // namespace sbl::dsp::pm
 
#endif // SBL_DSP_PM_LOAD_JUNCTION_HPP_