API reference¶

Export of an SBML model as its system of ordinary differential equations.

OdeSystem.from_sbml analyses a model into its ODE system, which is rendered in the formats of FORMATS:

from sbmlode import OdeSystem

system = OdeSystem.from_sbml("model.xml")
code = system.render("python", simulator=True)
system.write("model.py")

The methods render, write and render_template of OdeSystem are the functions of the same names of this package, which take the system as their first argument.

The math of the model is written by the printers of sbmlode.printers, one per dialect, the text of the model through the helpers of sbmlode.text, the formats by sbmlode.formats: python, julia and R code, and typst, LaTeX and markdown documents (sbmlode.documents), e.g. system.write("model.typ").

FORMATS = {
    "python": Format(
        name="python",
        kind="code",
        template="python.py.jinja",
        suffixes=(".py",),
        printer="python",
        options={"simulator": True},
    ),
    "julia": Format(
        name="julia",
        kind="code",
        template="julia.jl.jinja",
        suffixes=(".jl",),
        printer="julia",
        options={"simulator": True},
        first_index=1,
    ),
    "r": Format(
        name="r",
        kind="code",
        template="r.R.jinja",
        suffixes=(".R", ".r"),
        printer="r",
        options={"simulator": True},
        first_index=1,
    ),
    "typst": Format(
        name="typst",
        kind="document",
        template="typst.typ.jinja",
        suffixes=(".typ",),
        printer="typst",
        options={"standalone": True, "symbols": "id"},
    ),
    "latex": Format(
        name="latex",
        kind="document",
        template="latex.tex.jinja",
        suffixes=(".tex",),
        printer="latex",
        options={"standalone": True, "symbols": "id"},
    ),
    "markdown": Format(
        name="markdown",
        kind="document",
        template="markdown.md.jinja",
        suffixes=(".md",),
        printer="latex",
        options={"standalone": True, "symbols": "id"},
    ),
}

Format(
    name,
    kind,
    template,
    suffixes,
    printer,
    options=dict(),
    first_index=0,
)

OdeSystem(
    info,
    compartments,
    species,
    amounts,
    parameters,
    species_references,
    functions,
    assignments,
    initial,
    reactions,
    odes,
    events,
    unsupported,
)

states

constants

assigned

quantities

from_sbml(source)

render(fmt, **options)

typeset(dialect='latex', symbols='id', wrap=None)

write(path, fmt=None, **options)

render_template(template, fmt='python', **options)

quantity(sid)

symbol(sid)

render(system, fmt, **options)

render_template(system, template, fmt='python', **options)

write(system, path, fmt=None, **options)

Analysis of an SBML model into its system of ordinary differential equations.

OdeSystem.from_sbml resolves the semantics of SBML core once, as roadrunner implements them, so that a format only prints what the system holds:

• States are the species which are neither constant nor boundary nor assigned and take part in a reaction, and every compartment, species, parameter and species reference with a rate rule. Every other quantity is constant or assigned; a quantity an event changes is constant between the events (Quantity.constant is the flag of SBML, Quantity.role the role in the system).
• Species are held as roadrunner holds them, in amount if hasOnlySubstanceUnits, else in concentration; the reaction terms of a species in concentration are divided by its compartment. A rate rule applies to the species as written.
• A species in concentration in a variable compartment (a rate rule, an assignment rule or an event changes the size) without a rule of its own is held as its amount n_<id> (OdeSystem.amounts, made unique against the ids of the model), the quantity SBML conserves when the size changes, and its concentration is the assignment S = n_S / V of origin concentration. The amount is a state if the species is a state, else a constant (roadrunner keeps the amount of a boundary or constant species when the size changes). An event which assigns the concentration assigns the amount n_S = S_new * V with the size at the execution before the event; an event which changes the size of the compartment of a species in concentration with a rate rule rescales it, S = S * V / V_new (EventAssignment keeps the value of SBML and this conversion apart, they are evaluated at different times). The state of an amount takes the place of its species in the order of the states.
• Conversion factors: the conversion factor of a species, else of the model, multiplies the reaction terms of the species.
• Stoichiometry is a number, or the id of the species reference if a rule, an initial assignment or an event sets it; a species reference with an id is a quantity of the system.
• Local parameters are renamed to <reaction id>_<id>, made unique, and are constant parameters of the system.
• rateOf(x) is replaced by the right hand side of x for a state, by 0 for a constant, by d(n/V)/dt for a concentration held as amount; the rate of another assigned variable is unsupported.
• Assignments (assignment rules, concentrations and reaction rates) are ordered by their dependencies, ties in the order of the document; a cycle is an error.
• Initial values at t=0 (OdeSystem.initial) are every state, every constant set by an initial assignment or converted between amount and concentration, every assigned variable and the reaction rates these depend on, in one order of their dependencies, so that an initial assignment of a rule and a rule of an initial assignment are both right.
• Events keep their trigger as written and get its continuous root function (events.trigger_root, of the trigger with its function definitions expanded); an event without an id is event<index>, one without a trigger never fires.
• Defaults as roadrunner holds them: a compartment without a size has the size 1 (its Quantity.value), a stoichiometry which is not set is 1, a reaction without a kinetic law has the rate 0; a rule, initial assignment, event assignment or function definition without math is ignored (L3V2).
• Constants in OdeSystem.initial are only those set by an initial assignment and those whose value is a conversion with another quantity (a species in concentration with an initial amount, divided by its compartment, and the reverse); every other constant has its value in Quantity.value, so that a value passed for it is kept.
• Unsupported constructs are collected as (construct, element id): algebraic rules, delay, fast reactions, distrib functions, an event assignment to a constant, a trigger without a continuous root function, the rate of an assigned variable. A comp model is flattened first, an L1 or L2 model read as L3V2.

Every math of the system is a deep copy owned by the system, so the document can be freed; a sum is written with the signs of its terms (astutil.signed_sum). The analysis itself is sbmlode.analysis. The dataclasses which hold math compare by identity (eq=False), a libsbml math has no value equality.

Symbol(sid, name, unit, sbo, kind, element=())

source

Quantity(
    symbol,
    value,
    constant,
    role,
    compartment=None,
    amount=None,
    boundary=None,
    conversion_factor=None,
    amount_of=None,
)

FunctionDefinition(symbol, arguments, body)

Assignment(variable, math, origin)

Participant(species, stoichiometry)

Reaction(
    symbol,
    reactants,
    products,
    modifiers,
    reversible,
    rate,
    local_parameters,
)

Ode(
    variable,
    rhs,
    origin,
    reaction_terms=None,
    volume=None,
    amount_of=None,
)

EventAssignment(variable, math, scale=None, divisor=None)

Event(
    symbol,
    trigger,
    root,
    initial_value,
    persistent,
    delay,
    priority,
    use_values_from_trigger_time,
    assignments,
)

ModelInfo(sid, name, level, version, notes, units, source)

The context of the document formats of the ODE export: typst, LaTeX and markdown.

A document describes the model to a reader in the sections of the specification: title and metadata, units, compartments, species, parameters, function definitions, initial assignments and assignment rules, reactions, the ODE system, events and the unsupported constructs. DocumentContext.build gives a template every text and every math of these as markup of its format, so that a template only lays them out:

• text (names, notes, units, flags) is escaped for the markup of the format with text.typst_text, text.tex_text or text.markdown_text, a unit additionally with its exponents as superscripts and its products as ·, mol·m³, and without ligatures, fl is two letters;
• an id is code, `k1` in typst and markdown, \texttt{k1} in LaTeX, and is checked to be an SId (ValueError otherwise, libsbml reads a document with any id, which could end the code and write markup; an unsupported element without an id is labelled by its metaid, an XML ID); an id of more than LONG_ID characters may break after an underscore in typst and LaTeX (#sym.zws, \allowbreak), which writes no character, so that a table with long ids fits the page;
• math is printed with the printer of the format, LatexPrinter for LaTeX and markdown (in $$ ... $$), TypstPrinter for typst, the ids written as the math symbols of symbols.typeset_names (symbols="id" or "name"): the rate of a reaction is v with the id as subscript, v_{\mathrm{J0}}, the amount of a species held as amount is n with the symbol of the species as subscript, n_{S};
• a long sum is a list of lines (DocumentPrinter.print_lines), which a template joins into the lines of an alignment; a line after the first begins with its sign.

The context holds:

• model: title (the name, else the id), plain_title (the title without the opportunities of line breaks and without math, text.tex_pdf_text, for the bookmarks of a PDF), id, level, version, source, sbmlode (the version which writes the document) and notes, the paragraphs of the notes;
• units: the units of the model, each with kind and unit;
• compartments, parameters: rows with symbol, id, long_id (whether the id is longer than LONG_ID, a template lets its column wrap), name, value (math, empty for a value given by a rule or a conversion), unit and constant; the parameters include the local parameters and the species references with an id; species additionally compartment (math, None for a species in amount without a compartment) and properties (amount or concentration, boundary and constant as text);
• functions: lhs (f(x, y)) and rhs;
• initial: the initial assignments and the initial values which are a conversion between amount and concentration, assignments: the assignment rules and the concentrations of the species held as amount, each with lhs, lines and origin;
• amounts: the species held as amount, with amount, species and compartment as math;
• reactions: symbol (v_{J0}), id, long_id, name, equation (math, 2 A + B ⟶ C, ⇌ if reversible, ∅ for no species), modifiers and local_parameters (math, comma separated), lines of the rate;
• odes: lhs (dS/dt), lines and origin, the right hand side written with the rates of the reactions and divided by the volume of a species in concentration ((v_1 - v_2)/V, in lines 1/V (v_1 - v_2 ...)), or the rate rule;
• events: id, name, trigger, delay, priority (math, None without), initial_value, persistent, use_trigger_values and assignments with lhs and rhs, the effective value with the conversion of a size, conversion (None, amount for the amount of a species in concentration, resized for a concentration whose compartment the event resizes to new, V^{new});
• unsupported: construct and id;
• options: the options of the rendering.

The headings, labels and sentences of a document are written by its template.

Wrap = Callable[['Symbol', str], str]

TypesetSystem(
    model,
    units,
    compartments,
    species,
    parameters,
    functions,
    initial,
    assignments,
    amounts,
    reactions,
    odes,
    events,
    unsupported,
)

TypesetEquation(variable, lhs, lines, origin)

TypesetReaction(
    variable,
    symbol,
    id,
    long_id,
    name,
    equation,
    modifiers,
    local_parameters,
    lines,
)

TypesetFunction(variable, id, name, lhs, rhs)

TypesetEvent(
    symbol,
    id,
    name,
    trigger,
    delay,
    priority,
    initial_value,
    persistent,
    use_trigger_values,
    assignments,
)

TypesetEventAssignment(
    variable,
    lhs,
    rhs,
    conversion,
    species,
    compartment,
    new,
)

TypesetUnsupported(construct, id, element)

TypesetModel(
    title,
    plain_title,
    id,
    level,
    version,
    source,
    sbmlode,
    notes,
)

TypesetUnit(kind, unit)

TypesetRow(
    symbol, id, long_id, name, value, unit, constant
)

TypesetSpeciesRow(
    symbol,
    id,
    long_id,
    name,
    value,
    unit,
    constant,
    compartment=None,
    properties="",
)

TypesetAmount(amount, species, compartment)

Reading and flattening of SBML documents.

read_document reads a document from a path or an SBML string and raises for a source which could not be read, flatten resolves the submodels of comp into one model. Both are what the analysis needs of sbmlutils' read_sbml and flatten_sbml_doc, on libsbml alone.

read_document(source)

flatten(doc)

The string of a unit definition, mmol/min.

The string is the one sbmlutils writes for a unit (sbmlutils.report.units), without pint: a unit is (multiplier * 10^scale * kind)^exponent, a term multiplier * 10^scale * kind is written with the closest SI prefix, ms, and a magnitude which is not 1 in front of it, 160 s; a factor which names a unit of its own is written by that name, min, hr, day, cm. A term of a dimensionless kind (dimensionless, item, avogadro) gets no prefix. A product is *, a quotient /, a term with a magnitude is grouped in parentheses when it is a factor of more, mmol/(160 s).

unit_term(factor, kind)

udef_to_string(udef, model=None)