simulator.simulator¶

The simulator: simulations and scans of models, serially or in a pool.

Simulator.run(model, scan) runs every point of a scan in four steps:

Compile: a plan per combination of the simulations and the models of the scan (one plan without a dimension of simulations or of models), with compile_simulation; the values of the dimensions of values in the units of their targets in every model, once; the times of the dimensions with at in the time unit of every model; the selections and the grid of the output; the observables of the run, ordered, checked against the first model and with their kinds and units, see sbmlsim.simulator.observables.
Points: a point is a tuple of indices, nothing is built per point in the parent. The points are cut into chunks which share a plan, at most ceil(n_points / (4 * n_workers)) and at most MAX_CHUNK points each.
Worker: a chunk applies the values of each point to its plan and runs it, see sbmlsim.simulator.worker; the same function runs serially in the calling process and in a worker of a pool of sbmlsim.parallel; the observables are evaluated on the native solutions of the points of a chunk before the kept timecourses are interpolated onto a grid.
Assembly: the arrays of the chunks are written into the arrays of the result, a ScanResult, and reshaped into the dimensions of the scan.

The result does not depend on the number of workers or the size of the chunks: the values of a scan are fixed before the run. A run which raises raises the error of the first point in the order of the scan which fails, and a run which flags the points which fail keeps their errors in that order.

The integrator settings of a simulator apply to every model it runs: the model of a run, every model of a dimension of models and every model a worker loads, each with its own tolerance per state. A setting of a model which the simulator does not set stays, and a worker loads the model with the integrator and the settings the model has in the calling process.

ScanError ¶

Bases: RuntimeError

A point of a scan failed; the message names its labels and values.

Simulator ¶

Simulator(n_workers=None, **integrator_settings)

Runs simulations and scans of models, see the module.

Attributes:

Name	Type	Description
`n_workers`		the processes of a run, see `sbmlsim.parallel.resolve_workers`.
`integrator_settings`	`dict[str, IntegratorSetting]`	the settings of the integrator of every model.

Create a simulator.

Parameters:

Name	Type	Description	Default
`n_workers`	`int \| None`	`1` runs serially, a number is the number of processes, `None` uses every CPU for a scan of `sbmlsim.parallel.POOL_THRESHOLD` points or more and runs a smaller one serially.	`None`
`**integrator_settings`	`IntegratorSetting`	every setting of the integrator of roadrunner by its name, e.g. `relative_tolerance` or `variable_step_size`; `absolute_tolerance` is a float or an `AbsoluteTolerance`. The defaults are `AbsoluteTolerance()` and `relative_tolerance=1e-10`.	`{}`

Raises:

Type	Description
`ValueError`	if `n_workers` is less than 1.

set_integrator_settings ¶

set_integrator_settings(**integrator_settings)

Set settings of the integrator for every model run after.

A name the integrator does not have raises when a model is loaded, i.e. before a pool starts.

load ¶

load(model)

Get a loaded model with the integrator settings of the simulator.

A RoadrunnerSBMLModel is used as it is and gets the settings; an AbstractModel, with its selections, or a path is loaded.

Raises:

Type	Description
`ValueError`	if the model is of no supported type, or the integrator has no setting of a name.

compile ¶

compile(model, simulation)

Compile a simulation against a model.

The changes of the model are defaults of the pre-initialization changes, see Simulation.with_preinit_defaults: a change of the model applies unless the simulation sets the target.

Raises:

Type	Description
`ValueError`	if the simulation does not fit the model, see `compile_simulation`.

simulate ¶

simulate(model, simulation)

Run one simulation with the selections of the model.

The native solution of one simulation, which the fit and the test suites use; a scan is run.

Raises:

Type	Description
`ValueError`	if the simulation does not fit the model.
`RuntimeError`	if roadrunner fails to integrate.

run ¶

run(
    model,
    scan,
    observables=None,
    *,
    time=None,
    keep=None,
    on_error="raise",
    progress=None,
)

Run every point of a scan, see the module.

The variables of the result are the kept observables; without observables they are the selections of the model, of the first model of a dimension of models, each a timecourse of its own name.

Parameters:

Name	Type	Description	Default
`model`	`ModelLike \| None`	the model of the run; `None` for a scan with a dimension of models, which gives the model of every point.	required
`scan`	`Scan \| Simulation`	the scan, a simulation is a scan without dimensions.	required
`observables`	`Sequence[Observable] \| None`	what the run computes from every simulation, see `sbmlsim.simulation.observables`; they are evaluated on the native solution of every simulation, also with `time`.	`None`
`time`	`ArrayLike \| Quantity \| None`	a grid of times every timecourse is interpolated onto, numbers in the time unit of the model or a quantity, see `sbmlsim.result.timecourse.grid_weights`; without it the result keeps the output times of the simulations, a time of a change twice, the states before and after it, a dimension `time` if they agree, up to the changes at them, and `_point` otherwise.	`None`
`keep`	`Sequence[str] \| None`	the observables of the result, every one by default; the id of a PK observable keeps all its parameters; without observables the selections of the result. The others are evaluated where a kept one needs them and dropped.	`None`
`on_error`	`OnError`	`"raise"` raises a `ScanError` for the first point in the order of the scan which fails; `"flag"` sets every value of a point which fails to `NaN` and records it in the variable `status`. A failing point is reported by its error, not by the log of roadrunner; a run in a pool prints no messages of the integrator (SUNDIALS), while a serial run, which integrates the model of the user in the calling process, still shows them, a dozen lines or more per failing point.	`'raise'`
`progress`	`bool \| None`	show a progress bar; `None` shows it for a run in a pool.	`None`

Returns:

Type	Description
`ScanResult`	The result, see `sbmlsim.result.scan`.

Raises:

Type	Description
`ValueError`	if the scan does not fit its models, see `_compile`, or the integrator has no setting of a name.
`ScanError`	for a point which fails with `on_error="raise"`.
`RuntimeError`	if a worker of the pool dies.

scan_point_plans ¶

scan_point_plans(scan, model, plan, positions)

Get the plans of points of a scan of value dimensions on a compiled plan.

The plan of a point is the plan with the values and times of the point, scan_point_values, applied by point_plan, the function the workers of a run apply them with. The fit computes the values once per simulation group and applies them to the plan of every evaluation, which carries the fitted values first, so the values of a dimension win over a fitted value of the same target, as in a run of the scan.

Parameters:

Name	Type	Description	Default
`scan`	`Scan`	the scan, whose dimensions all set values.	required
`model`	`RoadrunnerSBMLModel`	the loaded model, whose units the values are converted to.	required
`plan`	`Plan`	the compiled plan of `scan.simulation` on the model, with any values applied already.	required
`positions`	`ndarray`	the index of every point along every dimension, a row per point; the one point of a scan without dimensions is a row of length 0.	required

Returns:

Type	Description
`list[Plan]`	The plan of every point, in the order of `positions`.

Raises:

Type	Description
`ValueError`	for a dimension of simulations or models, values which do not fit the model, a time of a dimension with `at` outside of the simulation, or two dimensions which set one target at one time.

scan_point_values ¶

scan_point_values(scan, model, plan, positions)

Get the values and times of points of a scan of value dimensions.

The values are in the units of the model and the times in its time unit, computed as a run of the scan computes them. point_plan(plan, values, timed, k) applies them to a plan, see scan_point_plans; the fit computes them once per simulation group and applies them to the plan of every evaluation.

Parameters:

Name	Type	Description	Default
`scan`	`Scan`	the scan, whose dimensions all set values.	required
`model`	`RoadrunnerSBMLModel`	the loaded model, whose units the values are converted to.	required
`plan`	`Plan`	the compiled plan of `scan.simulation` on the model, whose time span the times of the dimensions with `at` must lie in.	required
`positions`	`ndarray`	the index of every point along every dimension, a row per point; the one point of a scan without dimensions is a row of length 0.	required

Returns:

Type	Description
`dict[str, ndarray]`	target -> the value of every point, and time -> target -> the value of
`dict[float, dict[str, ndarray]]`	every point for the dimensions with `at`.

Raises:

Type	Description
`ValueError`	for a dimension of simulations or models, values which do not fit the model, a time of a dimension with `at` outside of the simulation, or two dimensions which set one target at one time.