pySimBlocks.core.simulator

class pySimBlocks.core.simulator.Simulator(model: Model, sim_cfg: SimulationConfig, verbose: bool = False)

Bases: object

Discrete-time simulator with strict Simulink-like semantics.

Each simulation step follows four phases:

1. output_update — blocks compute y[k] from x[k] and u[k].

2. Propagate — outputs are forwarded to downstream inputs.

3. state_update — blocks compute x[k+1] from x[k] and u[k].

4. Commit — x[k+1] is copied into x[k].

This guarantees proper separation of outputs and state transitions, correct causal behavior for feedback loops, and algebraic loop detection through the model’s topological ordering.

model

The block-diagram model to simulate.

sim_cfg

Simulation execution configuration.

verbose

If True, print step-by-step execution logs.

logs

Logged signal values keyed by variable name.

initialize(t0: float = 0.0) → None

Initialize all blocks and propagate initial outputs.

Parameters:

t0 – Initial simulation time in seconds.

Raises:

RuntimeError – If any block raises during initialization.

step(dt_override: float | None = None) → None

Perform one simulation step.

With an internal clock, dt is provided by the time manager. With an external clock, dt_override must be supplied by the caller.

Parameters:

dt_override – Time step in seconds, required when using an external clock. Must not be provided for an internal clock.

Raises:

• RuntimeError – If dt_override is missing for an external clock, or provided for an internal clock.

• ValueError – If dt_override is not strictly positive.

run(T: float | None = None, t0: float | None = None, logging: list[str] | None = None) → Dict[str, List[ndarray]]

Run the simulation from t0 to T.

Falls back to sim_cfg values for any argument not provided.

Parameters:

• T – Simulation end time in seconds.

• t0 – Simulation start time in seconds.

• logging – List of variable names to log (e.g. "BlockName.outputs.port").

Returns:

Dict mapping variable names to their logged values over time.

Raises:

RuntimeError – If called with an external clock configuration.

get_data(variable: str | None = None, block: str | None = None, port: str | None = None) → ndarray

Retrieve logged data for a variable as a NumPy array.

Provide either variable or the (block, port) pair:

• variable: full log key, e.g. "BlockName.outputs.port".

• block + port: shorthand for "block.outputs.port".

Parameters:

• variable – Full variable name as logged.

• block – Block name (used with port).

• port – Output port name (used with block).

Returns:

Array of shape (n_steps, *signal_shape) containing the logged values.

Raises:

ValueError – If neither variable nor (block, port) is provided, if the variable is not found in logs, or if the log is empty or cannot be converted to a NumPy array.