simulator.worker¶

The worker of a scan: the points of a chunk on one plan and one model.

run_chunk is the same function serially and in a worker process: for every point of a chunk it applies the values of the point to the plan of the chunk, Plan.with_values, and runs the plan with the executor of the engine of the model, sbmlsim.simulator.engines.execute_plan; the native solutions of the points which ran are stacked into arrays padded with NaN, the observables of the run are evaluated on them, see sbmlsim.simulator.observables, and the kept timecourses are interpolated onto the grid of times of the chunk, if it has one. A run without observables needs no native solution: the kept selections of every point are interpolated right after its simulation, so the memory of a chunk is bounded by its grid. A point fails exactly when its own simulation or observables fail, not because of the other points of its chunk. Nothing in here uses pint or xarray, and a chunk and its result are numbers, strings, a plan and the graph of the observables, so they pickle.

In a worker process the model of a chunk is loaded once from its ModelSpec and kept, see sbmlsim.parallel.worker_cache, in the engine of the model of the parent, with its integrator and every one of its settings, those of the simulator and those set on the model, so a worker integrates as the parent does and the result does not depend on the number of workers (bitwise with roadrunner and AMICI, within the integration with COPASI, see sbmlsim.simulator.simulator).

In a worker of a pool a large array of the result of a chunk is written into shared memory instead of being pickled through the pipe of the pool, see SharedChunkResult and sbmlsim.simulator.shared, on POSIX only.

A point which fails is reported once, by its error: roadrunner logs the error of CVODE as well, so its log level is lowered while a chunk of a model of roadrunner runs. A feature which the engine does not simulate, the NotImplementedError of an executor, is the same for every point of a model and is no failed point: it is raised also with on_error="flag". The messages of SUNDIALS follow the log level of roadrunner (libroadrunner 2.11).

ScanPointError ¶

ScanPointError(index, message)

Bases: RuntimeError

A point of a scan failed and the run raises, see Chunk.on_error.

Attributes:

Name	Type	Description
`index`		the flat index of the point in the scan.
`message`		the error of the point.

Create the error of a point, the arguments pickle.

ModelSpec `dataclass` ¶

ModelSpec(
    key,
    engine,
    source,
    parameters,
    jit_optimization,
    integrator,
    settings,
    cache=None,
)

What a worker needs to load a model as the parent loaded it.

Attributes:

Name	Type	Description
`key`	`str`	identifies the model, its engine, its optimization level, its integrator and the settings of the integrator, the key of the model in the cache of a worker.
`engine`	`Engine`	the engine which simulates the model.
`source`	`str`	the SBML of the model as the parent loaded it, see `SBMLModel.sbml`, or the path of the file `parallel.shared_payloads` shares it in. It is flattened and the path is absolute, so nothing is resolved against a directory.
`parameters`	`tuple[tuple[str, float], ...]`	the parameters added to the model, see `AbstractModel`.
`jit_optimization`	`JitOptimization \| None`	the optimization level the model is compiled with, see `RoadrunnerSBMLModel.jit_optimization`: a worker compiles it at the level of the parent, whatever its environment says; `None` for a model of COPASI or AMICI, which roadrunner does not compile.
`integrator`	`str`	the name of the integrator, e.g. `cvode` or `lsoda`.
`settings`	`tuple[tuple[str, Any], ...]`	every setting of the integrator by its name, the absolute tolerance as the `AbsoluteTolerance` of the model.
`cache`	`str \| None`	the directory of the compiled models a model of AMICI was loaded from, which a worker loads it from as well, see `sbmlsim.model.model_amici.using_cache`; `None` for the other engines.

of `classmethod` ¶

of(model)

Get the spec of a loaded model and of the state of its integrator.

The integrator and its settings are read from the model after the simulator set its own, see SBMLModel.integrator_state, so a setting of the model which the simulator does not set, e.g. one of RoadrunnerSBMLModel(settings=...) or of set_integrator_settings, holds in a worker as well.

Parameters:

Name	Type	Description	Default
`model`	`SBMLModel`	the loaded model, of any engine.	required

load ¶

load()

Load the model in its engine with the integrator and its settings.

Chunk `dataclass` ¶

Chunk(
    indices,
    plan,
    model,
    graph,
    values,
    timed,
    time,
    on_error="raise",
)

Points of a scan which share a plan and a model.

Attributes:

Name	Type	Description
`indices`	`ndarray`	the flat indices of the points in the scan, in C order.
`plan`	`Plan`	the plan of the points.
`model`	`int`	the index of the model of the points among the models of the run.
`graph`	`ObservableGraph`	the observables of the run, which give the selections.
`values`	`dict[str, ndarray]`	target -> value of every point, which replaces the target wherever the plan sets it and is a change before the initialization otherwise.
`timed`	`dict[float, dict[str, ndarray]]`	time -> target -> value of every point, a change at that time.
`time`	`ndarray \| None`	the grid of times to interpolate the kept timecourses onto, `None` for the time points of the simulation.
`on_error`	`OnError`	what to do about a point which fails.

selections `property` ¶

selections

Get the selections of the engine, time first.

plan_of ¶

plan_of(k)

Get the plan of the k-th point of the chunk, see point_plan.

ChunkResult `dataclass` ¶

ChunkResult(indices, values, scalars, status, errors)

The answer of a chunk.

Attributes:

Name	Type	Description
`indices`	`ndarray`	the flat indices of the points, those of the chunk.
`values`	`ndarray`	the kept timecourses, `(point, row, column)` with the time first and the timecourses of the graph, padded with `NaN`.
`scalars`	`ndarray`	the kept values per simulation, `(point, column)` with the scalars of the graph.
`status`	`ndarray`	`0` for a point which ran, `1` for one which failed.
`errors`	`tuple[tuple[int, str], ...]`	the flat index and the error of the first `MAX_ERRORS` points which failed, in the order of the scan.

SharedChunkResult `dataclass` ¶

SharedChunkResult(indices, values, scalars, status, errors)

The answer of a chunk of a worker whose large arrays are in shared memory.

The fields of ChunkResult, of which values and scalars are a SharedArray when the worker wrote them into a segment, see sbmlsim.simulator.shared.

received ¶

received()

Get the ChunkResult, its arrays read from their segments.

Such an array is a read-only view on its segment, whose name is removed, so this is called once, in the parent, see sbmlsim.simulator.shared.receive.

point_plan ¶

point_plan(plan, values, timed, k)

Get the plan of the k-th point of values.

The values of the dimensions without a time are applied first, then the changes of the dimensions with one in time order, so a target in both has the value of the change at its time.

Parameters:

Name	Type	Description	Default
`plan`	`Plan`	the plan of the points.	required
`values`	`Mapping[str, ndarray]`	target -> value of every point.	required
`timed`	`Mapping[float, Mapping[str, ndarray]]`	time -> target -> value of every point.	required
`k`	`int`	the point.	required

Returns:

Type	Description
`Plan`	The plan with the values of the point.

run_chunk ¶

run_chunk(chunk, model)

Run the points of a chunk on a loaded model, see the module.

Parameters:

Name	Type	Description	Default
`chunk`	`Chunk`	the points.	required
`model`	`SBMLModel`	the loaded model of the chunk, of any engine.	required

Returns:

Type	Description
`ChunkResult`	The values of every point.

Raises:

Type	Description
`ScanPointError`	for the first point which fails, with `on_error="raise"`.
`NotImplementedError`	for a feature the engine does not simulate, also with `on_error="flag"`.

observe ¶

observe(graph, selections, solutions, plans)

Evaluate the observables on the native solutions of points.

The graph is evaluated on all solutions at once. If an observable fails the points are evaluated one at a time, each alone on its native solution without padding, so a point fails exactly when its own evaluation fails, whatever the other points are; the outputs of the points which succeed are stacked again, padded with NaN to the longest of them.

Parameters:

Name	Type	Description	Default
`graph`	`ObservableGraph`	the observables.	required
`selections`	`Sequence[str]`	the columns of the solutions, the time first.	required
`solutions`	`Sequence[ndarray]`	the native solutions of the points.	required
`plans`	`Sequence[Plan]`	their plans.	required

Returns:

Type	Description
`ndarray`	The time points `(n_points, n_rows)` padded with `NaN`, the kept
`dict[str, ndarray]`	outputs (a timecourse `(n_points, n_rows)`, a value per simulation
`list[tuple[int, str, BaseException]]`	`(n_points,)`) of the points which are left, in their order, and the
`tuple[ndarray, dict[str, ndarray], list[tuple[int, str, BaseException]]]`	points whose observable failed (the position in `solutions`) with
`tuple[ndarray, dict[str, ndarray], list[tuple[int, str, BaseException]]]`	their message and error.

run_chunk_in_worker ¶

run_chunk_in_worker(spec, chunk, segment=None)

Run a chunk in a worker process, on the model the worker keeps.

Parameters:

Name	Type	Description	Default
`spec`	`ModelSpec`	the model of the chunk and the settings of its integrator.	required
`chunk`	`Chunk`	the points.	required
`segment`	`str \| None`	the stem of the names of the segments of shared memory the arrays of the result are written into, `values` and `scalars` with the `SUFFIXES` of `sbmlsim.simulator.shared`; `None` returns the arrays through the pipe of the pool.	`None`

Returns:

Type	Description
`ChunkResult \| SharedChunkResult`	The values of every point, see `run_chunk`, with its large arrays in
`ChunkResult \| SharedChunkResult`	shared memory when `segment` is given.

quiet_roadrunner ¶

quiet_roadrunner()

Lower the log level of roadrunner to critical messages, then restore it.

roadrunner logs the error of CVODE of a point which fails, which the run reports as the error of the point.

simulator.worker¶

ScanPointError ¶

ModelSpec dataclass ¶

of classmethod ¶

load ¶

Chunk dataclass ¶

selections property ¶

plan_of ¶

ChunkResult dataclass ¶

SharedChunkResult dataclass ¶

received ¶

point_plan ¶

run_chunk ¶

observe ¶

run_chunk_in_worker ¶

quiet_roadrunner ¶

ModelSpec `dataclass` ¶

of `classmethod` ¶

Chunk `dataclass` ¶

selections `property` ¶

ChunkResult `dataclass` ¶

SharedChunkResult `dataclass` ¶