Release notes for sbmlsim 0.19.0

The events at the start of a simulation follow the pre-initialization in every engine, absolute tolerances relative to the typical magnitude of every state, the SBML Test Suite pinned to its development branch, and the analyses of the tutorial as a workflow of simrun.

Results which change: with the default engine (roadrunner), an event whose trigger is false before the time 0 (initialValue="false") fires at the start with the values of the pre-initialization, as in COPASI, AMICI and the SBML Test Suite (#439). Before, roadrunner evaluated these triggers with the values of the model as loaded, before the pre-initialization was set:

• an event which the pre-initialization makes true did not fire, e.g. a dose at (dose > 0) with preinit_changes={"dose": 10}; it fires now, and the output at the start has the state after it,
• an event which the pre-initialization makes false fired anyway, e.g. the first dose of at (time >= tnext) with tnext moved to 2 was given at 0; it is given at 2 now,
• an event true in both fired with the values as loaded, e.g. preinit_changes={"dose": 0} still dosed the dose of the model; the event fires with the dose 0 now.

Models which dose through an event triggered by a parameter that a simulation sets before the initialization are affected, e.g. the ICG model of examples/comparison (IVDOSE_icg > 0). A simulation without such a pre-initialization, a change at the start and the events a change fires are unchanged.

Changes

• An event at the start fires with the values of the pre-initialization (#486). RoadrunnerSBMLModel.initialize resets the model without the events at the time 0 (model_roadrunner.reset_values), sets the values of the pre-initialization and fires these events after them (fire_initial_events), as libroadrunner does when the values are set before resetAll. The values as loaded are the ones before the events at the time 0, which reset() and loaded_value give. A model with a delayed event of initialValue="false" is generated again before an initialization without a simulation since the last one, as roadrunner's reset keeps the queue of delayed events. EventSymbols.initial_value is new. The known difference to COPASI and AMICI is removed from the documentation of the engines.

Features

• Absolute tolerances relative to the scale of a state (#487). AbsoluteTolerance(relative=..., scales=...) gives every state the tolerance relative times its scale, its value in scales or else the magnitude of its initial value in the model as loaded (the amount of a species); a state with neither keeps the tolerance of its kind, an override by id wins over both. So a small state, e.g. a drug in nM next to sodium in mM, is integrated with the same relative accuracy as a large one, which the finite differences of a fit, the Fisher information and the profiles need. sbmlsim.simulator.scales.typical_scales(simulator, model, simulations) gives the largest magnitude of every state in test simulations, e.g. the standard doses of a model, to be stored with the model; tolerances() of a model has the column scale. Without relative nothing changes. COPASI and AMICI keep one absolute tolerance. Measured in #435 on four PBPK models: rescaling the units of a model is the same as scaling these tolerances, so the models keep their units; on HCTZ the worst error relative to the scale of a state drops from 2.9e-8 to 1.3e-9.
• Workflows with simrun (#488). A new page of the documentation runs the analyses of the tutorial as one workflow of simrun (examples/hctz_fitting/workflows/tutorial.yaml: the simulation experiments, the dose scan, the Sobol indices, the uncertainty of the clearance, the fit, its profiles and its report), on the local machine with simrun submit --local or on a cluster, shows the web app, reads the results back and shows how to convert an analysis of a script into an analysis of a project. Every kind of the run layer has a description, which the task types of simrun show in the palette of the Editor, and the fields of a spec which the plan sets (units, scan_hash, run_plan, start_from, fixed_fits, fixed_values) are readOnly in its JSON Schema, which the Editor leaves out of the settings form.

Fixes

• The heading of a fit report is the id of the fit and not the directory of the report, which the kind report names report (#488).
• The cost test of AMICI times the fastest of three runs, so a busy runner does not fail it (#484).
• tox uses the interpreters of uv (uv_python_preference = only-managed): libroadrunner 2.11 for python 3.15 takes the symbols of the GDB JIT interface from the interpreter, which the python 3.15 of uv exports and e.g. the one of Ubuntu does not (undefined symbol: __jit_debug_register_code); the installation page says so for users of python 3.15 (#490).

Test suites

• The SBML Test Suite is pinned to a commit of its development branch (#485), SUITE_COMMIT, instead of its release 3.5.0, whose case 01511 is wrong; the fixed case passes, 1581 of the 1789 timecourse cases pass. The cases are downloaded from the archive of the commit, the baseline, the report and the submission record the commit, and testsuite-pin.yml opens a pull request when the cases change on the development branch of the suite.

Dependencies

• simrun 0.3.0 (#488). The simrun extra requires simrun>=0.3.0, which runs the unsplit task types of sbmlsim (sbmlsim.simulate, sbmlsim.report, ...) on the local machine and imports a task from the root of the model, so the examples of sbmlsim run through simrun without PYTHONPATH.