AMICI: High-Performance Sensitivity Analysis for Large Ordinary Differential Equation Models

What's Changed

The AMICI 1.0 release comes with many changes related to making the API more consistent and modular. On the feature side, a highlight is support for the new PEtab 2.0 format for both the JAX and SUNDIALS interface.

With contributions by @BSnelling, @dilpath, @dweindl, @FFroehlich

BREAKING CHANGES

Removed functionality

The following functionality has been removed without replacement:

• The complete MATLAB interface has been removed.
• amici.sbml_import.species_to_parameters has been removed.

API changes

• For a more consistent API, all function names are now snake_case instead of camelCase.
• The package has been reorganized.
  • All importers have been moved to amici.importers subpackages. For example, all functionality from amici.sbml_import is now available in amici.importers.sbml.
  • All simulation-related functionality has been moved to amici.sim.sundials for the SUNDIALS interface, and amici.sim.jax for the JAX interface.
  • A number of functions and modules have been made private (i.e., their name starts with _ or they are excluded from __all__), as they are not intended for public use and may change without deprecation.
• The naming of free and fixed parameters has been harmonized across the API: AMICI differentiates between parameters with respect to which a model can compute sensitivities ("free parameters") and parameters with respect to which no sensitivities can be computed ("fixed parameters"). "Free" and "fixed" are to be understood in the context of parameter estimation, where free parameters are optimized, while fixed parameters remain constant. Free parameters were previously referred to as just "parameters", and fixed parameters as "fixed parameters", "constant parameters", or "constants". This has now been harmonized to "free" and "fixed" across the API. E.g., Model.setParameters() is now Model.set_free_parameters().
• ReturnDataView.posteq_numsteps and ReturnDataView.posteq_numsteps now return a one-dimensional array of shape (num_timepoints,) instead of a two-dimensional array of shape (1, num_timepoints).
• ReturnDataView.posteq_status and ReturnDataView.preeq_status now return list[SteadyStateStatus] instead of an ndarray[int] of shape (1, 3).
• The way the observation model is passed to the different import functions (sbml2amici, pysb2amici, ...) has changed: The information previously split across observables, sigmas, noise_distributions, event_observables, event_sigmas, and event_noise_distributions dicts is now passed as a single observation_model: list[MeasurementChannel] argument.
• assignmentRules2observables has been renamed to assignment_rules_to_observables and now returns list[MeasurementChannel] to be passed to the import functions.
• AmiVector::getLength and AmiVectorArray::getLength have been renamed to size to be more consistent with STL containers.
• amici.petab.petab_import.import_model has been removed. Use amici.importers.petab.v1.import_petab_problem instead.
• Model.getSolver has been renamed to Model.create_solver, emphasizing that a new Solver instance is created on each call.
• amici.runAmiciSimulation and amici.runAmiciSimulations have been renamed to amici.sim.sundials.run_simulation and amici.sim.sundials.run_simulations, respectively.
• The following deprecated functionality has been removed:
  • NonlinearSolverIteration::functional has been removed, use NonlinearSolverIteration::fixedpoint instead.
  • The deprecated argument log_as_log10 to SbmlImporter.sbml2amici and SbmlImporter.sbml2jax has been removed. Just remove this argument, as this never had any effect.
  • Deprecated imports from amici.petab.* in amici.petab.simulations have been removed. Import those functions directly from their respective modules.
  • The force_compile argument to import_petab_problem has been removed. See the compile_ argument.
• Model output directory keyword arguments have been harmonized: What was previously model_output_dir, output_dir, outdir is now consistently called output_dir across the API.
• Plotting functions have been moved from amici.plotting to amici.sim.sundials.plotting. The model argument has been removed.

Features

• Support for the PEtab data format v2.0.0 (draft) for the JAX and SUNDIALS interfaces.

  See amici.importers.petab.PetabImporter and examples for JAX and SUNDIALS.

  For JAX-based models, the interface can be considered stable; for SUNDIALS-based models, the API may still change.

  SBML- and PySB-based PEtab problems are currently supported. For PySB-based PEtab problems, only species and pysb.Expression are supported as condition table targets (i.e., no parameters yet).

  PEtab v1 import for SUNDIALS-based models is still available via amici.importers.petab.v1. Once PEtab v2 import has been stabilized, PEtab v1 import for SUNDIALS-based models will be removed.

• Many relevant ReturnData fields are now available as xarray.DataArray via ReturnData.xr.{x,y,w,x0,sx,...}. DataArrays include the identifiers and are often more convenient than the plain numpy arrays. This allows for easy subselection and plotting of the results, and conversion to DataFrames.

• Model.simulate() has been added as a convenience function to run simulations without having to create a Solver object explicitly. This is a wrapper for both amici.sim.sundials.run_simulation and amici.sim.sundials.run_simulations, depending on the type of the edata argument. It also supports passing some Solver options as keyword arguments. This is intended for interactive use; for better full control and performance, it is still recommended to create a Solver object and call amici.sim.sundials.{run_simulation,run_simulations} directly.

• Improved pickle support for amici.sim.sundials.{Model,ModelPtr,Solver,ExpData}. Note that AMICI's pickling support is only intended for short-term storage or inter-process communication. Reading pickled objects after updating AMICI or the model code will almost certainly fail.

  • Modeland ModelPtr now support sufficient pickling for use in multiprocessing contexts. This works only if the amici-generated model package exists in the same file system location and does not change until unpickling.
  • Solver is now picklable if amici was built with HDF5 support. This only works on shared file systems, as the solver state is stored in a temporary HDF5 file.
  • ExpData is now picklable.

• The import function sbml2amici, pysb2amici, and antimony2amici now return an instance of the generated model class if called with compile=True (default).

• The default directory for model import changed, and a base directory can now be specified via the AMICI_MODELS_ROOT environment variable. See amici.get_model_dir for details.

• IDs and names of model entities are now not only accessible via amici.sim.sundials.Model, but also via amici.sim.sundials.ReturnData (ReturnData.{free_parameter_ids,observable_ids,...}, ReturnData.free_parameter_names,observable_names,...}).

Fixes

• Fixed a bug that potentially results in incorrect handling of discontinuities their location depends on a state variable that is subject to an event assignment but otherwise constant.

Full Changelog: https://github.com/AMICI-dev/AMICI/compare/v0.34.1...v1.0.0