Graph Simulator

Runs a graph in Python for testing (requires numpy).

simulate

Python DSP simulator for dsp-graph signal graphs.

Runs a per-sample Python loop that mirrors the C++ code generated by compile.py, enabling prototyping, unit-testing, and correctness verification without compilation.

Usage::

from gen_dsp.graph.simulate import simulate, SimState, SimResult

Requires numpy (install via pip install gen-dsp[sim]).

SimState

SimState(graph: Graph, sample_rate: float = 0.0)

Holds all mutable state for a simulated DSP graph.

reset

reset() -> None

Reset all state to initial values, mirroring compile.py:_emit_state_reset.

set_param

set_param(name: str, value: float) -> None

Set a parameter value. Raises KeyError if name is unknown.

get_param

get_param(name: str) -> float

Get current parameter value. Raises KeyError if name is unknown.

set_buffer

set_buffer(buffer_id: str, data: NDArray[float32]) -> None

Set buffer contents. Data is truncated/zero-padded to buffer size.

get_buffer

get_buffer(buffer_id: str) -> NDArray[np.float32]

Get a copy of buffer contents.

get_peek

get_peek(peek_id: str) -> float

Get the last value captured by a Peek node.

SimResult dataclass

SimResult(
    outputs: dict[str, NDArray[float32]] = dict(),
    state: SimState = None,
)

Result of a simulation run.

simulate

simulate(
    graph: Graph,
    inputs: dict[str, NDArray[float32]] | None = None,
    n_samples: int = 0,
    params: dict[str, float] | None = None,
    state: SimState | None = None,
    sample_rate: float = 0.0,
) -> SimResult

Simulate a DSP graph in Python, returning output arrays and state.

Parameters:

Name	Type	Description	Default
graph	Graph	The DSP graph to simulate.	required
inputs	dict[str, NDArray[float32]] | None	Dict mapping audio input IDs to float32 arrays. All arrays must have the same length. May be None for generators.	None
n_samples	int	Number of samples to process. Inferred from inputs if 0. Required for generators (no inputs).	0
params	dict[str, float] | None	Optional param overrides (name -> value).	None
state	SimState | None	Optional SimState to reuse across calls. Created if None.	None
sample_rate	float	Sample rate override. Uses graph.sample_rate if 0.	0.0

Returns:

Type	Description
SimResult	SimResult with output arrays and the (possibly new) SimState.

Raises:

Type	Description
ValueError	On invalid graph, mismatched input shapes, etc.