Crate pedalkernel

Expand description

§PedalKernel

A DSL compiler that transforms .pedal circuit netlists into real-time audio processors using Wave Digital Filter (WDF) theory. PedalKernel models the complete analog signal path of guitar effect pedals — resistors, capacitors, op-amps, transistors, vacuum tubes, diodes — and synthesizes a per-sample processing kernel that runs at audio rate with deterministic, bounded latency.

§Compilation Pipeline

The compiler transforms a human-readable circuit description into an optimized real-time audio processor through five stages:

  .pedal DSL         nom parser           Circuit graph
 ┌──────────┐      ┌──────────┐         ┌──────────────┐
 │ pedal    │      │ PedalDef │         │ CircuitGraph │
 │ "RAT" { │─────>│ (AST)    │────────>│ (nodes+edges)│
 │  R1: ... │ parse│          │ graph   │              │
 └──────────┘      └──────────┘ build   └──────┬───────┘
                                               │
                        SPQR decomposition     │
                       ┌───────────────────────┘
                       │
                       v
           ┌───────────────────────┐
           │  S / P / Q / R nodes  │
           │  (unique tree decomp) │
           └───────────┬───────────┘
                       │
                       v
             ┌──────────────────┐       ┌─────────────────┐
             │  SpqrStage list  │──────>│  CompiledPedal  │
             │  (WDF, IIR, MNA) │ build │  (PedalProcessor│
             └──────────────────┘       │   impl)         │
                                        └─────────────────┘

Parse: The dsl module uses nom to parse .pedal files into a dsl::PedalDef AST containing components, nets, and controls.
Graph build: The compiler constructs a CircuitGraph from the AST. Each component declares its own topology via the Component trait — the compiler never pattern-matches on component type.
SPQR decomposition: The circuit graph is decomposed into a unique SPQR tree (Series / Parallel / Q-leaf / Rigid). S and P nodes map directly to WDF adaptors. R nodes require matrix-based solvers.
Stage assignment: Each SPQR subtree becomes a processing stage with complexity determined by its topology and component classification.
Build: Stages are compiled into concrete runtime processors and chained into a CompiledPedal that implements PedalProcessor.

§Key Concepts

§Wave Digital Filters (WDF)

WDFs model analog circuits by propagating wave variables (incident and reflected voltage waves) through a binary tree of adaptors. Each passive component (R, C, L) becomes a leaf node; series and parallel connections become adaptor nodes. The tree is traversed once per sample — O(1) per component — making WDFs ideal for real-time audio.

§SPQR Decomposition

Every 2-connected graph has a unique decomposition into Series, Parallel, and Rigid (triconnected) components. PedalKernel exploits this to automatically identify which parts of a circuit can be solved with cheap WDF tree traversal (S/P) and which require heavier matrix solvers (R).

§The Component Trait

Component is the single source of truth for all component behavior. Each concrete component (resistor, op-amp, triode, etc.) declares its own ports, edge kinds, signal flow, non-idealities, and MNA stamps. The compiler reacts to these declarations — it never hard-codes knowledge about specific component types. This makes adding new components a matter of implementing one trait, with no changes to the compilation pipeline.

§Stage Types and Complexity

Stage	Solver	Complexity	When Used
PassiveWdf	WDF tree traversal	O(1)	All-passive S/P subtree
NlWdf	WDF + scalar Newton-Raphson	O(1)	S/P subtree with one nonlinear element
IIR	Biquad from MNA poles/zeros	O(1)	All-passive R-node (e.g., tone stack)
BlackFeedback	Harold Black’s formula	O(1)	Op-amp + passive feedback network
StateSpace	State-space MNA integration	O(N)	Reactive R-node with active elements
MultiNl	Multi-dimensional NR	O(N^2)	R-node with multiple nonlinear elements

§Non-Ideal Effects

Components declare their non-ideal behaviors via NonIdealFx — gain-bandwidth product limiting, slew rate, rail saturation — using values from SPICE models and datasheets. The stage builder applies these as post-processing filters, keeping the core WDF/MNA solver ideal and the non-ideal modeling composable.

§Quick Start

use pedalkernel::{dsl, compiler, PedalProcessor};

// Parse a .pedal circuit definition
let src = r#"
pedal "Example" {
  components {
    R1: resistor(10k)
    C1: cap(100n)
  }
  nets {
    in -> C1.a
    C1.b -> R1.a
    R1.b -> gnd
  }
}
"#;
let pedal = dsl::parse_pedal_file(src).unwrap();

// Compile to a real-time processor
let mut processor = compiler::compile_pedal(&pedal, 48000.0).unwrap();

// Process audio sample-by-sample
let output = processor.process(0.5);

See the compiler module for implementation details, and the compiler::component module for the trait that drives the entire pipeline.

§Modules

dsl — nom-based parser for .pedal circuit definition files
compiler — netlist-to-WDF compiler: graph building, SPQR decomposition, stage synthesis
elements — WDF one-port elements (R, C, L) and nonlinear roots (diodes)
tree — WDF adaptors (series, parallel) and the processing engine
kicad — KiCad netlist export from the parsed AST
wav — WAV file I/O for offline rendering and testing
oversampling — antialiasing via oversampling at nonlinear stages
loading — electrical loading and impedance interaction between stages
tolerance — component tolerance randomization for realistic variation
thermal — thermal drift model for temperature-dependent behavior
metering — lock-free audio-to-UI metrics for VU meters and visualizations

Modules§

board: Parser for .board pedalboard definition files.
bom: Bill-of-materials (BOM) generation from the parsed .pedal AST.
compiler: Netlist-to-WDF compiler.
dsl: DSL parser for .pedal circuit definition files.
dsl_expand: File-based subcircuit expansion (flatten pass).
elements: WDF circuit elements — re-exported from pedalkernel-rt.
fast_math
kicad: KiCad netlist export from the parsed .pedal AST.
loading
metering
model_lookup: Model lookup functions — bridges pedalkernel’s model DB to pedalkernel-rt types.
models: SPICE .MODEL file parser and model registry.
nonideal_fx
oversampling
pedalboard: Pedalboard processor — chains multiple compiled pedals in series.
pot_taper
precompute: Precomputed scattering matrix binary format (.pksc).
thermal
tolerance: Component tolerance randomization.
tree
wav: WAV file I/O for testing and offline rendering.

Traits§

PedalProcessor: Audio processor trait for pedals — re-exported from pedalkernel-rt. Audio processor trait for pedals.

Type Aliases§

Wave: Runtime audio scalar (f64 on the host, f32 under wave-f32 / on device), re-exported so crate::Wave resolves in the compiler when it casts f64 computations to the runtime types’ scalar at the storage boundary.