rill_core_model/
lib.rs

1//! Wave Digital Filter (WDF) core and physical modeling — elements, adapters,
2//! analysis, and resonant models for analog circuit and acoustic simulation.
3//!
4//! All types are generic over [`rill_core::Transcendental`], supporting both `f32`
5//! and `f64`. SIMD-accelerated batch processing is available via
6//! `process_incident_vector` methods on [`Resistor`], [`Capacitor`],
7//! [`Inductor`], and [`Diode`], plus the free function
8//! [`elements::process_batch_simd`].
9//!
10//! ## Modules
11//! - `macros` — WDF eDSL macros for defining elements and filters
12//! - `analysis` — frequency response and distortion analysis
13//! - `constants` — physical constants and tolerances
14//! - `wdf` — WDF-based filter models
15//! - `string` — 1D waveguide string models with stiffness and damping
16//! - `plate` — 2D FDTD waveguide mesh for plates and membranes
17//! - `modal` — modal synthesis via parallel resonant filter banks
18//! - `cavity` — Helmholtz cavity resonators and coupled cavity arrays
19//!
20//! # Design
21//!
22//! WDF elements are built around the [`WdfElement`] trait, which defines a
23//! port resistance, wave processing, and state update cycle. Elements can be
24//! combined via [`SeriesAdapter`] and [`ParallelAdapter`] to form arbitrary
25//! linear circuits. Nonlinear elements like [`Diode`] use Newton-Raphson
26//! iteration for implicit solution.
27//!
28//! References:
29//! - A. Fettweis, "Wave Digital Filters: Theory and Practice" (1986)
30//! - K. J. Werner et al., "An Improved and Generalized Diode Clipper
31//!   Model for Wave Digital Filters" (2015)
32
33#![warn(missing_docs)]
34#![deny(unsafe_code)]
35
36pub use rill_core::Transcendental;
37
38/// WDF eDSL macros for defining elements and filters
39pub mod macros;
40
41mod adapters;
42/// Frequency response and distortion analysis
43pub mod analysis;
44/// Physical constants and tolerances
45pub mod constants;
46mod elements;
47/// Analog tape recording and playback head models
48pub mod tape;
49
50/// WDF-based filter models
51pub mod wdf;
52
53/// Helmholtz cavity resonators and coupled cavity arrays
54pub mod cavity;
55/// Modal synthesis via parallel resonant filter banks
56pub mod modal;
57/// 2D FDTD waveguide mesh for plates and membranes
58pub mod plate;
59/// 1D waveguide string models with stiffness and damping
60pub mod string;
61
62pub use adapters::{ParallelAdapter, SeriesAdapter};
63pub use cavity::{CavityArray, HelmholtzCavity};
64pub use elements::{Capacitor, Diode, Inductor, OpAmp, Resistor};
65pub use modal::ModalModel;
66pub use plate::PlateModel;
67pub use string::StringModel;
68
69/// Base WDF element trait.
70///
71/// Every WDF element has a port resistance and processes incident
72/// waves to produce reflected waves. For SIMD batch processing,
73/// see the `process_incident_vector` methods on concrete element types.
74pub trait WdfElement<T: Transcendental>: Send + Sync {
75    /// Port resistance
76    fn port_resistance(&self) -> T;
77
78    /// Process incident wave, return reflected wave
79    fn process_incident(&mut self, a: T) -> T;
80
81    /// Update internal state (called after wave computation)
82    fn update_state(&mut self);
83
84    /// Current voltage across the element
85    fn voltage(&self) -> T;
86
87    /// Current current through the element
88    fn current(&self) -> T;
89
90    /// Reset to initial state
91    fn reset(&mut self);
92}
93
94/// Wave variables: a (incident), b (reflected)
95#[derive(Debug, Clone, Copy)]
96pub struct WaveVariables<T: Transcendental> {
97    /// Incident wave
98    pub a: T,
99    /// Reflected wave
100    pub b: T,
101}
102
103impl<T: Transcendental> WaveVariables<T> {
104    /// Create zero wave variables
105    pub fn new() -> Self {
106        Self {
107            a: T::ZERO,
108            b: T::ZERO,
109        }
110    }
111
112    /// Compute voltage and current from wave variables
113    pub fn to_voltage_current(&self, port_resistance: T) -> (T, T) {
114        let two = T::from_f32(2.0);
115        let v = (self.a + self.b) / two;
116        let i = (self.a - self.b) / (two * port_resistance);
117        (v, i)
118    }
119
120    /// Compute wave variables from voltage and current
121    pub fn from_voltage_current(v: T, i: T, port_resistance: T) -> Self {
122        let a = v + port_resistance * i;
123        let b = v - port_resistance * i;
124        Self { a, b }
125    }
126}
127
128impl<T: Transcendental> Default for WaveVariables<T> {
129    fn default() -> Self {
130        Self::new()
131    }
132}
133
134#[cfg(test)]
135mod tests {
136    use super::*;
137
138    #[test]
139    fn test_wave_variables() {
140        let wv: WaveVariables<f64> = WaveVariables::new();
141        assert_eq!(wv.a, 0.0);
142        assert_eq!(wv.b, 0.0);
143    }
144
145    #[test]
146    fn test_wave_to_voltage_current() {
147        let wv: WaveVariables<f64> = WaveVariables { a: 2.0, b: 0.5 };
148        let (v, i) = wv.to_voltage_current(100.0);
149        assert!((v - 1.25).abs() < 1e-10);
150        assert!((i - 0.0075).abs() < 1e-10);
151    }
152
153    #[test]
154    fn test_voltage_current_to_wave() {
155        let wv: WaveVariables<f64> = WaveVariables::from_voltage_current(1.0, 0.01, 100.0);
156        assert!((wv.a - 2.0).abs() < 1e-10);
157        assert!((wv.b - 0.0).abs() < 1e-10);
158    }
159}
rill_core_model/lib.rs

rill_core_model/
lib.rs
