Simulation

Run forward simulations of a generated model. The factory functions return a SimulationHelper for the configured solver (OpenCOR, Myokit, SciPy, or CasADi); all backends share the common method surface documented below.

Factory functions

solver_wrappers.get_simulation_helper

get_simulation_helper(
    model_path=None,
    solver=None,
    model_type=None,
    dt=None,
    sim_time=None,
    solver_info=None,
    pre_time=0.0,
)

Create a SimulationHelper for the requested solver.

Returns the appropriate backend (OpenCOR, Myokit, SciPy, or CasADi) based on solver and model_type. All backends share the common SimulationHelper method surface.

Parameters:

Name	Type	Description	Default
model_path	str	Path to the generated model file.	None
solver	str	Solver identifier. One of: 'CVODE_opencor': OpenCOR CVODE for CellML models (default). 'CVODE_myokit': Myokit CVODE for CellML models. 'solve_ivp': Python/SciPy solver for model_type='python' (method set via solver_info, e.g. RK45, BDF). 'casadi_integrator': CasADi integrator for model_type='casadi_python' (cvodes, idas, collocation, rk).	None
model_type	str	'cellml_only', 'python' or 'casadi_python'.	None
dt	float	Output sampling step (s).	None
sim_time	float	Logged simulation duration (s).	None
solver_info	dict	Solver config dict (e.g. MaximumStep, method).	None
pre_time	float	Unlogged steady-state spin-up duration (s).	0.0

Returns:

Name	Type	Description
SimulationHelper		The backend instance for the requested solver.

Raises:

Type	Description
ValueError	If the solver is unknown or incompatible with model_type.
RuntimeError	If the requested backend is not installed.

solver_wrappers.get_simulation_helper_from_inp_data_dict

get_simulation_helper_from_inp_data_dict(inp_data_dict)

Create a SimulationHelper from a configuration dict.

Convenience wrapper around get_simulation_helper that reads model_path, solver_info (and its solver), model_type, dt, sim_time and pre_time from the dict.

Parameters:

Name	Type	Description	Default
inp_data_dict		Configuration dict (see get_default_inp_data_dict).	required

Returns:

Name	Type	Description
SimulationHelper		The backend instance for the configured solver.

SimulationHelper

The same interface is implemented by every backend. It is documented here on the SciPy/Python backend; the OpenCOR, Myokit, and CasADi backends expose the same methods.

solver_wrappers.python_solver_helper.SimulationHelper

SimulationHelper(
    model_path, dt, sim_time, solver_info=None, pre_time=0.0
)

SciPy-based solver for libCellML-generated Python modules.

This implements the common SimulationHelper interface that every backend (OpenCOR, Myokit, SciPy, CasADi) shares. Obtain an instance via get_simulation_helper rather than constructing a backend directly. The methods documented here are available on all backends.

Typical usage::

sim = get_simulation_helper_from_inp_data_dict(inp)
sim.run()
t = sim.get_time()
y = sim.get_results(["component/var"], flatten=True)

get_time

get_time(include_pre_time=False)

Return the output time vector.

Parameters:

Name	Type	Description	Default
include_pre_time		If True, include the unlogged pre-time portion; otherwise return time relative to the end of pre-time.	False

Returns:

Type	Description
	numpy.ndarray: The sampled time points.

set_protocol_info

set_protocol_info(protocol_info)

Store protocol metadata for a common helper API.

update_times

update_times(dt, start_time, sim_time, pre_time)

Reconfigure the simulation timing.

Parameters:

Name	Type	Description	Default
dt		Output sampling step (s).	required
start_time		Start time of the simulation (s).	required
sim_time		Logged simulation duration (s).	required
pre_time		Unlogged steady-state spin-up duration (s).	required

get_init_param_vals

get_init_param_vals(param_names)

Read the initial values of the named parameters.

Parameters:

Name	Type	Description	Default
param_names		List of variable names (each entry may itself be a list of names sharing a value).	required

Returns:

Name	Type	Description
list		Initial value(s) for each requested parameter.

set_param_vals

set_param_vals(param_names, param_vals)

Set the values of the named parameters.

Parameters:

Name	Type	Description	Default
param_names		List of variable names (each entry may be a list of names sharing a value).	required
param_vals		Matching list of values to assign.	required

run

run()

Run the simulation over the configured time window.

Returns:

Name	Type	Description
bool		True on success, False if integration failed.

get_all_variable_names

get_all_variable_names()

Return the names of all state and algebraic/constant variables in the model.

get_results

get_results(variables_list_of_lists, flatten=False)

Return time-series results for the requested variables.

Parameters:

Name	Type	Description	Default
variables_list_of_lists		Variable names. Either a flat list of names, or a list of lists to group variables.	required
flatten		If True, flatten the grouped result into a single list.	False

Returns:

Name	Type	Description
list		One numpy array per requested variable (nested unless
		flatten=True). Use 'time' to request the time vector.

get_all_results

get_all_results(flatten=False)

Return time-series results for every variable in the model.

get_all_results_dict

get_all_results_dict()

Return all results as a dict keyed by variable name.

Returns:

Name	Type	Description
dict		{variable_name: numpy.ndarray} for every variable.

Raises:

Type	Description
RuntimeError	If the simulation has not been run yet.

run_offline_pre_and_set_default_state

run_offline_pre_and_set_default_state(offline_pre_time)

Run unlogged warmup once; use end state as default for reset_states().

reset_and_clear

reset_and_clear(only_one_exp=-1)

Reset the model state to initial conditions, caching the last results.

reset_states

reset_states()

Reset the state variables to their default initial values.

close_simulation

close_simulation()

Release simulation resources (no-op for the SciPy backend).