PyAntiGen 2.1.4__tar.gz → 2.1.6__tar.gz

{pyantigen-2.1.4 → pyantigen-2.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyAntiGen
-Version: 2.1.4
+Version: 2.1.6
 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.4 → pyantigen-2.1.6}/PyAntiGen.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyAntiGen
-Version: 2.1.4
+Version: 2.1.6
 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.4 → pyantigen-2.1.6}/PyAntiGen.egg-info/scm_file_list.json

@@ -143,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.6/PyAntiGen.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.1.6",
+  "distance": 0,
+  "node": "g9171689079d2fc724733c9b7be5620f998df09cf",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-19"
+}

{pyantigen-2.1.4 → pyantigen-2.1.6}/pyantigen/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.1.4'
-__version_tuple__ = version_tuple = (2, 1, 4)
+__version__ = version = '2.1.6'
+__version_tuple__ = version_tuple = (2, 1, 6)
 
-__commit_id__ = commit_id = 'g2e65abb87'
+__commit_id__ = commit_id = 'g917168907'

{pyantigen-2.1.4 → pyantigen-2.1.6}/pyantigen/engine/Optimize.py

@@ -8279,6 +8279,11 @@ def predict_concentrations(params, observable_data, model, param_names, observab
         model.setIntegrator('cvode')
         model.integrator.absolute_tolerance = 1e-8
         _model_cache.put(model, "_scalar_abs_tol", 1e-8)
+        # This helper takes no solver settings, so it cannot ask for pinning.
+        # Drop any policy an earlier configure_integrator left on the model, or
+        # its reference scale -- taken for a different parameter vector -- would
+        # keep pinning here.
+        _model_cache.put(model, "_tolerance_policy", None)
         model.integrator.relative_tolerance = 1e-8
         model.integrator.setValue('stiff', True)
         model.integrator.variable_step_size = True

{pyantigen-2.1.4 → pyantigen-2.1.6}/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.4 → pyantigen-2.1.6}/pyantigen/engine/Simulate.py

@@ -233,6 +233,181 @@ 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*.
+
+    ``tolerance_pinning`` must be a real bool: ``bool("false")`` is True, so a
+    string from a config file would switch pinning on while reading as off.
+    """
+    pin = solver_settings.get("tolerance_pinning", TOLERANCE_PINNING)
+    if not isinstance(pin, (bool, np.bool_)):
+        raise TypeError(f"tolerance_pinning must be True or False, got {pin!r}")
+    pin = bool(pin)
+    cap = solver_settings.get("tolerance_cap_ratio", TOLERANCE_CAP_RATIO)
+    if cap is not None:
+        if isinstance(cap, (bool, np.bool_, str)):
+            raise TypeError(f"tolerance_cap_ratio must be a number, got {cap!r}")
+        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
+    # The model clock is the test for "still at the initial state": reset() and
+    # resetAll() return it to exactly 0.0 whatever was simulated before (a model
+    # has no other start time), and save/restore_model_state carry 'time' with
+    # the amounts, so a restored state brings its clock back with it. A clock
+    # that is not 0 means the model has been integrated, whatever its start.
+    try:
+        at_start = float(r.getCurrentTime()) == 0.0
+    except Exception:
+        at_start = False
+    if at_start:
+        # At the initial time the reference is re-derived every time, and a
+        # failure to do so drops the old one: it belongs to an earlier parameter
+        # vector, and pinning to it would silently use the wrong scales. (Away
+        # from t=0 the stored reference is kept on purpose -- see above.)
+        reference = None
+        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:
+                reference = (list(ids[:n]), vec[:n] / float(scalar))
+        except Exception:
+            pass
+        _model_cache.put(r, "_atol_reference", reference)
+    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:
+        # A vector that cannot be read cannot be floored either (the floor reads
+        # it first), so there is nothing to fall back to.
+        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
+    failed = []
+    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:
+            failed.append(ids[i])
+    if failed and not _model_cache.get(r, "_tolerance_set_warned"):
+        # Once per model: a state left at its drifted tolerance is what pinning
+        # exists to prevent, so it must not be silent, but this runs before
+        # every block and would otherwise repeat for the whole fit.
+        import warnings
+        _model_cache.put(r, "_tolerance_set_warned", True)
+        warnings.warn(f"tolerance_pinning could not set the absolute tolerance of "
+                      f"{len(failed)} state(s) (first: {failed[0]!r}); they keep "
+                      f"RoadRunner's derived value", RuntimeWarning, stacklevel=2)
+    return n
+
+
 class StackedResult(np.ndarray):
     def __new__(cls, input_array, colnames):
         obj = np.asarray(input_array).view(cls)
@@ -584,6 +759,15 @@ def safe_simulate(r, solver_settings, observed_species, depth=0, label=None):
     # corrupted/advanced state that cannot be reverted without this snapshot.
     saved_state = save_model_state(r)
 
+    # A sub-call of a subdivision begins wherever the previous one left the
+    # vector: re-derived from the decayed state after a restore, or loosened by
+    # a ladder. The top-level call is pinned by its caller (_run_blocks,
+    # SegmentRunner); the halves are not, so pin them here, from the configured
+    # scalar. Each half then tries the configured accuracy and runs its own
+    # ladder if that fails.
+    if depth > 0:
+        apply_tolerance_vector(r)
+
     # Fast path: try once with whatever settings the model already has.
     try:
         res = _run(r, start, end, points, times, observed_species)
@@ -653,7 +837,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
@@ -670,6 +854,7 @@ def safe_simulate(r, solver_settings, observed_species, depth=0, label=None):
 
             # Restore original integrator settings on success
             r.integrator.absolute_tolerance = orig_abs_tol
+            apply_tolerance_vector(r, scalar=orig_abs_tol)
             r.integrator.relative_tolerance = orig_rel_tol
             r.integrator.maximum_num_steps = orig_max_steps
             try:
@@ -748,6 +933,7 @@ def safe_simulate(r, solver_settings, observed_species, depth=0, label=None):
         
         # Restore original integrator settings before returning
         r.integrator.absolute_tolerance = orig_abs_tol
+        apply_tolerance_vector(r, scalar=orig_abs_tol)
         r.integrator.relative_tolerance = orig_rel_tol
         r.integrator.maximum_num_steps = orig_max_steps
         try:
@@ -766,6 +952,7 @@ def safe_simulate(r, solver_settings, observed_species, depth=0, label=None):
 
     # If all else fails, restore original settings and raise exception
     r.integrator.absolute_tolerance = orig_abs_tol
+    apply_tolerance_vector(r, scalar=orig_abs_tol)
     r.integrator.relative_tolerance = orig_rel_tol
     r.integrator.maximum_num_steps = orig_max_steps
     try:
@@ -797,6 +984,9 @@ def configure_integrator(r, solver_settings):
     Mutates *solver_settings* with the defaults, as the original inline version
     did, so callers that read the values back afterwards still see them.
     """
+    # Before anything is touched: a bad pinning setting is a configuration
+    # error, and should not leave the integrator half set up.
+    tolerance_policy(solver_settings)
     solver_settings["integrator"] = solver_settings.get("integrator", "cvode")
     solver_settings["absolute_tolerance"] = solver_settings.get("absolute_tolerance", 1e-8)
     solver_settings["relative_tolerance"] = solver_settings.get("relative_tolerance", 1e-8)
@@ -822,6 +1012,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 +1082,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.4/PyAntiGen.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "2.1.4",
-  "distance": 0,
-  "node": "g2e65abb870fe7cb1136e01bcd8c30b6d0f712dd6",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-10-14"
-}