Simulator

simulator

Simulation orchestration for flepimop2.

Simulator(system, engine, backend, *, target=None, simulate_config=None, system_config=None, engine_config=None, backend_config=None)

Build and run a single simulation from configuration models.

Attributes:

Name	Type	Description
system	SystemABC	The built system instance.
engine	EngineABC	The built engine instance.
backend	BackendABC	The built backend instance.
target	str | None	Optional target simulate config to use.
simulate_config	SimulateSpecificationModel | None	The resolved simulation specification.
system_config	ModuleModel | None	The resolved system configuration dict.
engine_config	ModuleModel | None	The resolved engine configuration dict.
backend_config	ModuleModel | None	The resolved backend configuration dict.

Initialize the simulator with resolved components.

Parameters:

Name	Type	Description	Default
system	SystemABC	The built system instance.	required
engine	EngineABC	The built engine instance.	required
backend	BackendABC	The built backend instance.	required
target	str | None	Optional target simulate config to use.	None
simulate_config	SimulateSpecificationModel | None	The resolved simulation specification, if available.	None
system_config	ModuleModel | None	The resolved system configuration model, if available.	None
engine_config	ModuleModel | None	The resolved engine configuration model, if available.	None
backend_config	ModuleModel | None	The resolved backend configuration model, if available.	None

Raises:

Type	Description
Flepimop2ValidationError	If the engine is incompatible with the system.

Source code in src/flepimop2/simulator.py

def __init__(  # noqa: PLR0913
    self,
    system: SystemABC,
    engine: EngineABC,
    backend: BackendABC,
    *,
    target: str | None = None,
    simulate_config: SimulateSpecificationModel | None = None,
    system_config: ModuleModel | None = None,
    engine_config: ModuleModel | None = None,
    backend_config: ModuleModel | None = None,
) -> None:
    """
    Initialize the simulator with resolved components.

    Args:
        system: The built system instance.
        engine: The built engine instance.
        backend: The built backend instance.
        target: Optional target simulate config to use.
        simulate_config: The resolved simulation specification, if available.
        system_config: The resolved system configuration model, if available.
        engine_config: The resolved engine configuration model, if available.
        backend_config: The resolved backend configuration model, if available.

    Raises:
        Flepimop2ValidationError: If the engine is incompatible with the system.

    """
    self.target = target
    self.simulate_config = simulate_config
    self.system_config = system_config
    self.engine_config = engine_config
    self.backend_config = backend_config
    self.system = system
    self.engine = engine
    self.backend = backend

    if issues := self.engine.validate_system(self.system):
        raise Flepimop2ValidationError(issues)

from_configuration_model(config_model, target=None) classmethod

Build a simulator from a configuration model.

Returns:

Type	Description
Simulator	The constructed simulator instance.

Source code in src/flepimop2/simulator.py

@classmethod
def from_configuration_model(
    cls,
    config_model: ConfigurationModel,
    target: str | None = None,
) -> "Simulator":
    """
    Build a simulator from a configuration model.

    Returns:
        The constructed simulator instance.

    """
    simulate_config = _get_config_target(
        config_model.simulate,
        target,
        "simulate",
    )

    system_config = config_model.systems[simulate_config.system]
    engine_config = config_model.engines[simulate_config.engine]
    backend_config = config_model.backends[simulate_config.backend]

    system = build_system(system_config)
    engine = build_engine(engine_config)
    backend = build_backend(backend_config)

    return cls(
        system,
        engine,
        backend,
        target=target,
        simulate_config=simulate_config,
        system_config=system_config,
        engine_config=engine_config,
        backend_config=backend_config,
    )

run(initial_state, params, meta=None)

Run the simulation and persist results via the backend.

Parameters:

Name	Type	Description	Default
initial_state	Float64NDArray	The initial state array for the simulation.	required
params	dict[str, float]	The parameter dict for the simulation.	required
meta	RunMeta | None	Metadata about the simulation run.	None

Returns:

Type	Description
Float64NDArray	The simulation result array.

Raises:

Type	Description
ValueError	If simulate_config is not set.

Source code in src/flepimop2/simulator.py

def run(
    self,
    initial_state: Float64NDArray,
    params: dict[str, float],
    meta: RunMeta | None = None,
) -> Float64NDArray:
    """
    Run the simulation and persist results via the backend.

    Args:
        initial_state: The initial state array for the simulation.
        params: The parameter dict for the simulation.
        meta: Metadata about the simulation run.

    Returns:
        The simulation result array.

    Raises:
        ValueError: If `simulate_config` is not set.

    """
    if self.simulate_config is None:
        msg = "simulate_config must be set before running the simulator."
        raise ValueError(msg)
    res = self.engine.run(
        self.system,
        self.simulate_config.t_eval,
        initial_state,
        params,
    )
    meta = meta or RunMeta()
    self.backend.save(res, meta)
    return res