Skip to content

model.model_core

The model of an SBML model in the engine core, see sbmlsim.model.model_sbml.

CoreSBMLModel compiles the SBML of a model with the bindings of sbmlsim-core (sbmlsim.engine.import_core): the compiler writes it as a WebAssembly module with a description of the contract model/2 (its states, parameters and selections), which the runtime of the engine loads into a LoadedModel. The compiled model of an SBML is kept per process and shared by every model of that SBML (COMPILED), and the runtime, which compiles the engine itself, is created once (runtime): the HCTZ model compiles in 3 ms and loads in 4 ms, while the runtime takes 51 ms.

The engine is stateless: a simulation is a request of the contract simulation/1 which carries the values set before the initialization, the changes, the output and the settings of the integrator, and a model holds nothing of the simulations which ran. initialize therefore records the pre-initialization assignments which the executor sends with its request, reset records none and simulated records nothing, and value is the value of the model as loaded, as loaded_value.

The values of the model are read in the selections of roadrunner, S the amount of a species, [S] its concentration, the id of a parameter, a compartment or a reaction (its rate) and time, which every request answers as its first column and the description does not list.

The settings of the integrator have the names of roadrunner, CVODE in either engine: the ones a request has a field for are taken (REQUEST_SETTINGS), the other settings of roadrunner are ignored with one report per model (IGNORED_SETTINGS), and request_settings is the complete settings of a request, with the absolute tolerance of every state as roadrunner computes its vector of CVODE, see sbmlsim.model.tolerances.

A model the compiler refuses, e.g. one with an algebraic rule, the delay csymbol, a fast reaction or a package it requires, raises UnsupportedModelError with the message of the compiler, which names the feature, and so does a model the engine cannot load, so that nothing of the bindings reaches a caller of load_model.

CoreSBMLModel

CoreSBMLModel(
    source,
    base_path=None,
    changes=None,
    sid=None,
    name=None,
    selections=None,
    ureg=None,
    settings=None,
    parameters=None,
)

Bases: SBMLModel

The model of an SBML model in the engine core, see the module.

Attributes:

Name Type Description
loaded Any

the compiled model of the engine, a LoadedModel of the bindings, shared by every model of the same SBML, see COMPILED.

description dict[str, Any]

the description of the compiled model, model/2.

assignments tuple[Assignment, ...]

the pre-initialization assignments which were recorded last and which the executor sends with its request, see initialize.

absolute_tolerance AbsoluteTolerance

the absolute tolerance set last, see set_integrator_settings.

Compile the model with the engine, with changes, selections and settings.

The parameters are added to the model as constant parameters, see AbstractModel; they are not selected by default. The compiled model is shared by every model of the same SBML, see compiled_model.

Raises:

Type Description
UnsupportedModelError

for a model the compiler of the engine refuses, e.g. one with an algebraic rule.

ValueError

for a selection the model has not, or an unknown setting.

ImportError

if the bindings of sbmlsim-core are not installed.

from_abstract_model staticmethod

from_abstract_model(
    abstract_model,
    selections=None,
    ureg=None,
    settings=None,
)

Create from AbstractModel, see CoreSBMLModel.

initialize

initialize(assignments)

Record the values which are set before the initialization of the model.

The engine is stateless, the values of a simulation are the preinit of its request: the assignments are recorded for the executor, which sends them, and nothing is set on the model, see the module.

Parameters:

Name Type Description Default
assignments Sequence[Assignment]

the pre-initialization assignments of a plan.

required

reset

reset()

Set the model to the state it was loaded in, without a simulation.

The engine holds no state of a simulation, so only the recorded pre-initialization is dropped, see initialize.

simulated

simulated()

Record that the model was simulated since its last initialization.

Nothing is recorded: a request of the engine carries every value of its simulation, so a simulation does not depend on the one before it, see the module.

loaded_value

loaded_value(selection)

Get the value of a parameter, a compartment or a species of the model as loaded.

Parameters:

Name Type Description Default
selection str

the id of a parameter, a compartment or a species (its amount), or [S], the concentration of the species S.

required

Returns:

Type Description
float

The value as loaded.

Raises:

Type Description
KeyError

if the selection is none of these.

value

value(selection)

Get the current value of a selection.

The engine is stateless, a model holds no values of a simulation: the value is the one of the model as loaded, and time is 0, the time a model is initialized at, see the module.

Parameters:

Name Type Description Default
selection str

the selection, e.g. S, [S], a parameter, a compartment, a reaction or time.

required

Returns:

Type Description
float

The value of the model as loaded.

Raises:

Type Description
RuntimeError

if the engine has no selection of the name, as roadrunner.

has_selection

has_selection(selection)

Check whether the engine has a selection of a name in the model.

Parameters:

Name Type Description Default
selection str

the name, e.g. S, [S], a parameter or time.

required

Returns:

Type Description
bool

Whether the loaded model can select it. time is the first

bool

column of every request and no selection of the description.

set_selections

set_selections(selections)

Set the selections of the simulations of the model.

Parameters:

Name Type Description Default
selections Sequence[str] | None

the selections, default_selections for None.

required

Raises:

Type Description
ValueError

if the engine has no selection of a name.

set_integrator_settings

set_integrator_settings(**settings)

Set settings of the integrator, CVODE of the engine.

The settings have the names of roadrunner; a request of the engine has a field for absolute_tolerance (a float or an AbsoluteTolerance, sent as the tolerance of every state, see request_settings), relative_tolerance, maximum_num_steps, maximum_time_step, initial_time_step and stiff (REQUEST_SETTINGS). A setting of roadrunner which it has no field for, e.g. variable_step_size, which the output of a request states instead, is ignored and reported once per model (IGNORED_SETTINGS).

Parameters:

Name Type Description Default
**settings IntegratorSetting

the settings by their names in roadrunner.

{}

Raises:

Type Description
ValueError

if neither the engine nor roadrunner has a setting of a name, or a value is not valid.

request_settings

request_settings()

Get the settings of the integrator of a request of the engine.

The complete settings of a request of simulation/1: the settings which were set (set_integrator_settings), the defaults of the contract for the ones which were not (DEFAULT_SETTINGS, the defaults of roadrunner) and the settings which the engine chooses (ENGINE_SETTINGS).

The absolute tolerance is the tolerance of every state in the order of state_ids, {"per_state": [...]}, computed as roadrunner computes its vector of CVODE, from the initial volumes and the initial values of the model as loaded, see sbmlsim.model.tolerances: a float setting is the tolerance of every kind (AbsoluteTolerance.of), as in roadrunner, so the engine integrates with its tolerances and not with one number, which {"scalar": value} of the contract would be.

Returns:

Type Description
dict[str, object]

The settings of a request.

integrator_state

integrator_state()

Get the name of the integrator of the model and every one of its settings.

The settings have the names of roadrunner and are every setting of a request, the defaults of the contract for the ones which were not set, so that two models of equal settings have one state whatever was set on them (the key of a worker of a pool, see sbmlsim.simulator.worker.ModelSpec) and set_integrator_state is the inverse of this. The absolute tolerance is the AbsoluteTolerance of the model and not the tolerances of its states, see request_settings.

Returns:

Type Description
tuple[str, tuple[tuple[str, Any], ...]]

The name of the integrator and its settings, sorted by name.

set_integrator_state

set_integrator_state(state)

Set the settings of the integrator, see integrator_state.

Parameters:

Name Type Description Default
state tuple[str, tuple[tuple[str, Any], ...]]

the name of the integrator, cvode, and its settings.

required

Raises:

Type Description
ValueError

if the integrator is not the one of the engine, or it has no setting of a name.

state_ids

state_ids()

Get the ids of the states which the integrator integrates.

The states of the state vector of the engine, in the order of the states of the description, which a tolerance per state follows: the species which reactions or a rate rule change, in the order of the SBML, then the other targets of rate rules.

runtime cached

runtime()

Get the runtime of the engine of this process, created once.

The runtime compiles the engine and its math library, 51 ms, and loads the models of the process, see compiled_model.

Returns:

Type Description
Any

The Runtime of the bindings.

Raises:

Type Description
ImportError

if the bindings of sbmlsim-core are not installed.

compiled_model

compiled_model(
    sbml,
    *,
    optimize=OPTIMIZE,
    jacobian=JACOBIAN,
    label="model",
)

Compile an SBML with the engine and load it, once per SBML in this process.

The compiled model of an SBML and its compile options is kept in COMPILED and shared by every model of them: it is the module of the engine and its description, which a simulation does not change, while the values of a simulation are the ones of its request.

Parameters:

Name Type Description Default
sbml str

the SBML of the model, level 3, as the engine compiles it, see SBMLModel._take_engine_sbml.

required
optimize bool

whether the compiler optimizes the module.

OPTIMIZE
jacobian str

the Jacobian the compiler writes.

JACOBIAN
label str

the name of the model in a message.

'model'

Returns:

Type Description
Any

The LoadedModel of the bindings.

Raises:

Type Description
UnsupportedModelError

naming the feature, for a model the compiler refuses, and for one the engine cannot load, so that nothing of the bindings reaches a caller of load_model.

ImportError

if the bindings of sbmlsim-core are not installed.