modal_resonator.hpp

Go to the documentation of this file.

// sbl/dsp/pm/modal_resonator.hpp — A body as several resonances at one point (Physical modeling — composition)
//
// A real body is not one mass on one spring; it is many, and a string's
// bridge sees all of them at once. Driven at a point, the modes respond in
// parallel: each takes the same force scaled by its mode shape at that
// point, and the point's velocity is the weighted sum of what they do.
// Their admittances add:
//
//     Y(ω) = Σ w_i² · Y_i(ω)
//
// so a ModalResonator is a load exactly the way one MassSpringDamper is — it
// exposes the same instantaneous admittance g = Σ w_i² g_i, history
// h = Σ w_i h_i, and commit(F), and a LoadJunction scatters against it
// without knowing the difference. Each mode is passive; a sum of passive
// loads is passive (RPT-029 Part 4 rule 1).
//
// Modes are named the way a string feels them — where, how wide, how much
// they take (MassSpringDamper::set_resonance) — plus two shapes. The weight
// is the mode's shape at the bridge: 1 is a mode the bridge sits on the belly
// of, 0 is a node it cannot see. It sets how strongly the mode couples to the
// string, and so how much it can pull or break it. The radiation weight is
// the mode's shape where the sound is heard: it sets how present the mode is
// in radiated(), and nothing else. The two are independent on a real body,
// and keeping them apart is how a mode gets character without cost — weakly
// coupled, strongly heard (AP-036 addendum 2026-09-13: every partially
// matched mode at the bridge costs playability). Mode truncation is a design
// choice, not an error: a bank of one is the single body AP-036 started with.
//
// Usage:
//   sbl::dsp::pm::ModalResonator<8> body;
//   body.set_mode(0, 275.0f, 12.0f, 0.4f);              // where, how wide, how much
//   body.set_mode(1, 460.0f, 25.0f, 0.3f, 0.1f, 1.0f);  // barely coupled, fully heard
//   body.set_count(2);
//   sbl::dsp::pm::LoadJunction<sbl::dsp::pm::ModalResonator<8>> bridge(body);
 
#ifndef SBL_DSP_PM_MODAL_RESONATOR_HPP_
#define SBL_DSP_PM_MODAL_RESONATOR_HPP_
 
#include <cstdint>
 
#include <sbl/dsp/diagram/graph.hpp>
#include <sbl/dsp/math/clamp.hpp>
#include <sbl/dsp/pm/contracts.hpp>
#include <sbl/dsp/pm/mass_spring_damper.hpp>
 
namespace sbl::dsp::pm {
 
/// One resonance as a string feels it, its shape at the bridge, and its shape where it is heard.
struct Mode {
    float hz;
    float q;
    float match;
    float weight = 1.0f;    ///< coupling to the string at the bridge
    float radiate = 1.0f;   ///< presence in radiated()
};
 
template<uint8_t MaxModes = 8>
class ModalResonator {
    static_assert(MaxModes >= 1, "a resonator needs at least one mode");
 
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    static constexpr uint8_t MAX_MODES = MaxModes;
 
    ModalResonator() {
        for (uint8_t i = 0; i < MaxModes; ++i) {
            weight_[i] = 1.0f;
            radiate_[i] = 1.0f;
        }
        update();
    }
 
    /// Set one mode. Modes at or beyond count() are kept but silent.
    void set_mode(uint8_t index, float hz, float q, float match,
                  float weight = 1.0f, float radiate = 1.0f) {
        if (index >= MaxModes) return;
        modes_[index].set_resonance(hz, q, match);
        weight_[index] = math::clamp01(weight);
        radiate_[index] = math::clamp01(radiate);
        update();
    }
 
    /// Install a whole set; count is clamped to the bank's size.
    void set_modes(const Mode* modes, uint8_t count) {
        count_ = count < MaxModes ? count : MaxModes;
        for (uint8_t i = 0; i < count_; ++i) {
            modes_[i].set_resonance(modes[i].hz, modes[i].q, modes[i].match);
            weight_[i] = math::clamp01(modes[i].weight);
            radiate_[i] = math::clamp01(modes[i].radiate);
        }
        update();
    }
 
    /// How many of the modes are live.
    void set_count(uint8_t count) {
        count_ = count < MaxModes ? count : MaxModes;
        update();
    }
    uint8_t count() const { return count_; }
 
    const pm::MassSpringDamper& mode(uint8_t i) const { return modes_[i]; }
    float weight(uint8_t i) const { return weight_[i]; }
    float radiate(uint8_t i) const { return radiate_[i]; }
 
    // ─── The junction interface (parallel modes) ─────────────────────
 
    float admittance() const { return g_; }
 
    float history() const {
        float h = 0.0f;
        for (uint8_t i = 0; i < count_; ++i) h += weight_[i] * modes_[i].history();
        return h;
    }
 
    /// Apply this sample's force to every live mode; return the point velocity.
    float commit(float force) {
        float v = 0.0f;
        float heard = 0.0f;
        for (uint8_t i = 0; i < count_; ++i) {
            const float vi = modes_[i].commit(weight_[i] * force);
            v += weight_[i] * vi;
            heard += radiate_[i] * vi;
        }
        radiated_ = heard;
        return v;
    }
 
    /// What the body sounds like this sample: each mode's velocity by its radiation weight.
    float radiated() const { return radiated_; }
 
    /// Stored energy across the live modes, for passivity tests.
    float energy() const {
        float e = 0.0f;
        for (uint8_t i = 0; i < count_; ++i) e += modes_[i].energy();
        return e;
    }
 
    void reset() {
        for (uint8_t i = 0; i < MaxModes; ++i) modes_[i].reset();
        radiated_ = 0.0f;
    }
 
    /// One Load node per live mode, wired in parallel to a shared point. Never called from audio code (AP-037).
    diagram::Ports describe(diagram::Graph& g, uint8_t parent, const char* name = "resonator") const {
        diagram::Ports p;
        p.group = g.add_group(name, parent);
        p.in = p.out = g.add_node(diagram::Kind::Junction, "drive point", p.group);
        for (uint8_t i = 0; i < count_; ++i) {
            const diagram::Ports m = modes_[i].describe(g, p.group, "mode");
            g.add_edge(p.in, m.in, diagram::Wave::Force);
            g.add_edge(m.out, p.in, diagram::Wave::Velocity);
        }
        return p;
    }
 
private:
    /// NaN fails every comparison, so test the positive case: NaN reads as 0.
 
    /// The parallel admittance: weights squared, because the force each mode
    /// receives and the velocity it contributes are both scaled by its shape.
    void update() {
        g_ = 0.0f;
        for (uint8_t i = 0; i < count_; ++i) g_ += weight_[i] * weight_[i] * modes_[i].admittance();
    }
 
    pm::MassSpringDamper modes_[MaxModes];
    float weight_[MaxModes];
    float radiate_[MaxModes];
    uint8_t count_ = 1;
    float g_ = 0.0f;
    float radiated_ = 0.0f;
};
 
static_assert(is_load_v<ModalResonator<8>> && is_described_v<ModalResonator<8>>, "ModalResonator is a Load and describes itself (physical-modeling.md §4.1, §7)");
 
} // namespace sbl::dsp::pm
 
#endif // SBL_DSP_PM_MODAL_RESONATOR_HPP_