model.model_roadrunner¶

RoadRunner model.

RoadrunnerSBMLModel ¶

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

Bases: SBMLModel

The model of an SBML model in roadrunner, see SBMLModel.

Load the model into roadrunner, with changes, selections and settings.

The parameters are added to the model as constant parameters, see AbstractModel; they are not selected by default. The model is compiled at the optimization level jit_optimization, see resolve_jit_optimization for a level which is not given.

r_loaded `property` ¶

r_loaded

Get the roadrunner instance of the model.

Raises:

Type	Description
`ValueError`	if no model is loaded.

initialize ¶

initialize(assignments)

Initialize the model with values before its initialization.

PEtab v2 sets the values of the parameter table and of the first conditions on the model before it is initialized, so an initial assignment follows a changed parameter, and a target which is set replaces its own initial assignment. roadrunner reinitializes the model when an initial value is set with init(...), which costs a compilation of the model per value. The model is therefore initialized as it was loaded, the values are set as the current values, and the initial assignments which read a changed entity are evaluated again, in their order, from the assignment rule of their helper parameter, which roadrunner evaluates on the current values.

roadrunner queues the events which fire at the time 0 with every reset, a loaded model counts as one, and a simulation fires them once: a second reset without a simulation in between fires them twice (case 01757 of the SBML Test Suite). A model which was not simulated since its last reset is therefore not reset again, the values as loaded are set back instead (the values of an earlier initialization included), see _reset; simulated records a simulation.

A compartment keeps the concentration of the species whose initial value is a concentration, as at the initialization of SBML, and of a species which is set as a concentration, and the amount of every other species; a species of an assignment rule follows its rule. So does a compartment of an assignment rule which reads a changed entity (#344): roadrunner evaluates the rule with the new values and keeps the amounts, the concentration of such a species is set again after the entities its compartment depends on, before the initial assignments which read it.

Parameters:

Name	Type	Description	Default
`assignments`	`Sequence[Assignment]`	the pre-initialization assignments of a plan. A formula reads the parameters after the values are set.	required

reset ¶

reset()

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

A simulation leaves the model with the values of its pre-initialization and its state at its end until the next initialization, see initialize; a reader of the model, e.g. the references of a design, resets it after it read what it needs, so that nothing which reads the model later sees them (#315). Every parameter, compartment and species amount which is not the variable of an assignment rule is the one of the model as loaded afterwards, see _reset; roadrunner resets the model once per simulation, see initialize.

loaded_value ¶

loaded_value(selection)

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

The current value of the model depends on the simulations before it, see reset, the value as loaded does not (#315).

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.

simulated ¶

simulated()

Record that the model was simulated since its last initialization.

The next initialize resets the model, see there, and the time the simulation reached is kept, see discard_pending_events.

discard_pending_events ¶

discard_pending_events(horizon)

Discard the events of the simulation before which are still pending.

roadrunner's reset keeps the queue of the events of a model: an event with a delay which the simulation before triggered and which had not fired when it ended fires in the next simulation at its time, if that simulation reaches it (#305), also after an initialization without a simulation in between, e.g. the references of a design. Such an event is after the time the last simulation reached, so only a simulation which integrates beyond it can see it; for a model with an event with a delay the model is then generated again, which empties the queue (it costs milliseconds for a small model and tenths of a second for a large one). Every point of a scan reaches the same end, so a scan regenerates no model, unless it integrates to a steady state.

The selections and the absolute tolerances of sbmlsim are set again after it. The next initialization resets the new model, which queues its events at t0.

Parameters:

Name	Type	Description	Default
`horizon`	`float`	the time of roadrunner the next simulation integrates to, `inf` for an integration to a steady state.	required

from_abstract_model `staticmethod` ¶

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

Create from AbstractModel, see RoadrunnerSBMLModel.

load_roadrunner_model `classmethod` ¶

load_roadrunner_model(source, optimization=None)

Load model from given source.

:param source: path to SBML model or SBML string :param optimization: the optimization level of the compilation, see load_roadrunner :return: roadrunner instance

set_timecourse_selections `classmethod` ¶

set_timecourse_selections(r, selections=None, exclude=())

Set the selections of the simulations.

Without selections every entity of the model is selected, except a compartment without a size (NaN), e.g. a membrane whose area the model does not use, which has no value to record.

Parameters:

Name	Type	Description	Default
`r`	`RoadRunner`	the roadrunner instance.	required
`selections`	`list[str] \| None`	the selections, every entity of the model without.	`None`
`exclude`	`Collection[str]`	ids which are not selected by default, e.g. the parameters a problem added to the model.	`()`

Returns:

Type	Description
`list[str]`	The selections.

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, every entity of the model for `None`, see `set_timecourse_selections`; the parameters added to the model are not selected by default.	required

Raises:

Type	Description
`RuntimeError`	if roadrunner has no selection of a name.

value ¶

value(selection)

Get the current value of a selection of roadrunner.

Parameters:

Name	Type	Description	Default
`selection`	`str`	the selection, e.g. `S`, `[S]`, a parameter or a reaction.	required

Returns:

Type	Description
`float`	The value in the current state of the model.

Raises:

Type	Description
`RuntimeError`	if roadrunner has no selection of the name.

has_selection ¶

has_selection(selection)

Check whether roadrunner 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.

set_integrator_settings ¶

set_integrator_settings(**kwargs)

Set settings of the integrator.

Every setting of the integrator of roadrunner is passed on, for CVODE e.g. relative_tolerance, stiff, variable_step_size, initial_time_step, minimum_time_step, maximum_time_step and maximum_num_steps. absolute_tolerance, a float or an AbsoluteTolerance, is set as one tolerance per state, see sbmlsim.model.tolerances.

A setting the integrator has already is not set again, so that a simulator which applies its settings before every simulation costs nothing: the tolerances of the states are computed again only for another tolerance, another instance of roadrunner or a vector of CVODE which was set elsewhere. They are computed from the initial volumes of the compartments of the model as loaded, so a simulation does not depend on the pre-initialization of the one before it.

Parameters:

Name	Type	Description	Default
`**kwargs`	`IntegratorSetting`	the settings by their names in roadrunner.	`{}`

Raises:

Type	Description
`ValueError`	if the integrator has no setting of a name, or an override of the absolute tolerance is not a state.

integrator_state ¶

integrator_state()

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

The absolute tolerance is the AbsoluteTolerance of the model, from which set_integrator_settings computes the tolerance of every state, and not the vector of the integrator.

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 integrator of the model and its settings, see integrator_state.

Parameters:

Name	Type	Description	Default
`state`	`tuple[str, tuple[tuple[str, Any], ...]]`	the name of the integrator, e.g. `cvode`, and its settings.	required

Raises:

Type	Description
`ValueError`	if the integrator has no setting of a name.

sbml_ids ¶

sbml_ids()

Get the constant parameters and the species of the SBML roadrunner simulates.

They are read from the SBML of the instance of roadrunner (getSBML(), i.e. with the added parameters and the helpers of the initial assignments) once per instance and kept: serializing and parsing the SBML again on every call took 4.8 s of the 8.6 s of the initialization of the experiments of the acetaminophen model of pkdb_models (403 kB of SBML), which call sampling.parameters_of for 133 simulations (#332). An instance which replaces r is read again. sbmlsim never changes the structure of its instance (regenerateModel keeps the SBML); an edit of the instance itself, e.g. r.addParameter(...) or r.removeSpecies(...), is not tracked, and the ids stay those of the instance as first read until r is replaced.

Returns:

Type	Description
`SBMLIds`	The ids, in the order of the SBML.

state_ids ¶

state_ids()

Get the ids of the states which the integrator integrates.

The states of roadrunner's state vector, the targets of rate rules first, then the independent floating species, in the order of getRatesOfChange and of the tolerance vector of CVODE. They are counted by the rates of change, not by the tolerance vector, which is empty for another integrator than CVODE.

tolerances ¶

tolerances()

Get the absolute tolerance of every state.

Returns:

Type	Description
`DataFrame`	A row per state with `sid`, `kind`, `compartment` (the compartment
`DataFrame`	of a species, amount and concentration, empty for another state),
`DataFrame`	`volume` (the reference volume of a concentration species, which
`DataFrame`	scales its tolerance, empty for another state) and
`DataFrame`	`absolute_tolerance`.

parameter_df `staticmethod` ¶

parameter_df(r)

Create GlobalParameter DataFrame.

:return: pandas DataFrame

species_df `staticmethod` ¶

species_df(r)

Create FloatingSpecies DataFrame.

:return: pandas DataFrame

SBMLIds `dataclass` ¶

SBMLIds(constant_parameters, species)

The ids of the SBML of a model, see RoadrunnerSBMLModel.sbml_ids.

Attributes:

Name	Type	Description
`constant_parameters`	`tuple[str, ...]`	the parameters which are constant.
`species`	`tuple[str, ...]`	the species.

reset_all ¶

reset_all(r)

Reset a model to its initial values, as RoadRunner.resetAll.

roadrunner exposes the symbols of a model as attributes, so a model with a species or parameter named reset hides the method reset, which resetAll calls (case 00952 of the SBML Test Suite). The binding is called directly.

The reset queues the events which fire at the time 0 at the integration start time of the integrator and of the model, which every simulate sets to its start: after a simulation whose last integration started later, e.g. at the end of a simulation with events, the events at the time 0 fired at that time plus their delay, i.e. after the end of the next simulation (#305). Both are set to 0 first.

Parameters:

Name	Type	Description	Default
`r`	`RoadRunner`	the roadrunner instance.	required

apply_pending_step_event ¶

apply_pending_step_event(r)

Apply an event which the integrator keeps pending after a simulation.

An integration with the steps of the integrator whose last step of CVODE found the root of an event after the end leaves that event pending in the integrator, which neither a reset nor the next simulate clears (variableStepPendingEvent of CVODEIntegrator, roadrunner #1381): the first call of the integrator of the next simulation applies it with the states of the triggers before it, and an event whose trigger is not persistent misses its next rise (case 01590 of the SBML Test Suite). The integrator is called once with exact output at the time of the model, which applies such an event after the simulation, and does not integrate without one.

Parameters:

Name	Type	Description	Default
`r`	`RoadRunner`	the roadrunner instance after a simulation.	required

resolve_jit_optimization ¶

resolve_jit_optimization(level=None)

Get the optimization level of the compilation of a model.

Parameters:

Name	Type	Description	Default
`level`	`JitOptimization \| str \| None`	the level, e.g. `"O0"`. Without one, the level of `JIT_OPTIMIZATION_VARIABLE` or else `DEFAULT_JIT_OPTIMIZATION`.	`None`

Returns:

Type	Description
`JitOptimization`	The level.

Raises:

Type	Description
`ValueError`	if the level is none of `JitOptimization`.

load_roadrunner ¶

load_roadrunner(source, optimization=None)

Load an instance of roadrunner, its model always compiled (#313).

roadrunner (2.10 and 2.11) takes the compiled model of a new instance from its cache in the process when another instance of the same SBML is alive, and the data of such a model has no piecewise triggers (createModelData(..., 0) in LLVMModelGenerator::createModel): CVODE's root finding does not stop at the switch of a piecewise of the model, and the instance integrates a few 1e-9 apart from a compiled one. Which instance is alive differs between the first experiment of a run, the later ones, a serial run and the workers of a pool, so a model is compiled whenever it is loaded (LoadSBMLOptions.RECOMPILE), which also keeps it out of the cache. The compilation is paid once per loaded model, i.e. once per model of an ExperimentRunner and of a worker of a pool, and an instance no longer shares its code with another one.

The model is compiled with LLJIT at the given optimization level, see JitOptimization, which compiles faster than roadrunner's default JIT, MCJIT. Up to libroadrunner 2.10 LLJIT crashed when the code of a model and its jump tables were more than 2 GiB apart (#331, roadrunner #1368), e.g. when a model was compiled again while an earlier instance of it was alive. The memory the compilation freed is returned to the system (sbmlsim.memory.release_freed_memory).

LLJIT of libroadrunner 2.11 keeps the code of an SBML once it compiled it in the process, also after the instance was released and also with RECOMPILE, and gives a later compilation of the same SBML at another optimization level that code: a model compiled at O0 (e.g. by sbmlsim.sensitivity.parameters.parameters_from_sbml) made every later instance of the model in the process an O0 one, which integrates a little apart from the O2 instances of the workers of a pool. The SBML roadrunner compiles carries its level as a comment (_with_level), so the code of one level is never the code of another; a model which references models of other files (externalModelDefinition) is flattened first.

Parameters:

Name	Type	Description	Default
`source`	`str \| Path`	the path of an SBML file or the SBML itself.	required
`optimization`	`JitOptimization \| str \| None`	the optimization level of the compilation, see `resolve_jit_optimization` for a level which is not given.	`None`

Returns:

Type	Description
`RoadRunner`	The instance.

model.model_roadrunner¶

RoadrunnerSBMLModel ¶

r_loaded property ¶

initialize ¶

reset ¶

loaded_value ¶

simulated ¶

discard_pending_events ¶

from_abstract_model staticmethod ¶

load_roadrunner_model classmethod ¶

set_timecourse_selections classmethod ¶

set_selections ¶

value ¶

has_selection ¶

set_integrator_settings ¶

integrator_state ¶

set_integrator_state ¶

sbml_ids ¶

state_ids ¶

tolerances ¶

parameter_df staticmethod ¶

species_df staticmethod ¶

SBMLIds dataclass ¶

reset_all ¶

apply_pending_step_event ¶

resolve_jit_optimization ¶

load_roadrunner ¶

r_loaded `property` ¶

from_abstract_model `staticmethod` ¶

load_roadrunner_model `classmethod` ¶

set_timecourse_selections `classmethod` ¶

parameter_df `staticmethod` ¶

species_df `staticmethod` ¶

SBMLIds `dataclass` ¶