doc: private / public / fix references

* Exclude private members from the sphinx documentation
* Make some supposed-to-be-private members private
* Fix references
* Fix docstrings

To be continued...

Author: dweindl

doc/_templates/autosummary/module.rst

@@ -1,8 +1,6 @@
 {{ fullname | escape | underline}}
 
 .. automodule:: {{ fullname }}
-   :members:
-   :undoc-members:
 
    {% block attributes %}
    {% if attributes %}

doc/conf.py

@@ -207,8 +207,12 @@ def install_doxygen():
     "inherited-members": True,
     "undoc-members": True,
     "ignore-module-all": False,
+    "imported-members": True,
 }
 
+# autosummary
+autosummary_ignore_module_all = False
+
 # sphinx-autodoc-typehints
 typehints_fully_qualified = True
 typehints_document_rtype = True
@@ -469,36 +473,21 @@ def process_missing_ref(app, env, node, contnode):
 
 
 def skip_member(app, what, name, obj, skip, options):
+    """Decide whether to skip a member during autodoc processing.
+
+    > Emitted when autodoc has to decide whether a member should be included in
+    > the documentation.
+    > The member is excluded if a handler returns True.
+    > It is included if the handler returns False.
+    """
     ignored_names = {
         "AbstractModel",
         "CVodeSolver",
         "IDASolver",
         "Model_ODE",
         "Model_DAE",
         "ConditionContext",
-        "checkSigmaPositivity",
-        "createGroup",
         "equals",
-        "printErrMsgIdAndTxt",
-        "wrapErrHandlerFn",
-        "printWarnMsgIdAndTxt",
-        "AmiciApplication",
-        "writeReturnData",
-        "writeReturnDataDiagnosis",
-        "attributeExists",
-        "locationExists",
-        "createAndWriteDouble1DDataset",
-        "createAndWriteDouble2DDataset",
-        "createAndWriteDouble3DDataset",
-        "createAndWriteInt1DDataset",
-        "createAndWriteInt2DDataset",
-        "createAndWriteInt3DDataset",
-        "getDoubleDataset1D",
-        "getDoubleDataset2D",
-        "getDoubleDataset3D",
-        "getIntDataset1D",
-        "getIntScalarAttribute",
-        "getDoubleScalarAttribute",
         "stdVec2ndarray",
         "SwigPyIterator",
         "thisown",
@@ -507,6 +496,16 @@ def skip_member(app, what, name, obj, skip, options):
     if name in ignored_names:
         return True
 
+    # skip, unless in __all__
+    # (we want to include imported members, but only the exported ones.
+    #  autodoc does not provide this functionality out of the box)
+    module_name = app.env.temp_data.get("autodoc:module")
+    if module_name and what == "module":
+        module_obj = sys.modules.get(module_name)
+        if module_obj is not None and hasattr(module_obj, "__all__"):
+            if name not in getattr(module_obj, "__all__", []):
+                return True
+
     if name.startswith("_") and name != "__init__":
         return True
 

doc/examples/example_presimulation/ExampleExperimentalConditions.ipynb

@@ -211,7 +211,7 @@
    "source": [
     "# Retrieve model output names and formulae from AssignmentRules and remove the respective rules\n",
     "observables = amici.assignment_rules_to_observables(\n",
-    "    sbml_importer.sbml,  # the libsbml model object\n",
+    "    sbml_importer.sbml_model,  # the libsbml model object\n",
     "    filter_function=lambda variable: variable.getName() == \"pPROT\",\n",
     ")\n",
     "print(\"Observables:\")\n",

python/sdist/amici/__init__.py

@@ -1,6 +1,5 @@
 """
-The AMICI Python module provides functionality for importing SBML or PySB
-models and turning them into C++ Python extensions.
+Top-level module.
 """
 
 import contextlib
@@ -226,7 +225,7 @@ def import_model_module(
     module_name: str, module_path: Path | str
 ) -> ModelModule:
     """
-    Import Python module of an AMICI model
+    Import Python module of an AMICI model.
 
     :param module_name:
         Name of the python package of the model

python/sdist/amici/adapters/fiddy.py

@@ -38,27 +38,28 @@
 __all__ = [
     "run_simulation_to_cached_functions",
     "simulate_petab_to_cached_functions",
+    "simulate_petab_v2_to_cached_functions",
 ]
 
 LOG_E_10 = np.log(10)
 
 
-def transform_gradient_lin_to_lin(gradient_value, _):
+def _transform_gradient_lin_to_lin(gradient_value, _):
     return gradient_value
 
 
-def transform_gradient_lin_to_log(gradient_value, parameter_value):
+def _transform_gradient_lin_to_log(gradient_value, parameter_value):
     return gradient_value * parameter_value
 
 
-def transform_gradient_lin_to_log10(gradient_value, parameter_value):
+def _transform_gradient_lin_to_log10(gradient_value, parameter_value):
     return gradient_value * (parameter_value * LOG_E_10)
 
 
 transforms = {
-    LIN: transform_gradient_lin_to_lin,
-    LOG: transform_gradient_lin_to_log,
-    LOG10: transform_gradient_lin_to_log10,
+    LIN: _transform_gradient_lin_to_lin,
+    LOG: _transform_gradient_lin_to_log,
+    LOG10: _transform_gradient_lin_to_log10,
 }
 
 
@@ -93,20 +94,13 @@ def transform_gradient_lin_to_log10(gradient_value, parameter_value):
 }
 
 
-def rdata_array_transpose(array: np.ndarray, variable: str) -> tuple[int]:
+def _rdata_array_transpose(array: np.ndarray, variable: str) -> tuple[int]:
     if array.size == 0:
         return array
     original_parameter_dimension = derivative_parameter_dimension[variable]
     return np.moveaxis(array, original_parameter_dimension, -1)
 
 
-def fiddy_array_transpose(array: np.ndarray, variable: str) -> tuple[int]:
-    if array.size == 0:
-        return array
-    original_parameter_dimension = derivative_parameter_dimension[variable]
-    return np.moveaxis(array, -1, original_parameter_dimension)
-
-
 default_derivatives = {
     k: v
     for k, v in all_rdata_derivatives.items()
@@ -181,7 +175,7 @@ def function(point: Type.POINT):
     def derivative(point: Type.POINT, return_dict: bool = False):
         rdata = run_amici_simulation(point=point, order=SensitivityOrder.first)
         outputs = {
-            variable: rdata_array_transpose(
+            variable: _rdata_array_transpose(
                 array=fiddy_array(getattr(rdata, derivative_variable)),
                 variable=derivative_variable,
             )
@@ -244,48 +238,6 @@ def derivative(point: Type.POINT, return_dict: bool = False):
 TYPE_STRUCTURE = tuple[int, int, tuple[int, ...]]
 
 
-def flatten(arrays: dict[str, Type.ARRAY]) -> Type.ARRAY:
-    flattened_value = np.concatenate([array.flat for array in arrays.values()])
-    return flattened_value
-
-
-def reshape(
-    array: Type.ARRAY,
-    structure: TYPE_STRUCTURE,
-    sensitivities: bool = False,
-) -> dict[str, Type.ARRAY]:
-    reshaped = {}
-    for variable, (start, stop, shape) in structure.items():
-        # array is currently "flattened" w.r.t. fiddy dimensions
-        # hence, if sensis, reshape w.r.t. fiddy dimensions
-        if sensitivities and (
-            dimension0 := derivative_parameter_dimension.get(
-                "s" + variable, False
-            )
-        ):
-            shape = [
-                size
-                for dimension, size in enumerate(shape)
-                if dimension != dimension0
-            ] + [shape[dimension0]]
-
-        array = array[start:stop]
-        if array.size != 0:
-            array = array.reshape(shape)
-
-        # now reshape to AMICI dimensions
-        if sensitivities and (
-            derivative_parameter_dimension.get(f"s{variable}", False)
-        ):
-            array = fiddy_array_transpose(
-                array=array,
-                variable=f"s{variable}",
-            )
-        reshaped[variable] = array
-
-    return reshaped
-
-
 def simulate_petab_to_cached_functions(
     petab_problem: petab.Problem,
     amici_model: Model,

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

@@ -218,7 +218,7 @@ def __init__(
         # include/amici/model.h for details)
         self.model: DEModel = de_model
         self._code_printer.known_functions.update(
-            splines.spline_user_functions(
+            splines._spline_user_functions(
                 self.model._splines, self._get_index("p")
             )
         )

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

@@ -51,9 +51,10 @@ def antimony2sbml(ant_model: str | Path) -> str:
 def antimony2amici(ant_model: str | Path, *args, **kwargs):
     """Convert Antimony model to AMICI model.
 
-    Converts the Antimony model provided as string of file to SBML and then imports it into AMICI.
+    Converts the Antimony model provided as string or file to SBML and then
+    imports it into AMICI.
 
-    For documentation see :meth:`amici.sbml_import.SbmlImporter.sbml2amici`.
+    For documentation see :meth:`amici.importers.sbml.SbmlImporter.sbml2amici`.
     """
     from amici.importers.sbml import SbmlImporter
 

python/sdist/amici/importers/petab/v1/sbml_import.py

@@ -332,7 +332,7 @@ def import_model_sbml(
         sbml_model,
         discard_annotations=discard_sbml_annotations,
     )
-    sbml_model = sbml_importer.sbml
+    sbml_model = sbml_importer.sbml_model
 
     allow_n_noise_pars = (
         not petab.lint.observable_table_has_nontrivial_noise_formula(

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

@@ -180,15 +180,16 @@ def pysb2amici(
     .. warning::
         **PySB models with Compartments**
 
-        When importing a PySB model with ``pysb.Compartment``\ s, BioNetGen
-        scales reaction fluxes with the compartment size. Instead of using the
+        When importing a PySB model with ``pysb.core.Compartment``\ s,
+        BioNetGen scales reaction fluxes with the compartment size.
+        Instead of using the
         respective symbols, the compartment size Parameter or Expression is
         evaluated when generating equations. This may lead to unexpected
         results if the compartment size parameter is changed for AMICI
         simulations.
 
     :param model:
-        pysb model, :attr:`pysb.Model.name` will determine the name of the
+        pysb model, :attr:`pysb.core.Model.name` will determine the name of the
         generated module
 
     :param output_dir:
@@ -197,7 +198,7 @@ def pysb2amici(
     :param observation_model:
         The different measurement channels that make up the observation
         model, see also :class:`amici.importers.utils.MeasurementChannel`.
-        The ID is expected to be the name of a :class:`pysb.Expression` or
+        The ID is expected to be the name of a :class:`pysb.core.Expression` or
         :class:`pysb.Observable` in the provided model that should be mapped to
         an observable.
         ``sigma`` is expected to be the name of a :class:`pysb.Expression` to