Move symbolic model and utils to amici._symbolic (#3058)

Closes #3040.

Author: dweindl

.github/workflows/test_sbml_semantic_test_suite.yml

@@ -8,8 +8,7 @@ on:
     paths:
       - .github/workflows/test_sbml_semantic_test_suite.yml
       - python/sdist/amici/exporters/sundials/de_export.py
-      - python/sdist/amici/de_model_components.py
-      - python/sdist/amici/de_model.py
+      - python/sdist/amici/_symbolic/**
       - python/sdist/amici/importers/sbml/**
       - python/sdist/amici/importers/utils.py
       - scripts/run-SBMLTestsuite.sh

.gitignore

@@ -7,6 +7,7 @@ swig/python/build/*
 tests/cpp/build/*
 tests/cpp/build_xcode/*
 tests/cpp/Testing/*
+.cache/
 
 doc-venv/*
 fonts/*

doc/python_modules.rst

@@ -29,8 +29,6 @@ AMICI Python API
    amici.importers.petab.v1.simulator
    amici.jax
    amici.exporters.sundials.de_export
-   amici.de_model
-   amici.de_model_components
    amici.plotting
    amici.pandas
    amici.logging

python/sdist/amici/_symbolic/__init__.py

@@ -0,0 +1,13 @@
+"""
+Private functionality for symbolic model generation and manipulation.
+
+This module provides tools to create, modify, and analyze symbolic
+representations of differential equation models used in AMICI.
+Most symbolic functionality is provided by `SymPy <https://www.sympy.org/>`_.
+"""
+
+from .de_model import *  # noqa: F403
+from .de_model_components import *  # noqa: F403
+from .sympy_utils import *  # noqa: F403
+
+__all__ = de_model.__all__ + de_model_components.__all__ + sympy_utils.__all__

python/sdist/amici/de_model.py python/sdist/amici/_symbolic/de_model.pypython/sdist/amici/de_model.py renamed to python/sdist/amici/_symbolic/de_model.py

@@ -16,6 +16,22 @@
 import sympy as sp
 from sympy import ImmutableDenseMatrix, MutableDenseMatrix
 
+from amici.exporters.sundials.cxx_functions import (
+    nobody_functions,
+    sensi_functions,
+    sparse_functions,
+    var_in_function_signature,
+)
+from amici.exporters.sundials.cxxcodeprinter import csc_matrix
+from amici.importers.utils import (
+    ObservableTransformation,
+    _default_simplify,
+    amici_time_symbol,
+    toposort_symbols,
+    unique_preserve_order,
+)
+from amici.logging import get_logger, log_execution_time, set_log_level
+
 from .de_model_components import (
     AlgebraicEquation,
     AlgebraicState,
@@ -39,21 +55,6 @@
     SigmaZ,
     State,
 )
-from .exporters.sundials.cxx_functions import (
-    nobody_functions,
-    sensi_functions,
-    sparse_functions,
-    var_in_function_signature,
-)
-from .exporters.sundials.cxxcodeprinter import csc_matrix
-from .importers.utils import (
-    ObservableTransformation,
-    _default_simplify,
-    amici_time_symbol,
-    toposort_symbols,
-    unique_preserve_order,
-)
-from .logging import get_logger, log_execution_time, set_log_level
 from .sympy_utils import (
     _parallel_applyfunc,
     smart_is_zero_matrix,

python/sdist/amici/de_model_components.py …t/amici/_symbolic/de_model_components.pypython/sdist/amici/de_model_components.py renamed to python/sdist/amici/_symbolic/de_model_components.py python/sdist/amici/de_model_components.py renamed to python/sdist/amici/_symbolic/de_model_components.py

@@ -6,8 +6,8 @@
 
 import sympy as sp
 
-from .constants import SymbolId
-from .importers.utils import (
+from amici.constants import SymbolId
+from amici.importers.utils import (
     RESERVED_SYMBOLS,
     ObservableTransformation,
     amici_time_symbol,

python/sdist/amici/sympy_utils.py …hon/sdist/amici/_symbolic/sympy_utils.pypython/sdist/amici/sympy_utils.py renamed to python/sdist/amici/_symbolic/sympy_utils.py python/sdist/amici/sympy_utils.py renamed to python/sdist/amici/_symbolic/sympy_utils.py

@@ -10,10 +10,19 @@
 
 import sympy as sp
 
-from .logging import get_logger, log_execution_time
+from amici.logging import get_logger, log_execution_time
 
 logger = get_logger(__name__, logging.ERROR)
 
+__all__ = [
+    "smart_jacobian",
+    "smart_multiply",
+    "smart_is_zero_matrix",
+    "_monkeypatch_sympy",
+    "_parallel_applyfunc",
+    "_piecewise_to_minmax",
+]
+
 
 def _custom_pow_eval_derivative(self, s):
     """

python/sdist/amici/exporters/sundials/de_export.py

@@ -24,20 +24,15 @@
 
 import sympy as sp
 
+from amici._symbolic import *
+
 from ... import (
     __commit__,
     __version__,
     get_model_dir,
 )
-from ...de_model import DEModel
-from ...de_model_components import *
 from ...importers.sbml import splines
 from ...logging import get_logger, log_execution_time, set_log_level
-from ...sympy_utils import (
-    _custom_pow_eval_derivative,
-    _monkeypatched,
-    smart_is_zero_matrix,
-)
 from ..template import apply_template
 from .compile import build_model_extension
 from .cxx_functions import (
@@ -236,16 +231,14 @@ def __init__(
         self.generate_sensitivity_code: bool = generate_sensitivity_code
         self.hybridisation = hybridization
 
+    @_monkeypatch_sympy
     @log_execution_time("generating cpp code", logger)
     def generate_model_code(self) -> None:
         """
         Generates the model code (Python package + C++ extension).
         """
-        with _monkeypatched(
-            sp.Pow, "_eval_derivative", _custom_pow_eval_derivative
-        ):
-            self._prepare_model_folder()
-            self._generate_c_code()
+        self._prepare_model_folder()
+        self._generate_c_code()
 
     @log_execution_time("compiling cpp code", logger)
     def compile_model(self) -> None:

python/sdist/amici/importers/petab/_petab_importer.py

@@ -22,7 +22,7 @@
 
 import amici
 from amici import SensitivityOrder, get_model_dir
-from amici.de_model import DEModel
+from amici._symbolic import DEModel, Event
 from amici.importers.utils import MeasurementChannel, amici_time_symbol
 from amici.logging import get_logger
 
@@ -32,8 +32,6 @@
 if TYPE_CHECKING:
     import pysb
 
-    import amici.de_model_components
-
 __all__ = [
     "PetabImporter",
     "ExperimentManager",
@@ -1926,7 +1924,7 @@ def __init__(self, petab_problem: v2.Problem):
                     )
         #: The PEtab problem to convert. Not modified by this class.
         self._petab_problem = petab_problem
-        self._events: list[amici.de_model_components.Event] = []
+        self._events: list[Event] = []
         self._new_problem: v2.Problem | None = None
 
     @staticmethod
@@ -1936,7 +1934,7 @@ def _get_experiment_indicator_condition_id(experiment_id: str) -> str:
 
     def convert(
         self,
-    ) -> tuple[v2.Problem, list[amici.de_model_components.Event]]:
+    ) -> tuple[v2.Problem, list[Event]]:
         """Convert PEtab experiments to amici events and pysb initials.
 
         Generate events, add Initials, or convert Parameters to Expressions
@@ -1952,7 +1950,7 @@ def convert(
             to be passed to `pysb2amici`.
         """
         self._new_problem = copy.deepcopy(self._petab_problem)
-        self._events: list[amici.de_model_components.Event] = []
+        self._events: list[Event] = []
 
         self._add_preequilibration_indicator()
 
@@ -2177,7 +2175,7 @@ def _create_period_start_event(
             else:
                 raise AssertionError(change)
 
-        event = amici.de_model_components.Event(
+        event = Event(
             identifier=sp.Symbol(event_id),
             name=event_id,
             value=root_fun,

python/sdist/amici/importers/pysb/__init__.py

@@ -23,8 +23,8 @@
 import sympy as sp
 
 import amici
-from amici.de_model import DEModel
-from amici.de_model_components import (
+from amici._symbolic.de_model import DEModel
+from amici._symbolic.de_model_components import (
     DifferentialState,
     Event,
     Expression,
@@ -486,7 +486,7 @@ def get_cached_index(symbol, sarray, index_cache):
     dflux_dw = sp.ImmutableSparseMatrix(n_r, n_w, dflux_dw_dict)
     dflux_dp = sp.ImmutableSparseMatrix(n_r, n_p, dflux_dp_dict)
 
-    # use dok format to convert numeric csc to sparse symbolic
+    # use dok format to convert numeric csc to sparse _symbolic
     S = sp.ImmutableSparseMatrix(
         n_x,
         n_r,  # don't use shape here as we are eliminating rows
@@ -649,7 +649,7 @@ def _add_expression(
         name of the expression
 
     :param expr:
-        symbolic expression that the symbol refers to
+        _symbolic expression that the symbol refers to
 
     :param pysb_model:
         see :py:func:`_process_pysb_expressions`
@@ -681,10 +681,10 @@ def _add_expression(
 
         y = sp.Symbol(name)
         trafo = noise_distribution_to_observable_transformation(noise_dist)
-        # note that this is a bit iffy since we are potentially using the same symbolic identifier in expressions (w)
+        # note that this is a bit iffy since we are potentially using the same _symbolic identifier in expressions (w)
         # and observables (y). This is not a problem as there currently are no model functions that use both. If this
         # changes, I would expect symbol redefinition warnings in CPP models and overwriting in JAX models, but as both
-        # symbols refer to the same symbolic entity, this should not be a problem (untested)
+        # symbols refer to the same _symbolic entity, this should not be a problem (untested)
         obs = Observable(
             y, name, _parse_special_functions(expr), transformation=trafo
         )
@@ -723,7 +723,7 @@ def _get_sigma(
     pysb_model: pysb.Model, obs_name: str, sigma_name: str | None
 ) -> sp.Symbol:
     """
-    Tries to extract standard deviation symbolic identifier and formula
+    Tries to extract standard deviation _symbolic identifier and formula
     for a given observable name from the pysb model and if no specification is
     available sets default values
 
@@ -738,7 +738,7 @@ def _get_sigma(
         sigma or ``None``.
 
     :return:
-        symbolic variable representing the standard deviation of the observable
+        _symbolic variable representing the standard deviation of the observable
     """
     if sigma_name is None:
         return sp.Symbol(f"sigma_{obs_name}")
@@ -933,7 +933,7 @@ def _compute_possible_indices(
                 )
                 # TODO: implement this, multiply species by the volume of
                 # their respective compartment and allow total_cl to depend
-                # on parameters + constants and update the respective symbolic
+                # on parameters + constants and update the respective _symbolic
                 # derivative accordingly
 
             prototype = dict()
@@ -1161,7 +1161,7 @@ def _is_in_cycle(
 def _greedy_target_index_update(cl_prototypes: CL_Prototype) -> None:
     """
     Computes unique target indices for conservation laws from possible
-    indices  such that expected fill in in symbolic derivatives is minimized
+    indices  such that expected fill in in _symbolic derivatives is minimized
 
     :param cl_prototypes:
         dict that contains possible indices and non-unique target indices