string_base.hpp

Go to the documentation of this file.

// sbl/dsp/pm/string_base.hpp — What every string widget is made of (Physical modeling — widget base)
//
// A StringLoop between an exciter and a load, with the ports a string owns —
// pitch, position, damping, and what is heard — smoothed and applied at
// block rate; the non-finite guard; the pickup mix ramp; reset and describe.
// The exciter and the load are taken by reference, the way LoadJunction
// takes its load: the string knows what it is played with and terminated on
// only through the contracts (RPT-036; Michael, 2026-09-17: a base class for
// strings). A concrete string — BowedString — is this plus a name and the
// wiring it wants to draw.
//
// Every port is a signal unit and the widget owns the mapping. All ports are
// smoothed at block rate inside process(), advanced by the block length,
// never by an assumed call rate (ADR-011). Setters only store, so a setter
// and process() can run in different contexts without a half-updated loop.
//
// ## Pitch
//
// set_pitch_su maps as math::note_of_su: 0..1 across C1..C9. The loss filter's
// delay is not compensated, so the string plays somewhat flat, more so when
// dark and high (StringLoop, AP-032 addendum 2026-09-12). The loop's shortest
// period is StringLoop::MIN_PERIOD, so the top of the range plays that.
//
// ## End b: a load, or a wall (AP-036)
//
// With the load in use the loop's end b is a LoadJunction scattering the
// string against it — a resonator, one mode or many — so energy leaks into
// it near its resonances and the string's pitch is pulled by them. Without
// (use_load(false)) end b is a rigid wall and the string is the bare one.
//
// ## Output
//
// With the load in use, the output is a crossfade between two taps, set by
// the pickup port: 0 is what the load radiates, 1 is the string's velocity
// arriving at end b, the bare string. The mix only chooses what is heard.
// Neither tap is held to [-1, 1]; level and DC are the application's.
//
// ## Safety
//
// A non-finite sample anywhere in a block resets the string rather than
// recirculating forever (BlockGuard). The exciter's own limiter is the
// exciter's business (Bow).
 
#ifndef SBL_DSP_PM_STRING_BASE_HPP_
#define SBL_DSP_PM_STRING_BASE_HPP_
 
#include <cmath>
#include <cstdint>
#include <initializer_list>
 
#include <sbl/dsp/diagram/graph.hpp>
#include <sbl/dsp/math/clamp.hpp>
#include <sbl/dsp/math/pitch.hpp>
#include <sbl/dsp/pm/contracts.hpp>
#include <sbl/dsp/pm/load_junction.hpp>
#include <sbl/dsp/pm/string_loop.hpp>
#include <sbl/dsp/primitives/block_guard.hpp>
#include <sbl/dsp/primitives/crossfade_ramp.hpp>
#include <sbl/dsp/primitives/smoothed_port.hpp>
#include <sbl/dsp/types/fixed.hpp>
 
namespace sbl::dsp::pm {
 
/**
 * @tparam Exciter   what plays the string (contracts.hpp: Exciter)
 * @tparam Load      what end b terminates on (contracts.hpp: Load)
 * @tparam MaxPeriod longest loop in samples, which sets the lowest pitch.
 *         The default covers C1 at 48 kHz (a 1469-sample period); each of
 *         the two segments gets a buffer this size. The widget owns its
 *         buffers: it is the black box, the loop inside it is not.
 *
 * @note All public methods are ISR-safe — bounded computation, no I/O.
 */
template<typename Exciter, typename Load, uint16_t MaxPeriod = 1536>
class StringBase {
    static_assert(MaxPeriod >= 64, "a string needs room to ring");
    static_assert(is_exciter_v<Exciter>, "the string is played by an Exciter (physical-modeling.md §4.2)");
    static_assert(is_load_v<Load>, "end b terminates on a Load (physical-modeling.md §4.1)");
 
public:
    // Port defaults: C4, a junction that plays the fundamental.
    static constexpr float DEFAULT_PITCH_SU = 0.375f;
    static constexpr float DEFAULT_POSITION_SU = 0.556f;   ///< junction 0.3
    static constexpr float DEFAULT_DAMPING_SU = 0.6f;
    static constexpr float DEFAULT_PICKUP_SU = 0.0f;       ///< all load
 
    StringBase(Exciter& exciter, Load& load, const char* name = "String")
        : name_(name), exciter_(exciter), load_(load), end_b_(load) {
        loop_.init(buf_a_, MaxPeriod, buf_b_, MaxPeriod);
        loop_.set_loop_gain(LOOP_GAIN);
        pitch_.set(DEFAULT_PITCH_SU);
        position_.set(DEFAULT_POSITION_SU);
        damping_.set(DEFAULT_DAMPING_SU);
        pickup_.set(DEFAULT_PICKUP_SU);
        reset();
    }
 
    // ─── Structural parameters ───────────────────────────────────────
 
    /// End b terminates on the load (true) or on a wall (false). The junction starts at rest.
    void use_load(bool on) {
        loaded_ = on;
        end_b_.reset();
    }
    bool loaded() const { return loaded_; }
 
    /// The parts, for whoever owns them and for tools.
    Exciter& exciter() { return exciter_; }
    Load& load() { return load_; }
    const StringLoop& loop() const { return loop_; }
    const LoadJunction<Load>& end_b() const { return end_b_; }
 
    // ─── Ports ───────────────────────────────────────────────────────
 
    /// Pitch across C1..C9 (math::note_of_su). Smoothed.
    void set_pitch_su(float su) { pitch_.set(math::clamp01(su)); }
 
    /**
     * @brief Where the exciter sits along the string
     *
     * 0 is near an end, 1 is the middle. Positions mirror about the middle,
     * so this spans the distinct ones. Near an end the string locks onto
     * upper modes — an octave or more up — which is the real instrument's
     * behaviour, not a fault (AP-032 Phase 1 finding 3). Smoothed.
     */
    void set_position_su(float su) { position_.set(math::clamp01(su)); }
 
    /// Loss filter cutoff: how fast the high partials give up. Smoothed.
    void set_damping_su(float su) { damping_.set(math::clamp01(su)); }
 
    /**
     * @brief What is heard: 0 the load, 1 the bare string, a crossfade between
     *
     * Smoothed and ramped across each block, so turning it never steps. It
     * changes the output only, not the string. Without the load it has no effect.
     */
    void set_pickup_su(float su) { pickup_.set(math::clamp01(su)); }
 
    // ─── Processing ──────────────────────────────────────────────────
 
    void process(float* out, uint16_t n) {
        if (n == 0) return;
 
        exciter_.advance(n);
        update_period(pitch_.advance(n));
        apply_position(position_.advance(n));
        apply_damping(damping_.advance(n));
        mix_.begin(pickup_.advance(n), n);
 
        guard_.begin();
        if (loaded_) {
            for (uint16_t i = 0; i < n; ++i) {
                const float at_b = loop_.tick(exciter_, [&](float arriving) { return end_b_.reflect(arriving); });
                const float mix = mix_.next();
                const float radiated = load_.radiated();
                out[i] = radiated + mix * (at_b - radiated);
                guard_.add(out[i] + end_b_.load_velocity());   // the load's state is guarded either way
            }
        } else {
            for (uint16_t i = 0; i < n; ++i) {
                out[i] = loop_.tick(exciter_);
                guard_.add(out[i]);
            }
        }
        mix_.end();
 
        // A non-finite sample would recirculate forever: silence the string.
        if (guard_.tripped()) {
            reset();
            for (uint16_t i = 0; i < n; ++i) out[i] = 0.0f;
        }
    }
 
    /// The string at rest, its ports already at their targets rather than gliding to them.
    void reset() {
        // Rate-derived state belongs here, not in the constructor (FDP-055 Addendum A).
        for (primitives::SmoothedPort* port : {&pitch_, &position_, &damping_, &pickup_}) {
            port->set_time_ms(SMOOTH_MS, types::SAMPLE_RATE_F);
            port->reset();
        }
        loop_.reset();
        end_b_.set_impedance(loop_.impedance());
        end_b_.reset();
        exciter_.reset();
        mix_.reset(pickup_.value());
        apply_position(position_.value());
        apply_damping(damping_.value());
        last_period_ = -1.0f;
        update_period(pitch_.value());
    }
 
    /**
     * @brief The whole string as wired: exciter, loop, end b, pickup (AP-037)
     *
     * The widget knows what its lambdas were, so it draws them. Never called
     * from audio code.
     */
    void describe(diagram::Graph& g) const {
        using diagram::Kind;
        using diagram::Wave;
        const uint8_t group = g.add_group(name_);
 
        const diagram::Ports loop = loop_.describe(g, group, loaded_);
 
        const diagram::Ports exciter = exciter_.describe(g, group);
        g.add_edge(exciter.out, loop.in, Wave::Force);
        const uint8_t second = exciter.find("table B");
        if (second != diagram::NO_NODE) g.add_edge(second, loop.in, Wave::Force);
 
        if (loaded_) {
            const diagram::Ports end_b = end_b_.describe(g, group);
            g.add_edge(loop.find("to end b"), end_b.in, Wave::Velocity);
            g.add_edge(end_b.out, loop.find("from end b"), Wave::Velocity);
            const uint8_t tap = g.add_node(Kind::Tap, "out: load ↔ bare string", group);
            g.add_edge(end_b.find("load"), tap, Wave::Velocity);
            g.add_edge(loop.out, tap, Wave::Velocity);
        } else {
            const uint8_t tap = g.add_node(Kind::Tap, "out: end b velocity", group);
            g.add_edge(loop.out, tap, Wave::Velocity);
        }
    }
 
    // ─── Reading the string ──────────────────────────────────────────
 
    /// The loop period the string is currently tuned to, in samples.
    float period_samples() const { return loop_.period_samples(); }
 
    /// Energy in the loop, the load and the exciter. Never called from audio code.
    float energy() const { return loop_.energy() + (loaded_ ? end_b_.energy() : 0.0f) + exciter_.energy(); }
 
protected:
    friend struct StringTestAccess;
 
    static constexpr float SMOOTH_MS = 20.0f;
    static constexpr float MIN_JUNCTION = 0.05f;
    static constexpr float MAX_JUNCTION = 0.5f;
    static constexpr float LOOP_GAIN = 0.999f;         ///< energy lost at end b each trip
    static constexpr float PERIOD_MARGIN = 4.0f;       ///< headroom under MaxPeriod for the split
    static constexpr float RETUNE_THRESHOLD = 1e-4f;   ///< samples of period change worth a retune
 
    void update_period(float pitch_su) {
        const float note = math::note_of_su(math::clamp01(pitch_su));
        float period = types::SAMPLE_RATE_F / math::note_to_frequency(note);
        const float longest = static_cast<float>(MaxPeriod) - PERIOD_MARGIN;
        if (period > longest) period = longest;
        // Retuning re-splits the segments and re-tunes the allpass; skip it
        // while the pitch holds.
        if (std::fabs(period - last_period_) > RETUNE_THRESHOLD) {
            loop_.set_period_samples(period);
            last_period_ = period;
        }
    }
 
    void apply_position(float position_su) {
        const float junction = MIN_JUNCTION + position_su * (MAX_JUNCTION - MIN_JUNCTION);
        if (std::fabs(junction - last_junction_) > RETUNE_THRESHOLD) {
            loop_.set_junction(junction);
            last_junction_ = junction;
        }
    }
 
    void apply_damping(float damping_su) {
        if (std::fabs(damping_su - last_damping_) > RETUNE_THRESHOLD) {
            loop_.set_damping_su(damping_su);
            last_damping_ = damping_su;
        }
    }
 
    const char* name_;
    float buf_a_[MaxPeriod] = {};   ///< the loop's segment to end a
    float buf_b_[MaxPeriod] = {};   ///< and to end b
    StringLoop loop_;
 
    Exciter& exciter_;
    Load& load_;
    LoadJunction<Load> end_b_;
    bool loaded_ = true;
 
    primitives::SmoothedPort pitch_;
    primitives::SmoothedPort position_;
    primitives::SmoothedPort damping_;
    primitives::SmoothedPort pickup_;
    primitives::CrossfadeRamp mix_;
    primitives::BlockGuard guard_;
 
    float last_period_ = -1.0f;
    float last_junction_ = -1.0f;
    float last_damping_ = -1.0f;
};
 
} // namespace sbl::dsp::pm
 
#endif // SBL_DSP_PM_STRING_BASE_HPP_