model.model_sbml¶

The SBML model independent of the engine which simulates it.

SBMLModel reads the SBML of a model once, flattens a hierarchical model, adds the parameters of its description and derives its symbols and units, which the compile step and the results need whatever engine simulates the model. An engine subclasses it with the model it loads, e.g. sbmlsim.model.model_roadrunner.RoadrunnerSBMLModel, and load_model is the one place a model of an engine is created.

IntegratorSettings ¶

Bases: TypedDict

The settings of the integrator a simulator takes, by their names in roadrunner.

The settings of CVODE, the integrator of roadrunner; COPASI takes relative_tolerance, absolute_tolerance, maximum_num_steps and maximum_time_step and ignores the others, see sbmlsim.model.model_copasi.CopasiSBMLModel.set_integrator_settings. sbmlsim.simulator.Simulator(**settings) checks the names and types of a dictionary of this type; a dictionary of settings of other names or types, dict[str, IntegratorSetting], e.g. of another integrator of roadrunner, is set with Simulator.set_integrator_settings or SBMLModel.set_integrator_settings, which take every name.

SBMLModel ¶

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

Bases: AbstractModel, ABC

An SBML model, loaded by an engine, see the module.

Attributes:

Name	Type	Description
`engine`	`Engine`	the engine which simulates the model.
`sbml`	`str`	the SBML of the model as sbmlsim hands it to the engine, flattened, before the added parameters: the units of the model are read from it and a worker loads it, so it derives the symbols and the units the parent has, see `sbmlsim.simulator.worker.ModelSpec`.
`hierarchical`	`bool`	whether the model uses the package `comp` of hierarchical models, i.e. `sbml` is its flattened SBML.
`symbols`	`ModelSymbols`	the symbols of the model with the added parameters.
`uinfo`	`UnitsInformation`	the units of the model.
`reported_triggers`	`set[str]`	the events whose trigger was reported as no formula the simulator evaluates, once per event of this instance (a worker of a pool loads its own instance and reports it once as well), see `sbmlsim.simulator.changes`.
`warned_start`	`bool`	whether the start of a simulation was reported, see `sbmlsim.simulator.executor`.
`selections_given`	`bool`	whether the selections were given, `False` for the default selections of the engine, see `default_selections`; a model loaded in another engine gets that engine's defaults, see `load_model`.

Read the SBML of the model, its symbols and its units.

The parameters are added to the model as constant parameters, see AbstractModel. The changes are normalized to the units of the model. The subclass loads the model in its engine from the SBML which _take_engine_sbml hands over, and sets the selections after it.

label `property` ¶

label

Get the name of the model in a message.

The id of the model, else the id of its SBML model, else the name of its SBML model, else model.

Q ¶

Q(value, unit=None)

Create a quantity in a unit of pint and of the unit ids of the model.

A unit id of the model is its expression, e.g. mg_per_min/kg is a milligram per minute and kilogram for a model whose unit definition mg_per_min is a milligram per minute, see UnitsInformation.quantity. sbmlsim.Q takes the units of pint only. A unit of pint, e.g. the units of a quantity, is taken as it is.

Parameters:

Name	Type	Description	Default
`value`	`Any`	the magnitude, a number or an array.	required
`unit`	`str \| PlainUnit \| None`	the unit, a string or a unit of pint, dimensionless without one.	`None`

Returns:

Type	Description
`Quantity`	The quantity.

Raises:

Type	Description
`UndefinedUnitError`	for a unit which is neither a unit of pint nor a unit id of the model.

parse_units ¶

parse_units(ureg)

Parse the units of the model from its SBML, see sbml.

A hierarchical model has the units of its flattened SBML, which include the ones of its submodels.

default_selections ¶

default_selections()

Get the selections of a model loaded without selections.

Every entity of the model which has a value, the selections roadrunner makes by default in its order: the time, the amounts of the floating and of the boundary species, the global parameters, the species references with an id whose species is a boundary species (roadrunner's global parameters, the other ones are entries of the stoichiometry matrix), the reactions and the compartments, then the concentrations of the floating and of the boundary species. The species, the parameters and the compartments are each in the order of the SBML with the entities without a rule first and the ones of a rate or an assignment rule after them, as roadrunner orders them (an initial assignment or an event assignment is no rule). The rule of the species references was determined empirically, against roadrunner on every case of the SBML Test Suite. A compartment whose size is NaN and set by no initial assignment or rule, e.g. a membrane whose area the model does not use, has no value to record (a compartment without a size has the size 1 in roadrunner); the parameters added to the model and the helpers of sbmlsim are not selected.

Returns:

Type	Description
`list[str]`	The selections.

initialize `abstractmethod` ¶

initialize(assignments)

Initialize the model with values before its initialization.

Parameters:

Name	Type	Description	Default
`assignments`	`Sequence[Assignment]`	the pre-initialization assignments of a plan.	required

reset `abstractmethod` ¶

reset()

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

simulated `abstractmethod` ¶

simulated()

Record that the model was simulated since its last initialization.

loaded_value `abstractmethod` ¶

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 `abstractmethod` ¶

value(selection)

Get the current value of a selection.

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 the model has no selection of the name, in every engine.

has_selection `abstractmethod` ¶

has_selection(selection)

Check whether the model has a selection of a name.

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_selections `abstractmethod` ¶

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`, see `selections_given`.	required

set_integrator_settings `abstractmethod` ¶

set_integrator_settings(**settings)

Set settings of the integrator.

Parameters:

Name	Type	Description	Default
`**settings`	`IntegratorSetting`	the settings by their names, `absolute_tolerance` a float or an `AbsoluteTolerance`.	`{}`

Raises:

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

integrator_state `abstractmethod` ¶

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 and not the tolerances of its states.

Returns:

Type	Description
`tuple[str, tuple[tuple[str, Any], ...]]`	The name of the integrator and its settings, sorted by name.

set_integrator_state `abstractmethod` ¶

set_integrator_state(state)

Set the integrator of the model and its settings, see integrator_state.

A worker of a pool loads a model with the state of the integrator of the model of the parent, see sbmlsim.simulator.worker.ModelSpec.

Parameters:

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

Raises:

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

state_ids `abstractmethod` ¶

state_ids()

Get the ids of the states which the integrator integrates.

Feature ¶

Bases: StrEnum

A feature of SBML which an engine other than roadrunner may not simulate.

EngineSettings ¶

EngineSettings(engine, integrator, label, log)

The settings of roadrunner in an engine which takes PORTABLE_SETTINGS.

Checks and validates the settings and reports, once per model, the ones the engine ignores and an absolute tolerance per kind which it takes as one number.

Create the settings of a model.

Parameters:

Name	Type	Description	Default
`engine`	`str`	the name of the engine in a message, e.g. `COPASI`.	required
`integrator`	`str`	the name of its integrator.	required
`label`	`str`	the name of the model in a message.	required
`log`	`Logger`	the logger of the engine, which reports.	required

checked ¶

checked(settings)

Check settings and get the ones the engine takes, validated.

A setting of roadrunner which the engine has no equivalent of is reported once per model and left out.

Parameters:

Name	Type	Description	Default
`settings`	`Mapping[str, IntegratorSetting]`	the settings by their names in roadrunner.	required

Returns:

Type	Description
`dict[str, float \| int \| AbsoluteTolerance]`	The settings of `PORTABLE_SETTINGS`: the absolute tolerance an
`dict[str, float \| int \| AbsoluteTolerance]`	`AbsoluteTolerance`, the maximum number of steps an integer, the
`dict[str, float \| int \| AbsoluteTolerance]`	others floats.

Raises:

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

scalar_tolerance ¶

scalar_tolerance(tolerance, factor=1.0)

Get the one absolute tolerance of the engine of a tolerance per kind.

The smallest tolerance of the kinds and of the overrides, reported once per model when they differ, times a factor of the engine.

Parameters:

Name	Type	Description	Default
`tolerance`	`AbsoluteTolerance`	the tolerance per kind.	required
`factor`	`float`	the factor of the engine, e.g. `COPASI_ATOL_FACTOR`.	`1.0`

Returns:

Type	Description
`float`	The absolute tolerance.

EngineValues ¶

EngineValues(model)

The current values of a model of an engine in the selections of roadrunner.

The ModelValues of sbmlsim.simulator.changes, with which an executor reads and sets values between two integrations, of a model with value and set_value, e.g. CopasiSBMLModel.

Get the values of a model.

getValue ¶

getValue(selection)

Get the current value of a selection, see the value of the model.

setValue ¶

setValue(selection, value)

Set the current value of a selection, see the set_value of the model.

description ¶

description(model)

Get the description of a loaded model, which loads it again in any engine.

It is what does not depend on the engine of the model: its sbml as the source, so a file rewritten or deleted after the model was loaded changes nothing, with the path of its file, its added parameters, its changes, its selections (none for the default selections, so the engine selects its own defaults, see SBMLModel.selections_given), its id, its name and its base path; a state set on the model is not part of it.

Parameters:

Name	Type	Description	Default
`model`	`SBMLModel`	a loaded model.	required

Returns:

Type	Description
`AbstractModel`	The description of the model.

load_model ¶

load_model(
    model,
    engine,
    *,
    ureg=None,
    jit_optimization=None,
    reload=False,
)

Load a model in an engine.

A model of the engine is the model itself, as it is: ureg and jit_optimization do not apply to it, unless reload loads it again. A model of another engine is loaded again from its description; a state set on the model of the other engine is not carried over.

Parameters:

Name	Type	Description	Default
`model`	`AbstractModel \| str \| Path`	a loaded model, the description of a model or its path or SBML.	required
`engine`	`Engine \| str`	the engine or its name.	required
`ureg`	`UnitRegistry \| None`	the unit registry of the units of the model, the registry of the package without one; a loaded model which is loaded again keeps its own without one.	`None`
`jit_optimization`	`JitOptimization \| str \| None`	the optimization level of the compilation of a model of roadrunner, see `sbmlsim.model.model_roadrunner.resolve_jit_optimization`.	`None`
`reload`	`bool`	load a model of the engine again as well, e.g. with another unit registry or optimization level.	`False`

Returns:

Type	Description
`SBMLModel`	The model of the engine.

Raises:

Type	Description
`ValueError`	for a name which is no engine.
`ImportError`	for the engine COPASI without python-copasi, AMICI without AMICI.

sbml_maths ¶

sbml_maths(model)

Get every math of a model with the name of its element, e.g. for a message.

reads_csymbol ¶

reads_csymbol(math_, url, kind)

Whether a math reads a csymbol, found by its type or its definition URL.

libsbml gives some csymbols no definition URL, e.g. rateOf, so a node is the csymbol if it has its type or its URL.

Parameters:

Name	Type	Description	Default
`math_`	`ASTNode \| None`	the math, `None` for none.	required
`url`	`str`	the definition URL of the csymbol.	required
`kind`	`int`	the type of libsbml of the csymbol, e.g. `AST_FUNCTION_DELAY`.	required

Returns:

Type	Description
`bool`	Whether a node of the math is the csymbol.

reads_delay ¶

reads_delay(math_)

Whether a math reads the delay csymbol, see reads_csymbol.

reads_rate_of ¶

reads_rate_of(math_)

Whether a math reads the csymbol rateOf, see reads_csymbol.

conversion_factors ¶

conversion_factors(model)

Get the conversion factors of a model and of its species, constants of SBML.

rate_rule_entities ¶

rate_rule_entities(model, symbols)

Get the parameters and compartments of rate rules, in the order of the SBML.

The states an engine integrates after its species, see SBMLModel.state_ids.

variable_features ¶

variable_features(model)

Get the features of a model which COPASI and AMICI do not simulate as roadrunner.

The algebraic rules, the stoichiometry maths, the species references which are not constant, the initial assignments of species references and the delay csymbol, each with its element for a message, e.g. the non-constant species reference 'B_sr' of the reaction 'J1'; an engine adds why it does not simulate it.

Parameters:

Name	Type	Description	Default
`model`	`Model`	the model of the SBML.	required

Yields:

Type	Description
`tuple[Feature, str]`	The feature and its element.

model.model_sbml¶

IntegratorSettings ¶

SBMLModel ¶

label property ¶

Q ¶

parse_units ¶

default_selections ¶

initialize abstractmethod ¶

reset abstractmethod ¶

simulated abstractmethod ¶

loaded_value abstractmethod ¶

value abstractmethod ¶

has_selection abstractmethod ¶

set_selections abstractmethod ¶

set_integrator_settings abstractmethod ¶

integrator_state abstractmethod ¶

set_integrator_state abstractmethod ¶

state_ids abstractmethod ¶

Feature ¶

EngineSettings ¶

checked ¶

scalar_tolerance ¶

EngineValues ¶

getValue ¶

setValue ¶

description ¶

load_model ¶

sbml_maths ¶

reads_csymbol ¶

reads_delay ¶

reads_rate_of ¶

conversion_factors ¶

rate_rule_entities ¶

variable_features ¶

label `property` ¶

initialize `abstractmethod` ¶

reset `abstractmethod` ¶

simulated `abstractmethod` ¶

loaded_value `abstractmethod` ¶

value `abstractmethod` ¶

has_selection `abstractmethod` ¶

set_selections `abstractmethod` ¶

set_integrator_settings `abstractmethod` ¶

integrator_state `abstractmethod` ¶

set_integrator_state `abstractmethod` ¶

state_ids `abstractmethod` ¶