Release notes for sbmlsim 0.6.0

We are pleased to release the next version of sbmlsim including the following changes. This is a large release which reorganizes the repository in the same way as sbmlutils 0.10.0 and pymetadata 0.6.0, so it starts with what has to be changed in existing code.

Breaking changes

• the examples moved out of the package to examples/ in the repository: from sbmlsim.examples.experiments.midazolam import ... becomes from examples.midazolam import ..., run from the root of a checkout, and python -m sbmlsim.examples.example_timecourse becomes python -m examples.timecourse. The SED-ML examples of sbmlsim.combine.examples are examples/sedml, the sensitivity example of sbmlsim.sensitivity.example is examples/sensitivity, the PEtab experiments of sbmlsim.fit.pet are examples/petab, sbmlsim.interpolation.interpolation_example is examples/interpolation.py and the juliacall notes of sbmlsim.julia are examples/julia. They are documentation and are no longer installed with the package, which shipped megabytes of models and results

• sbmlutils >= 0.10.1 and pymetadata >= 0.6.1 are required, which reorganized their packages and their logging. sbmlsim no longer configures logging on import: every module got its logger from pymetadata.log.get_logger, which attached a rich handler and set a level, so an application had no say over the messages of the library. Modules use logging.getLogger(__name__), and sbmlsim.log.enable_rich_logging() is the opt-in for scripts, examples and interactive work. The rich console of scripts is sbmlsim.console.console

• unused dependencies dropped: pkdb-analysis, statsmodels, typst, bottleneck, psutil, setproctitle, plotly and altair, none of which the package imported. pyDOE dropped as well, its latest release does not provide the pyDOE module any more; the Latin hypercube sampling of sbmlsim.fit.sampling uses scipy.stats.qmc. dill (the cache of the sensitivity analysis uses pickle) and xmltodict (an unused SED-ML to JSON helper) are dropped, and pytest-cov from the dev extra, nothing measured coverage

• amici, basico, h5py, pypesto and juliacall are not dependencies; the comparison scripts and examples which use them import them optionally

• sbmlsim.combine.validation removed, a script which imported the uninstalled biosimulators_utils and the tests; the legacy tellurium code generation in sbmlsim.combine.sedml.task (SEDMLCodeFactory, Test) removed, it called methods which did not exist. sbmlsim.plot.plotting_deprecated_matplotlib.add_line removed, it used a private matplotlib API which no longer exists; add_data stays for the glucose example

• SimulationExperiment.from_json raises NotImplementedError, it called a from_dict which never existed. SimulationExperiment.data_path is a list of paths

• Report objects of sbmlsim.combine.sedml.report are not returned by SimulationExperiment.reports(), which returns the label to data generator mapping of every report as the base class always declared

• the fit and simulation experiment examples with post processing functions (examples/demo, examples/repressilator, examples/midazolam, examples/covid) currently fail in the evaluation of the function data and are not part of the example tests, see examples/README.md; the corresponding tests were already skipped

• library code no longer calls plt.show(); run_experiments and execute_sedml do not show figures by default

• minimum versions of all dependencies are the current releases, i.e., libroadrunner>=2.10.0, numpy>=2.5.3, pandas>=3.0.5, xarray>=2026.7.0, scipy>=1.18.1, matplotlib>=3.11.1, pint>=0.25.3, pydantic>=2.13.5, petab>=0.9.0, rich>=15.0.0, sbmlutils>=0.10.1 and pymetadata>=0.6.1; the tests run against exactly these versions

Fixes

The type checker surfaced a number of bugs, all of them fixed:

• sbmlsim.combine.sedml.parser: YAxisPosition.Right does not exist (RIGHT), a curve on the right y-axis of a SED-ML plot raised an AttributeError; axis.style.id does not exist (sid), styles of axes were never found; isSetName on an axis was tested instead of called, so every axis label was read; the x data of a curve was tested on the wrong variable; a marker line color was written as an object instead of its color string, which failed in libsedml (examples/midazolam/simulate.py); getSecondColor/setSecondColor do not exist on SedFill in libsedml, second colors of fills are skipped with a warning; get_ordered_subtasks was annotated with SedTask although it needs a SedRepeatedTask; the parser reports a missing simple task and an unsupported simulation type with a ValueError instead of returning None
• sbmlsim.combine.sedml.io: archives were searched for the format key sed-ml, which pymetadata 0.6 does not know (sedml), so no SED-ML file was found in any COMBINE archive
• sbmlsim.combine.mathml.evaluate passed all variables to the lambdified expression, which raised for a data generator whose formula does not use all of them; only the free symbols of the expression are passed now
• sbmlsim.comparison.diff used np.NaN, which numpy 2 removed
• sbmlsim.simulation.sensitivity: the difference and distribution scans read .magnitude of the reference values, which are floats; the units are taken from the model. difference_sensitivity_scan and distribution_sensitivity_scan take a RoadrunnerSBMLModel, as their implementation always required, not a roadrunner.RoadRunner
• sbmlsim.model.model_roadrunner.parameter_df read attributes which the libsbml objects do not have (units, constant, name), it uses the getters
• sbmlsim.fit.objects.FitParameter.__eq__ compared optional values with math.isclose, which raised for None
• sbmlsim.sensitivity.analysis: the chunking of samples for the worker processes bound loop variables late (B023)
• RoadrunnerSBMLModel.copy_roadrunner_model and the SED-ML data parser leaked temporary files
• sbmlsim.fit.optimization.OptimizationProblem.optimize was annotated with optimize.OptimizeResult, where optimize is the method itself, so inspecting the signature raised
• the examples were repaired: examples/timecourse.py imported modules which do not exist (sbmlsim.xresult, SimulatorSerialRR), examples/model_sensitivity.py used simulator.worker and XResult.mean_all_dims, examples/scan.py read a time coordinate which is _time, examples/curve_types/model.py was written against the sbmlutils API of 2020 (sbmlutils.creator, sbmlutils.examples.templates, UNIT_* constants) and is a Model definition of the current API, examples/initial_assignment lost its model file in 2021 and has it back from the history, examples/sedml/execute_omex.py imported tests.DATA_DIR

Features

• sbmlsim.log and sbmlsim.console: logging and rich console of the package, see Breaking changes
• SimulatorSerial.model_loaded and r_loaded, OptimizationProblem.runner_initialized, SensitivityAnalysis.samples_required and results_required: accessors which raise a clear ValueError instead of an AttributeError on None when a model, runner or result is not available yet
• MappingMetaData carries an outlier flag and to_dict, the base for application specific mapping metadata
• RuntimeErrorOptimizeResult carries x and x0 like a scipy OptimizeResult
• sbmlsim.units.Quantity is the type of the quantities of a unit registry (pint's PlainQuantity), used in all annotations

Documentation

• the documentation is built and published again, migrated from quarto to Zensical, the static site generator of the Material for MkDocs authors: markdown sources in docs/, configured in zensical.toml, built and published to https://matthiaskoenig.github.io/sbmlsim by a GitHub workflow on every push to develop. Nothing rendered is committed and _docs/ and the rendered docs/ are gone
• new user guides for models, timecourse simulations, parameter scans, units, simulation experiments, data, plots and reports, parameter fitting, sensitivity analysis and SED-ML with COMBINE archives. Every code block was run against the package
• API reference of all modules, rendered from the docstrings by mkdocstrings
• the documentation is available as markdown for agents and language models: llms.txt, llms-full.txt and every page next to its html. CLAUDE.md describes the repository itself
• examples/README.md describes what is where and how to run it
• a References page cites libroadrunner, SBML, SED-ML, the COMBINE archive, KISAO, PEtab and the sensitivity analysis methods
• README.md rewritten

Development

• mypy replaced by ty for type checking; ty runs in CI, in tox r -e ty and as a pre-commit hook. The # type: ignore comments are gone and the tree is at zero diagnostics
• more ruff rules (import sorting, docstrings, pyupgrade, bugbear, comprehensions, simplifications, returns, logging format) and additional pre-commit hooks (toml, json, case conflicts, line endings, forgotten debug statements). The blanket F403/F405 ignore of the star imports became a per file ignore of the examples and tests; log calls use lazy %s formatting instead of f-strings
• type annotations modernized to dict, list and X | None
• the project urls reach the metadata now: the table was written as [project_urls] instead of [project.urls], so it was silently ignored and the pypi page carried no links at all. Documentation points to the documentation site and a Changelog url was added. The license metadata follows PEP 639, i.e., license = "MIT" with license-files; .zenodo.json said LGPL-3.0 and says MIT now
• root configuration cleaned up: the pytest configuration moved from tox.ini to [tool.pytest.ini_options] in pyproject.toml, the unused pytest-raises dependency and its raises marker are gone, as is the install tox environment which nothing referenced. RELEASE.md moved into the documentation, .editorconfig, .quartoignore and .nojekyll are gone
• the committed results of the examples are untracked and ignored; the examples write into the current working directory and never open a window
• tests/examples/test_example_scripts.py runs the examples in a temporary working directory, so an example which breaks fails the test suite
• the workflows pin their actions, declare least privilege permissions, cancel superseded runs and time out; the test matrix covers linux, windows and macos and the release job publishes with trusted publishing. main.yml became ci-cd.yml, ty.yml and docs.yml were added; dependabot keeps the actions current
• CITATION.cff added and bumped with the version instead of _docs/_quarto.yml
• the generated AMICI model code and compiled extensions of sbmlsim.comparison are excluded from the distribution and from ruff and ty, they are only of use from a checkout

Your sbmlsim team