PyAntiGen 2.1.3__tar.gz → 2.1.5__tar.gz

{pyantigen-2.1.3 → pyantigen-2.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyAntiGen
-Version: 2.1.3
+Version: 2.1.5
 Summary: Declarative generation, simulation and identifiability analysis of compartmental Antimony/SBML models
 Author-email: Don Elbert <elbert5770@gmail.com>
 License-Expression: MIT

{pyantigen-2.1.3 → pyantigen-2.1.5}/PyAntiGen.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyAntiGen
-Version: 2.1.3
+Version: 2.1.5
 Summary: Declarative generation, simulation and identifiability analysis of compartmental Antimony/SBML models
 Author-email: Don Elbert <elbert5770@gmail.com>
 License-Expression: MIT

{pyantigen-2.1.3 → pyantigen-2.1.5}/PyAntiGen.egg-info/scm_file_list.json

@@ -103,6 +103,7 @@
     "tests/README.md",
     "tests/__init__.py",
     "tests/conftest.py",
+    "tests/engine/test_amici_flux_outputs.py",
     "tests/engine/test_amici_jumps.py",
     "tests/engine/test_amici_sensitivity.py",
     "tests/engine/test_analytic_gradient.py",
@@ -142,6 +143,7 @@
     "tests/engine/test_solver_fingerprint.py",
     "tests/engine/test_stop_rules.py",
     "tests/engine/test_tolerance_floor.py",
+    "tests/engine/test_tolerance_pinning.py",
     "tests/engine/test_wald_units.py",
     "tests/generate/test_gen_antimony_utils.py",
     "tests/generate/test_gen_data_interpolation.py",

pyantigen-2.1.5/PyAntiGen.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.1.5",
+  "distance": 0,
+  "node": "g244c235d347fa7cf25440401efc2e02f1a6955e2",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-15"
+}

{pyantigen-2.1.3 → pyantigen-2.1.5}/docs/ANALYTIC_GRADIENT.md

@@ -123,6 +123,9 @@ dynamics read them.
 * Columns that are not species, parameters or compartments (reaction rates) are not available to the
   loss; the gradient is then zero for anything that depends only on them.
 * The profile-likelihood stage keeps its own optimizers.
+  The gradient can differentiate what a profile point minimizes: `provider.freeze_sigmas(block_sigmas)` pins the floored blocks'
+  sigmas as `evaluate_nll_fixed(frozen_sigmas=...)` does (without it the gradient is off by 10 to 30% away from the fit);
+  `freeze_sigmas(None)` releases them. Nothing calls it yet.
 * Cost: the gradient costs one AMICI forward-sensitivity run, which grows with the number of
   parameters it differentiates. On SILK, 8 parameters: about 1.2 s a gradient against 9 objective
   evaluations (about 1.4 s) for forward differences; with all 48 parameters AMICI needs about 40 s a

{pyantigen-2.1.3 → pyantigen-2.1.5}/pyantigen/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.1.3'
-__version_tuple__ = version_tuple = (2, 1, 3)
+__version__ = version = '2.1.5'
+__version_tuple__ = version_tuple = (2, 1, 5)
 
-__commit_id__ = commit_id = 'g45ef1dd29'
+__commit_id__ = commit_id = 'g244c235d3'

{pyantigen-2.1.3 → pyantigen-2.1.5}/pyantigen/engine/Analytic_gradient.py

@@ -91,6 +91,8 @@ class LossGradient:
         self.param_names = list(param_names)
         self.rel_step = float(rel_step)
         self.explicit = self._explicit_parameters()
+        # {(block, observable): sigma}: the floored blocks' sigmas a profile point holds still (see freeze_sigmas)
+        self.frozen_sigmas = None
 
     # -- which parameters the loss reads by name ------------------------------------
     def _explicit_parameters(self):
@@ -123,7 +125,8 @@ class LossGradient:
         from pyantigen.engine.Optimize import collect_loss_blocks, concentrated_nll
         p_dict = dict(zip(self.param_names, np.asarray(p_lin, dtype=float).tolist()))
         blocks = collect_loss_blocks(items, self.groups, self.replicates, self.param_names,
-                                     np.asarray(p_lin, dtype=float), p_dict)
+                                     np.asarray(p_lin, dtype=float), p_dict,
+                                     frozen_sigmas=self.frozen_sigmas)
         if not blocks:
             raise AnalyticGradientError("the loss has no data to score")
         v = concentrated_nll(blocks)
@@ -581,6 +584,16 @@ class AmiciGradient:
             points += [p for p in (lo, hi) if np.all(np.isfinite(p)) and not np.array_equal(p, x0)]
         return points
 
+    def freeze_sigmas(self, sigmas):
+        """Differentiate the loss a profile point minimizes: floored blocks keep the sigma they had at the fit.
+
+        *sigmas* is what ``Optimize.block_sigmas`` returns for the fit (``{(block, observable): sigma_used}``),
+        the same dictionary the profile passes to ``evaluate_nll_fixed(frozen_sigmas=...)``. A frozen block is
+        scored with that sigma instead of ``min(sigma_hat, floor)`` at the current point, which changes its
+        derivative (the sigma no longer moves with the parameters). ``None`` releases them.
+        """
+        self.loss.frozen_sigmas = dict(sigmas) if sigmas else None
+
     def linear_gradient(self, p_lin):
         """``(nll, d nll / d p_lin)`` evaluated on AMICI's own simulation."""
         items, dirs = {}, {}

{pyantigen-2.1.3 → pyantigen-2.1.5}/pyantigen/engine/Segmented.py

@@ -44,7 +44,7 @@ caches separately must not contain a switch: ``switches_before`` says whether it
 """
 import numpy as np
 
-from pyantigen.engine.Simulate import StackedResult, floor_tolerance_vector, safe_simulate
+from pyantigen.engine.Simulate import StackedResult, apply_tolerance_vector, safe_simulate
 from pyantigen.generate.input_schedule import ScheduleError
 
 
@@ -154,7 +154,7 @@ class SegmentRunner:
             between = mine[(mine > u + eu) & (mine < v - ev)]
             times = [u] + between.tolist() + [v]
 
-            floor_tolerance_vector(self.r)
+            apply_tolerance_vector(self.r)
             res, _meta = safe_simulate(
                 self.r, {"times": times, "variable_step_size": False},
                 observed_species, label=label)

{pyantigen-2.1.3 → pyantigen-2.1.5}/pyantigen/engine/Simulate.py

@@ -233,6 +233,150 @@ def floor_tolerance_vector(r, floor=_MIN_ABSOLUTE_TOLERANCE):
     return n
 
 
+# ---------------------------------------------------------------------------
+# Pinning the vector, not only flooring it
+# ---------------------------------------------------------------------------
+# floor_tolerance_vector raises what has fallen below the floor and leaves
+# everything else as RoadRunner has it. That is enough for a vector that has
+# drifted DOWN, which is what the floor was written for. It does nothing about
+# two other things:
+#
+#   * The retry ladder sets the scalar before every attempt, and setting the
+#     scalar re-derives the whole vector from the amounts the model holds
+#     *at that moment* -- the failing state, not the initial one. Measured on
+#     Aducanumab 60 mg/kg: between the segment-start vector and the vector of
+#     attempt 2, 176 entries were more than 10x larger and 62 more than 10x
+#     smaller (ratios 1.7e-11 .. 2.9e+07). The floor raised 3 of them. So the
+#     loosened retries do not run at "the same tolerances, looser"; they run at
+#     tolerances derived from wherever the integration died.
+#
+#   * RoadRunner's initial-derived scale is atol_i = scalar * amount_i, or
+#     scalar * volume_i for a species that starts at 0 (see the note above
+#     _MIN_ABSOLUTE_TOLERANCE). Every species that starts empty therefore gets
+#     one number, scalar * its compartment volume -- 6.7e-11 at scalar 1e-9 for
+#     the 0.067-volume endosome -- however small it later runs. After the FcRn
+#     saturation front of a 60 mg/kg dose the endosomal antibody species sit at
+#     1.6e-9 .. 1.3e-8, so that budget is 0.5-4% of their value, and CVODE fails
+#     (CV_ILL_INPUT / CV_TOO_MUCH_ACC) ~200 h after the dose. Lowering the scalar
+#     10x, pinning those five species at 1e-15, or capping every entry at 1e-12
+#     each took the displaced-parameter failures from 6/40 to 0/40.
+#
+# Pinning keeps ONE reference -- the per-state scale RoadRunner derives at
+# configure_integrator when the model is at its initial time -- and from it
+# sets every entry explicitly before each block, each segment and each ladder
+# attempt:
+#
+#     atol_i = clip( scalar * scale_i , floor , cap_ratio * scalar )
+#
+# *scalar* is the configured one, or the ladder's current (loosened) one, so a
+# retry scales the same vector instead of re-deriving it. The cap is relative
+# to the scalar for the same reason: an absolute cap would undo the ladder's
+# loosening. cap_ratio is optional; without it pinning only restores the
+# initial-derived vector.
+#
+# Opt in per replicate through the solver settings:
+#
+#     "tolerance_pinning": True,        # default TOLERANCE_PINNING (False)
+#     "tolerance_cap_ratio": 1e-3,      # default TOLERANCE_CAP_RATIO (None)
+#
+# Both are plain values in the settings dict, so Profile_checkpoint's solver
+# fingerprint already covers them: switching them on starts a new checkpoint
+# directory rather than mixing two objectives. Left off, apply_tolerance_vector
+# is floor_tolerance_vector and nothing changes.
+TOLERANCE_PINNING = False
+TOLERANCE_CAP_RATIO = None
+
+
+def tolerance_policy(solver_settings):
+    """``{"pin": bool, "cap_ratio": float | None}`` from *solver_settings*."""
+    pin = bool(solver_settings.get("tolerance_pinning", TOLERANCE_PINNING))
+    cap = solver_settings.get("tolerance_cap_ratio", TOLERANCE_CAP_RATIO)
+    if cap is not None:
+        cap = float(cap)
+        if not cap > 0:
+            raise ValueError(f"tolerance_cap_ratio must be positive, got {cap}")
+        if not pin:
+            raise ValueError("tolerance_cap_ratio needs tolerance_pinning: a cap is "
+                             "applied to the pinned vector")
+    return {"pin": pin, "cap_ratio": cap}
+
+
+def _remember_tolerance_policy(r, solver_settings, scalar):
+    """Cache the policy on *r* and, at the model's initial time, the reference scale.
+
+    Called by configure_integrator right after the scalar is set, when RoadRunner
+    has just derived the vector. The scale is only taken at time 0: a second
+    configure on a state restored from the pre-dose cache would derive it from
+    amounts that have already decayed, which is the drift this exists to undo.
+    """
+    policy = tolerance_policy(solver_settings)
+    if not policy["pin"]:
+        _model_cache.put(r, "_tolerance_policy", None)
+        return
+    try:
+        at_start = float(r.getCurrentTime()) == 0.0
+    except Exception:
+        at_start = False
+    if at_start:
+        try:
+            vec = np.asarray(r.integrator.getAbsoluteToleranceVector(), float)
+            ids = state_vector_ids(r)
+            n = min(len(ids), len(vec))
+            if float(scalar) > 0 and n:
+                _model_cache.put(r, "_atol_reference",
+                                 (list(ids[:n]), vec[:n] / float(scalar)))
+        except Exception:
+            pass
+    if _model_cache.get(r, "_atol_reference") is None:
+        # Never saw the initial state, so there is no initial scale to pin to.
+        import warnings
+        warnings.warn("tolerance_pinning requested but the model was first configured "
+                      "away from its initial time; falling back to the floor",
+                      RuntimeWarning, stacklevel=3)
+        _model_cache.put(r, "_tolerance_policy", None)
+        return
+    _model_cache.put(r, "_tolerance_policy", policy)
+
+
+def apply_tolerance_vector(r, scalar=None, floor=_MIN_ABSOLUTE_TOLERANCE):
+    """Set the per-state absolute tolerances for the next integration.
+
+    Pinning off (the default): exactly :func:`floor_tolerance_vector`. Pinning
+    on: every entry is set to ``clip(scalar * scale_i, floor, cap_ratio * scalar)``
+    from the reference scale. *scalar* defaults to the configured absolute
+    tolerance; the retry ladder passes its current, loosened one. Returns the
+    number of entries set.
+    """
+    policy = _model_cache.get(r, "_tolerance_policy")
+    ref = _model_cache.get(r, "_atol_reference") if policy else None
+    if ref is None:
+        return floor_tolerance_vector(r, floor)
+    if scalar is None:
+        scalar = _model_cache.get(r, "_scalar_abs_tol")
+    if scalar is None:
+        return floor_tolerance_vector(r, floor)
+    ids, scale = ref
+    try:
+        current = np.asarray(r.integrator.getAbsoluteToleranceVector(), float)
+    except Exception:
+        return 0
+    if len(current) < len(ids):
+        return floor_tolerance_vector(r, floor)
+    scalar = float(scalar)
+    want = scalar * scale
+    if policy["cap_ratio"] is not None:
+        want = np.minimum(want, policy["cap_ratio"] * scalar)
+    want = np.maximum(want, floor)
+    n = 0
+    for i in np.flatnonzero(~np.isclose(current[:len(ids)], want, rtol=1e-9, atol=0.0)):
+        try:
+            r.integrator.setIndividualTolerance(ids[i], float(want[i]))
+            n += 1
+        except Exception:
+            pass
+    return n
+
+
 class StackedResult(np.ndarray):
     def __new__(cls, input_array, colnames):
         obj = np.asarray(input_array).view(cls)
@@ -653,7 +797,7 @@ def safe_simulate(r, solver_settings, observed_species, depth=0, label=None):
         # state and discards any individual settings, so the floor has to be
         # re-applied here or every retry would run without it -- including the
         # retries provoked by its absence.
-        floor_tolerance_vector(r)
+        apply_tolerance_vector(r, scalar=cur_abs_tol)
         if cur_initial_step is not None:
             try:
                 r.integrator.initial_time_step = cur_initial_step
@@ -822,6 +966,7 @@ def configure_integrator(r, solver_settings):
     r.integrator.variable_step_size = solver_settings["variable_step_size"]
     # r.integrator.setValue('initial_time_step', solver_settings["initial_time_step"])
     r.integrator.setValue('maximum_num_steps', solver_settings["maximum_num_steps"])
+    _remember_tolerance_policy(r, solver_settings, atol)
     return solver_settings
 
 
@@ -891,7 +1036,7 @@ def _run_blocks(r, block_list, last_tracked_idx, observed_species, label, runner
         # tolerance vector is derived from the current state, so it is healthy
         # here at t=0 and underflows as the trajectory decays. See
         # _MIN_ABSOLUTE_TOLERANCE.
-        floor_tolerance_vector(r)
+        apply_tolerance_vector(r)
 
         try:
             if runner is not None:

{pyantigen-2.1.3 → pyantigen-2.1.5}/pyantigen/generate/scaled_time.py

@@ -23,7 +23,8 @@ What this module does to the model
   from per-segment constants ``sched_a0/a1`` and ``sched_c0_<m>/c1_<m>`` (the
   anchors and coefficients of the segment's two end points). The solver sees
   ``D`` as a function of the parameters.
-* Every reaction rate and every rate rule is multiplied by ``sched_Delta``.
+* Every reaction rate and every rate rule is multiplied by ``sched_Delta``; a formula that reads a reaction id
+  (a rule that sums fluxes) reads ``id/sched_Delta``, the flux of the unscaled model.
 * A measured curve ``c`` (an assignment rule in the model) becomes
   ``sched_ci_c + sched_cs_c*sched_clock``: on one segment it is a straight line.
 * Each parameter the schedule assigns (``Q_Leak``, ...) becomes a state with rate
@@ -133,6 +134,32 @@ def _with_clock(node):
     return _parse(_TIME_TOKEN.sub(CLOCK, libsbml.formulaToL3String(node)))
 
 
+_TOKEN = re.compile(r"(?<![A-Za-z0-9_.])[A-Za-z_][A-Za-z0-9_]*")
+
+
+def _reads_any(node, names):
+    if node.isName() and node.getName() in names:
+        return True
+    return any(_reads_any(node.getChild(i), names) for i in range(node.getNumChildren()))
+
+
+def _with_true_fluxes(node, reaction_ids):
+    """*node*'s mathematics with each reaction id read as the flux of the original time, as a new tree; None if it reads none.
+
+    A reaction id in a formula means the reaction's rate. Step 3 of :func:`scale_model` multiplies every rate law by
+    ``sched_Delta``, so a rule that sums fluxes (``BBB_transport := BBBTransport_AB42 + ...``) would read
+    ``Delta`` times the flux, and an output or a rate rule built on it would be wrong by the length of the segment.
+    Reading ``(R/sched_Delta)`` instead gives the rule the flux it has in the unscaled model, and the solver
+    differentiates the quotient, ``dDelta/dp`` included. Done on the formula text, for the reason given in
+    :func:`_with_clock`.
+    """
+    if not _reads_any(node, reaction_ids):
+        return None
+    text = _TOKEN.sub(lambda m: f"({m.group(0)}/{DELTA})" if m.group(0) in reaction_ids else m.group(0),
+                      libsbml.formulaToL3String(node))
+    return _parse(text)
+
+
 def _expand_initial(model, text, depth=0):
     """*text* with every parameter that has an initial assignment replaced by that assignment.
 
@@ -221,6 +248,25 @@ def scale_model(sbml, schedule):
         _add_parameter(model, f"{PREFIX}cs_{c}")
         rule.setMath(_parse(f"{PREFIX}ci_{c} + {PREFIX}cs_{c}*{CLOCK}"))
 
+    # 3a. a formula that reads a reaction id reads that reaction's rate: keep it the unscaled one
+    reaction_ids = {model.getReaction(i).getId() for i in range(model.getNumReactions())}
+    if reaction_ids:
+        for i in range(model.getNumRules()):
+            rule = model.getRule(i)
+            new = _with_true_fluxes(rule.getMath(), reaction_ids)
+            if new is not None:
+                rule.setMath(new)
+        for i in range(model.getNumReactions()):
+            kl = model.getReaction(i).getKineticLaw()
+            new = _with_true_fluxes(kl.getMath(), reaction_ids) if kl is not None and kl.isSetMath() else None
+            if new is not None:
+                kl.setMath(new)
+        for i in range(model.getNumInitialAssignments()):
+            assignment = model.getInitialAssignment(i)
+            new = _with_true_fluxes(assignment.getMath(), reaction_ids)
+            if new is not None:
+                assignment.setMath(new)
+
     # 3. rates times Delta (before the new rules, which must not be scaled)
     delta = lambda: _name_node(DELTA)  # noqa: E731
     for i in range(model.getNumReactions()):

pyantigen-2.1.3/PyAntiGen.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "2.1.3",
-  "distance": 0,
-  "node": "g45ef1dd293ac66f01a48a35895aa0b83ec9a6b96",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-10-13"
-}