Release notes for sbmlutils 0.14.0

We are pleased to release the next version of sbmlutils including the following changes. This release replaces the ODE code generator sbmlutils.converters.odefac with the ODE export sbmlutils.converters.ode (#492), which writes the ordinary differential equations of an SBML model as python, julia and R code which simulates the model, and as typst, LaTeX and markdown documents which describe it. The generated code covers the semantics of SBML core including initial assignments and events and is verified against roadrunner over the SBML test suite (#481, #438). Code which uses one of the items under breaking changes has to be changed, see ODE export for the migration from SBML2ODE.

New features

• sbmlutils.converters.ode exports the ODE system of a model in six formats from one analysis and one math printer core: OdeSystem.from_sbml(source) reads a path, an SBML string or an SBMLDocument, render(fmt, **options) returns the output as a string, write(path) writes it with the format taken from the suffix and render_template(template) renders a jinja2 template of your own with the documented context (#492)
• the analysis resolves the semantics of SBML core once for every format: initial values, initial assignments and assignment rules at t = 0 in the order of their dependencies (#438), function definitions, local parameters, conversion factors, stoichiometries given by species references, rate rules on species, parameters, compartments and species references, rateOf, species in a compartment whose size changes, which are integrated as amounts, and events with delays, priorities, persistence, initial values and values from the trigger time. Algebraic rules, delay and fast reactions are reported as unsupported and refused by the code formats, never dropped in silence (#492)
• the math is printed from the libsbml AST with the exact SBML semantics in every language: rem and quotient truncate like C, log with a base, root with a degree, booleans used as numbers, lazy piecewise, and NaN instead of a domain error for math outside its domain (#492)
• python (numpy and scipy), julia (OrdinaryDiffEq.jl) and R (deSolve) code with the same structure: the ids, names and units of the states, constants and assigned values, initial_values(p), the right hand side, the assigned values and reaction rates, the events, and simulate(t_end, points=101, ...) returning a table of the states, the assigned values and the constants changed by events. simulator=False writes the right hand side and its helpers only. The step limit and the limit of cascaded events make a model which blows up fail fast (#492)
• the python, julia and R code simulates every case of the SBML semantic test suite (level 3 version 2) without an unsupported construct as roadrunner does, 1480 of 1481 cases in python and julia and 1479 of 1481 in R; the known failures are listed with their reasons. scripts/ode_report.py reports the coverage per language (#492)
• typst, LaTeX and markdown documents with the same sections: units, compartments, species and parameters as tables, function definitions, initial assignments and assignment rules, reactions with their equations and rates, the ODE system written with the reaction rates, events, and the unsupported constructs. standalone=False writes a fragment to include in a document, ids are typeset as math symbols (k_cat as k with subscript cat, k1 as k₁, tau_mRNA as τ with subscript mRNA) and symbols="name" uses the names of the elements (#492)
• every name, unit and note is written as text in every format, on a single line in the comments of code and escaped in documents, and every id written into code or a document is checked to be an SId (#492)
• the documentation has a new page ODE export with the output of every format for the repressilator, the options, the supported SBML and the migration from odefac (#492)

Breaking changes

• sbmlutils.converters.odefac with SBML2ODE and its templates is removed, use sbmlutils.converters.ode: SBML2ODE.from_file(path) is OdeSystem.from_sbml(path), to_python(path) is write(path), to_R, to_julia, to_markdown and to_tex are render("r" | "julia" | "markdown" | "latex"), and to_custom_template is render_template with a template written for the new context. SBML2ODE is no longer importable from sbmlutils.factory (#492)
• sbmlutils.converters.mathml with evaluableMathML is removed, it was only used by odefac (#492)
• pymetadata>=0.8.0: pymetadata 0.7 rejects COMBINE archive locations outside of the archive and drops the query string and the fragment of an identifiers.org URL, which the round trip comparison of the tests now follows (#492)

Behaviour changes

• create_model(create_markdown=True) writes the markdown document of the ODE export, with the equations as math in $$ ... $$ (#492)

Packaging and development

• scipy is part of the examples extra, it integrates the python code the ODE export writes; typst is part of the dev extra and a test dependency, the typst documents are compiled in the tests (#492)
• new tox environments and CI jobs julia, R and latex run the generated julia and R code against roadrunner and compile the LaTeX documents with tectonic; julia runs only for a release and on demand, since its packages take long to install; SBMLUTILS_JULIA and SBMLUTILS_RSCRIPT set the commands, docker works, see Development (#492)
• the documentation typesets math with MathJax, which is vendored into the site instead of loaded from a CDN, and compiles the typst pages it shows at build time (#492)
• the legacy example misc/odefac_example is removed (#492)
• continuous integration tests macOS and Windows only with python 3.14, python 3.15 only on Linux (#493)