contracts.hpp

Go to the documentation of this file.

// sbl/dsp/pm/contracts.hpp — What a load, an exciter, a termination and a friction law provide (Physical modeling — cross-cutting)
//
// The contracts the physical-modeling components compose against, as
// compile-time checks (docs/conventions/physical-modeling.md §4). A consumer
// asserts the contract on its template parameter the way hw/validation/
// checks a driver, so a type that is missing a member fails at the assert
// with the contract's name rather than deep inside a call.
//
//   static_assert(pm::is_load_v<Load>, "LoadJunction needs a Load");
//
// Load         admittance(), history(), commit(force), energy(), reset()
// Exciter      excite(const JunctionState&), advance(n), energy(), reset()
// Termination  reflect(arriving), energy(), reset()
// FrictionLaw  set_force_su(su), process(dv_free), sticking(), limit(), reset()
// Described    describe(graph, group[, name]) — the diagram obligation, checked
//              beside the physics contracts rather than inside them (RPT-036)
//
// The junction state is what a guide reports at an excitation point: the
// velocity arriving there, the point's displacement, and the guide's wave
// impedance. Every exciter is handed all three, whatever law it runs, so
// energy can pass both ways at the point (Michael, 2026-09-17: bidirectional
// junction-point energy transfer). The exciter returns a force; the guide
// converts it to a wave with its impedance.
//
// Friction laws speak in wave units: the force they return is F / 2Z, the
// velocity a string of impedance Z would take from it. A junction that knows
// Z converts. A law solved offline (a lute table) is solved against a string's
// line and is only valid there; a Coulomb law (the thermal one) exposes its
// limit and can be solved against any line (AP-041 Phase 6).
 
#ifndef SBL_DSP_PM_CONTRACTS_HPP_
#define SBL_DSP_PM_CONTRACTS_HPP_
 
#include <cstdint>
#include <type_traits>
#include <utility>
 
#include <sbl/dsp/diagram/graph.hpp>
 
namespace sbl::dsp::pm {
 
/// What the guide reports at an excitation point, each sample.
struct JunctionState {
    float velocity;       ///< the velocity arriving at the point, before this sample's injection
    float displacement;   ///< the point's displacement, integrated from its velocity (wave units × samples)
    float impedance;      ///< the guide's wave impedance Z
};
 
namespace detail {
 
template<typename T>
using returns_float = std::is_same<std::decay_t<T>, float>;
 
template<typename T, typename = void>
struct has_energy_reset : std::false_type {};
template<typename T>
struct has_energy_reset<T, std::void_t<
    std::enable_if_t<returns_float<decltype(std::declval<const T&>().energy())>::value>,
    decltype(std::declval<T&>().reset())>> : std::true_type {};
 
} // namespace detail
 
// ─── Load ────────────────────────────────────────────────────────────
 
template<typename T, typename = void>
struct is_load : std::false_type {};
template<typename T>
struct is_load<T, std::void_t<
    std::enable_if_t<detail::returns_float<decltype(std::declval<const T&>().admittance())>::value>,
    std::enable_if_t<detail::returns_float<decltype(std::declval<const T&>().history())>::value>,
    std::enable_if_t<detail::returns_float<decltype(std::declval<T&>().commit(0.0f))>::value>,
    std::enable_if_t<detail::has_energy_reset<T>::value>>> : std::true_type {};
template<typename T>
inline constexpr bool is_load_v = is_load<T>::value;
 
// ─── Exciter ─────────────────────────────────────────────────────────
 
template<typename T, typename = void>
struct is_exciter : std::false_type {};
template<typename T>
struct is_exciter<T, std::void_t<
    std::enable_if_t<detail::returns_float<decltype(std::declval<T&>().excite(std::declval<const JunctionState&>()))>::value>,
    decltype(std::declval<T&>().advance(uint16_t{})),
    std::enable_if_t<detail::has_energy_reset<T>::value>>> : std::true_type {};
template<typename T>
inline constexpr bool is_exciter_v = is_exciter<T>::value;
 
// ─── Termination ─────────────────────────────────────────────────────
 
template<typename T, typename = void>
struct is_termination : std::false_type {};
template<typename T>
struct is_termination<T, std::void_t<
    std::enable_if_t<detail::returns_float<decltype(std::declval<T&>().reflect(0.0f))>::value>,
    std::enable_if_t<detail::has_energy_reset<T>::value>>> : std::true_type {};
template<typename T>
inline constexpr bool is_termination_v = is_termination<T>::value;
 
// ─── Friction law ────────────────────────────────────────────────────
 
template<typename T, typename = void>
struct is_friction_law : std::false_type {};
template<typename T>
struct is_friction_law<T, std::void_t<
    decltype(std::declval<T&>().set_force_su(0.0f)),
    std::enable_if_t<detail::returns_float<decltype(std::declval<T&>().process(0.0f))>::value>,
    std::enable_if_t<std::is_same<decltype(std::declval<const T&>().sticking()), bool>::value>,
    std::enable_if_t<detail::returns_float<decltype(std::declval<const T&>().limit())>::value>,
    decltype(std::declval<T&>().reset())>> : std::true_type {};
template<typename T>
inline constexpr bool is_friction_law_v = is_friction_law<T>::value;
 
// ─── Described ───────────────────────────────────────────────────────
 
template<typename T, typename = void>
struct is_described : std::false_type {};
template<typename T>
struct is_described<T, std::void_t<
    std::enable_if_t<std::is_same<
        decltype(std::declval<const T&>().describe(std::declval<diagram::Graph&>(), uint8_t{})),
        diagram::Ports>::value>>> : std::true_type {};
template<typename T>
inline constexpr bool is_described_v = is_described<T>::value;
 
// ─── Waveguide callables ─────────────────────────────────────────────
 
template<typename F>
inline constexpr bool is_wave_callable_v = std::is_invocable_r_v<float, F, float>;
 
} // namespace sbl::dsp::pm
 
#endif // SBL_DSP_PM_CONTRACTS_HPP_