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. A worker of a pool hands a large array of the result of a chunk over in shared memory instead of the pipe of the pool, on POSIX, see sbmlsim.simulator.shared; the segments of a run never outlive it.
Assembly: the arrays of a chunk are written into the arrays of the result when the chunk arrives and the chunk is released, see _Assembly, so a run holds its result once; the arrays are reshaped into the dimensions of the scan, a ScanResult.

A run of a block of points (points=range(start, stop)) runs only these points of the scan, in the same chunks of a plan, and gives a result over the dimension _index of their flat indices in C order; ScanResult.combine combines the results of the blocks of a scan to the result of the whole scan, bitwise, so a scan runs in pieces, e.g. on several machines.

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.

The engine of a simulator, roadrunner by default, COPASI or AMICI, simulates every model it runs: a model of another engine is loaded again in the engine of the simulator, see sbmlsim.model.model_sbml.load_model, and a plan runs with the executor of the engine, see sbmlsim.simulator.engines. The engine is the attribute engine of the result. A feature the engine does not simulate raises its NotImplementedError, also with on_error="flag", when the scan is compiled, before a point runs or a pool starts, see sbmlsim.simulator.engines.check_plan. A result of COPASI depends on the number of workers within the integration and not bitwise: COPASI sums the rates of the reactions of a species in an order which depends on the memory its process allocated before, so two loads of a model in the parent and in a worker differ in the last bit of a rate, which the integration amplifies. A result of AMICI does not depend on the number of workers: a worker imports the module the parent compiled, from the directory of compiled models the parent loaded it from (ModelSpec.cache), whatever the environment of the worker says, see sbmlsim.model.model_amici.using_cache.

ScanError ¶

Bases: RuntimeError

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

Simulator ¶

Simulator(
    n_workers=None, engine=ROADRUNNER, **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`.
`engine`	`Engine`	the engine which simulates every model.
`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`
`engine`	`Engine \| str`	the engine or its name, `roadrunner`, `copasi` or `amici`.	`ROADRUNNER`
`**integrator_settings`	`Unpack[IntegratorSettings]`	the settings of the integrator by their names in roadrunner, see `IntegratorSettings`, e.g. `relative_tolerance` or `variable_step_size`; `absolute_tolerance` is a float or an `AbsoluteTolerance`. A dictionary of settings is an `IntegratorSettings`, and one of other names, e.g. of another integrator of roadrunner, is set with `set_integrator_settings`. The defaults are `AbsoluteTolerance()` and `relative_tolerance=1e-10`. COPASI and AMICI ignore a setting of roadrunner they have no equivalent of, see `sbmlsim.model.model_copasi.CopasiSBMLModel.set_integrator_settings` and `sbmlsim.model.model_amici.AmiciSBMLModel.set_integrator_settings`.	`{}`

Raises:

Type	Description
`ValueError`	if `n_workers` is less than 1 or the engine is unknown.
`ImportError`	for the engine COPASI without python-copasi and for the engine AMICI without AMICI.

set_integrator_settings ¶

set_integrator_settings(**integrator_settings)

Set settings of the integrator for every model run after.

Every name is taken, also one which is no IntegratorSettings, e.g. a setting of another integrator of roadrunner, so a dictionary dict[str, IntegratorSetting] is set here.

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

load ¶

load(model)

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

A model of the engine is used as it is and gets the settings; a model of another engine, an AbstractModel, with its selections, or a path is loaded in the engine, see sbmlsim.model.model_sbml.load_model.

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 the engine fails to integrate.
`NotImplementedError`	for a feature the engine does not simulate.

run ¶

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

Run every point of a scan, or a block of its points, 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.

A block of points is a piece of the scan, e.g. a unit of work of a run on several machines: its result has the dimension _index of the flat indices of its points in C order instead of the dimensions of the scan, every coordinate of a dimension along _index and the attribute block, see ScanResult.combine, which combines the results of the blocks of a scan to the result of the whole scan, bitwise. The methods of a result over the dimensions of the scan, dims, summary, interpolate, to and q, are for the combined result: summary and interpolate raise for a block. A run of a block allocates per point of the block only, also for a scan of more points than fit into memory.

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 feature the engine does not simulate is no failing point, it raises with either.	`'raise'`
`progress`	`bool \| None`	show a progress bar; `None` shows it for a run in a pool.	`None`
`points`	`range \| None`	the flat indices of the points in C order which run, a `range` of step 1 inside `range(scan.size)` which is not empty; `None` runs the whole scan. A scan without dimensions has the point 0.	`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`, the integrator has no setting of a name, or the points are no block of the scan.
`ScanError`	for a point which fails with `on_error="raise"`.
`RuntimeError`	if a worker of the pool dies.
`NotImplementedError`	for a feature the engine does not simulate, see `sbmlsim.simulator.executor_copasi` and `sbmlsim.simulator.executor_amici`.

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`	`SBMLModel`	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`	`SBMLModel`	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.

settings_record ¶

settings_record(settings)

Get the integrator settings as JSON types, the provenance of a result.