Release notes for sbmlsim 0.8.4

A patch release of the simulation engine and of the core of sbmlsim: one way to set up a simulation with the semantics of PEtab v2, PEtab v2 problems read and evaluated exactly, and a library reduced to simulating, scanning, sensitivity and uncertainty, fitting, plotting and reporting.

Breaking changes

• Simulation, Change and SteadyState replace Timecourse and TimecourseSim (#245). The following are removed:

  • Timecourse, TimecourseSim, AbstractSim and time_offset.
  • ScanSim(mapping=...) and SimulatorSerial.run_timecourse.
  • The Q_ of experiments, runners, simulators and models.
  • The clamping of species inside a timecourse.

  The migration:

  • TimecourseSim([Timecourse(0, e1, n, changes=c1), Timecourse(0, e2, n, changes=c2)], time_offset=o) is Simulation(start=o, end=o + e1 + e2, preinit_changes=c1, changes=[Change(o + e1, c2)]).
  • self.Q_ is from sbmlsim import Q, and run_timecourse is run_simulation.
  • A scan of a later timecourse is a Dimension(..., at=<time>).

• The formula of a Data is the math of PEtab (#252). It is compiled like the formulas of changes and observables. max and min of a single argument still reduce over the data, so Y/max(Y) still normalizes. log(x) is now the natural logarithm; the SBML L3 syntax read it as base 10. Some functions of the old syntax now raise a ValueError: asin and the other names starting with a (use arcsin and so on), root, ceiling, floor and factorial. pi is passed as a parameter. See docs/data.md.

• The SED-ML leftovers and the code nothing used are removed (#252):

  • The SED-ML objects of sbmlsim.simulation: Algorithm, Calculation, the SED-ML Change, ComputeChange and the ranges. Dimension stays.
  • sbmlsim.result.datagenerator, sbmlsim.result.report and the hook SimulationExperiment.reports(), whose reports were never rendered.
  • sbmlsim.mathml. Its SBML math for the networks is sbmlsim.sciml.formula.
  • The downloads of models from URLs and BioModels. A model is a file or its SBML.
  • ModelChange, Data.Symbols and the parameter symbol of Data. A Data keeps its index, sid and name, and its new attribute selection holds the selection as given.
  • Functions without a caller, such as XResult.from_netcdf and Figure.from_plots, and the distribution argument of the sensitivity scans of ModelSensitivity, which had only the normal distribution.

• run_optimization rejects keyword arguments its optimizer does not accept before it runs, naming them in a TypeError. Before, every repeat failed separately. sampling is a named parameter with the same default.

Features

• The simulation engine (#245):
  • A simulation has start and end in its time_unit (negative times are allowed) and preinit_changes before the initialization of the model.
  • Its changes happen at absolute times: a Change at a vector of times is a multiple dosing, and a value is a number, a quantity or a formula.
  • An optional SteadyState pre-equilibrates the model.
  • The output is the steps of the integrator, exact times or steps.
  • A simulation is compiled into a Plan without units, which the executor runs on roadrunner.
  • Results keep the time points of every simulation, and XResult.interpolate gives a common grid.
  • A fit simulates exactly at the times of its data.
• PEtab v2 on the engine (#246). A PEtab v2 problem is read with its full semantics:
  • The parameters of the parameter table are in the model.
  • Conditions use formulas, the events they trigger are fired, and the steady state is the output at time = inf.
  • An observable which is a formula is an ObservableModel, so the model is not rewritten.
  • Noise formulas are supported, and the priors of PEtab v2 enter log_prior and unnorm_log_posterior.
  • The PEtab v2 test suite passes completely (pytest -m petab_testsuite).
  • 28 of the 35 problems of the benchmark collection agree with the collection and with the log-likelihoods of AMICI (pytest -m petab_benchmark).
• One unit registry, sbmlsim.units.ureg, with the quantity sbmlsim.Q (#245). The units of a model are expressions pint parses.
• The sensitivity analyses take dpi, the resolution of their figures, which was always 300 (#252).

Fixes

• A hierarchical model is flattened with libsbml (#251). roadrunner misses the package comp in a file with the line endings of Windows and in SBML given as a string, and then simulated the model without its submodels. An initial assignment of a model which enables comp, as the models of sbmlutils do, now follows a changed parameter.
• A change of a parameter which feeds an initial assignment reaches it (#245). Results change where this was hit. The changes of an AbstractModel are applied in a fit.
• No pool of sbmlsim forks a process which runs threads (#252). The pools of the SBML Test Suite runner and of the sensitivity analyses forked on python 3.13 on linux, which can deadlock. Using them also fixed the start method of the process, so a later fit forked as well. Every pool now takes its context from sbmlsim.utils.process_context, which uses forkserver where fork is the default, as python 3.14 does.
• A fit keeps its finished repeats when it is interrupted. This holds for a serial fit as for a parallel one. A parallel fit interrupted before any repeat finished raises the KeyboardInterrupt instead of reporting that every repeat failed (#252).
• The title of a small figure no longer overlaps the titles of its plots (#251).
• Units.udef_to_str no longer writes ^^ for a scaled unit with an exponent (#245).

Performance

• Importing sbmlsim no longer imports petab and torch (#252). import sbmlsim.experiment takes 0.85 s instead of 2.2 s, in every process and every worker of a parallel fit. petab is imported when the first formula is compiled.
• A fit with one worker runs in the calling process instead of in a pool of one process (#252).
• The residuals of the HCTZ fit take 0.042 s per evaluation instead of 0.079 s (#245). Reading a PEtab problem with thousands of experiments is no longer quadratic (#246).

Dependencies

• python-libsedml, pkpdutils and sbml4humans are no longer dependencies. pyyaml is declared; before, it was only installed through petab (#252).

Examples

• The examples follow one pattern for simulation experiments (#251): overrides are marked with typing.override, the methods follow the order of their dependencies, and the FIXMEs are resolved.
• The examples on julia and on the interpolation of data are removed (#252).

Development

• The tests take 140 s instead of 182 s on four workers (#252). This comes from the lazy import of petab, the serial fit for one worker, fit problems built once per session, and small figures and samples in the tested examples. Two assertions on wall time now compare against a reference measured in the same test.
• Only the jobs of the test matrix save the cache of uv, which ends the warnings Unable to reserve cache (#252).

Documentation

• The documentation is grouped into the core, sensitivity and uncertainty, parameter optimization and the test suites (#244).
• The plans and designs in docs/superpowers/ are no longer published (#252).
• The citation points at the Zenodo record of 0.8.3, and the Zenodo metadata describes the present package (#243).