model.model_amici¶

The model of an SBML model in AMICI, see sbmlsim.model.model_sbml.

AmiciSBMLModel compiles the SBML of a model with AMICI (the optional extra amici) into a python extension, which is cached on disk (compiled_dir), and owns an instance of the compiled model and of its solver, CVODES. Its values are read and written in the selections of roadrunner, S the amount of a species, [S] its concentration, the id of a parameter or a compartment, the id of a reaction its rate, the id of a species reference its stoichiometry (a number, which AMICI folds into its equations) and time, with the numbers of the SBML, which AMICI keeps as they are. Every selection roadrunner makes by default is a state, a free parameter or an expression of AMICI or a number of the SBML, so the model is compiled without observables. A model of SBML level 1 or 2 is converted to level 3 version 2 first.

AMICI integrates the concentration of a species whose hasOnlySubstanceUnits is false and the amount of the other species, folds a compartment without a rule into the equations as a number and turns a parameter with an initial assignment into an expression, which follows its math during a simulation. The SBML which AMICI compiles (amici_sbml) therefore keeps every entity a change can set apart:

• a parameter without a rule, an initial assignment or an event is a free parameter of AMICI, which is set directly;
• a compartment without an assignment rule and a parameter with an initial assignment, a rate rule or an event are the targets of one event which never fires (TARGETS_EVENT), which makes them states of AMICI whose rate is 0 (or the one of their rate rule), so their value is the one at the initialization until a change or an event sets it;
• the species are states of AMICI anyway.

The initial value of every such state is an initial assignment of two free parameters which sbmlsim adds per entity, its value and its kind (VALUE_PREFIX, KIND_PREFIX): piecewise(value as amount, kind == 1, value as concentration, kind == 2, initial value of the SBML), the initial value of the SBML being its initial assignment or its number, an amount of a species whose state is a concentration divided by its compartment and vice versa (a conversion factor, a constant of SBML, stays a free parameter of AMICI). A pre-initialization sets these parameters and the free parameters, AMICI evaluates the initial state of the model from them in the order of its dependencies, so a target replaces its own initial assignment and every initial value which depends on it follows, as in roadrunner (RoadrunnerSBMLModel.initialize). A compartment whose number in the SBML is not finite (NaN) and which has no initial assignment stays a number of AMICI, which integrates no state which is not finite, and a change of it raises.

The current state of the model is its time, the states of AMICI and its free parameters, which the executor sets between two integrations; the values of the assignment rules and the rates of the reactions are the expressions of AMICI, which an integration of no length at the current time evaluates.

AMICI finds the roots of the triggers of the events of the model, the executor fires the events, see sbmlsim.simulator.executor_amici: every event of the model keeps its trigger in the SBML AMICI compiles and, instead of its assignments, sets two states of AMICI, that it fired in the integration and the time of its first execution (FIRED_PREFIX, FIRST_PREFIX, fired, first_times), which the executor sets to 0 before every integration (reset_events), so the first root of an integration is known exactly and the state of the model is the one before it. AMICI evaluates a comparison exactly at its threshold at the start of an integration as written (time <= 10 at the time 10 true, time > 10 false: its Heaviside variables are initialized from the sign of the root functions, a root of 0 as true) and keeps the value for the whole integration, since CVODES does not report a root at the start and the root function does not change its sign afterwards. The executor therefore shifts every comparison which is exactly at its threshold at the start of an integration by a little, so that AMICI finds the crossing when the operands move: every strict comparison of a trigger, a > b or a < b, is compiled shifted by a free parameter of AMICI, a > b + shift (SHIFT_PREFIX, comparisons, set_shifts), and so is every comparison of the maths AMICI integrates, the kinetic laws, the assignment rules and the rate rules, e.g. the condition of a piecewise in a rate (SWITCH_PREFIX, switches, set_switch_shifts, Switch): a > b + shift, a + shift < b, a >= b - shift and a <= b + shift, so a shifted comparison keeps its value at its threshold until the operands move by the shift in the direction which changes it, as roadrunner evaluates it at every step; a == b and a != b of a math are compiled as a <= b + shift && a >= b - shift and a < b - shift || a > b + shift, which is how AMICI compiles them without the shift. The trigger of every event starts true in the compiled SBML, so AMICI fires no event at the start of an integration; the events whose trigger is false before the time 0 (start_events) are fired by the executor at the start of a simulation, as the ones a change triggers. A feature which AMICI does not compile or simulates otherwise than roadrunner raises at the load, see _check_supported; a trigger which compares for equality, a == b or a != b, is refused there: AMICI has no root of it, and roadrunner fires it only where a step of its integrator lands on the equality. The priorities of the events and the persistence of their triggers are the executor's, see sbmlsim.simulator.changes.fire_events, so the compiled SBML has no priority and every trigger persistent, which AMICI imports.

AmiciSBML(
    sbml,
    flagged,
    not_a_number,
    start_events,
    events=(),
    comparisons=(),
    switches=(),
)

StrictComparison(event, left, right)

Switch(left, right)

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

values

time

state

free_parameters

not_a_number

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

set_time(time)

set_state(time, state)

prepare(timepoints)

rates(states)

fired(states)

first_times(states)

reset_events()

set_shifts(shifts)

set_switch_shifts(shifts)

output_transform(selections)

value(selection)

set_value(selection, value)

initialize(assignments)

reset()

simulated()

loaded_value(selection)

has_selection(selection)

set_selections(selections)

set_integrator_settings(**settings)

integrator_state()

set_integrator_state(state)

state_ids()

amici_sbml(sbml, symbols, label)

shift_ids(comparisons)

switch_ids(count)

cache_root()

using_cache(root)

cache_key(sbml)

module_name(key)

compiled_dir(sbml, label='model')

load_module(directory)

run_simulation()

vector_array(vector)