PyAntiGen 2.0.3__tar.gz → 2.1.1__tar.gz

{pyantigen-2.0.3 → pyantigen-2.1.1}/PKG-INFO

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

{pyantigen-2.0.3 → pyantigen-2.1.1}/PyAntiGen.egg-info/PKG-INFO

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

{pyantigen-2.0.3 → pyantigen-2.1.1}/PyAntiGen.egg-info/SOURCES.txt

@@ -32,8 +32,10 @@ pyantigen/engine/Event_times.py
 pyantigen/engine/Fast_profile.py
 pyantigen/engine/Fit_cache.py
 pyantigen/engine/Identifiability.py
+pyantigen/engine/Model_cache.py
 pyantigen/engine/Model_optimize.py
 pyantigen/engine/Model_simulate.py
+pyantigen/engine/Multistart.py
 pyantigen/engine/Nelder_mead.py
 pyantigen/engine/Noise_floor.py
 pyantigen/engine/Optimize.py
@@ -45,6 +47,7 @@ pyantigen/engine/README.md
 pyantigen/engine/Results.py
 pyantigen/engine/Sensitivity_analysis.py
 pyantigen/engine/Simulate.py
+pyantigen/engine/Stop_rules.py
 pyantigen/engine/__init__.py
 pyantigen/generate/AntimonyGen.py
 pyantigen/generate/RxnDict_to_antimony.py

{pyantigen-2.0.3 → pyantigen-2.1.1}/PyAntiGen.egg-info/scm_file_list.json

@@ -24,8 +24,10 @@
     "pyantigen/engine/Fast_profile.py",
     "pyantigen/engine/Fit_cache.py",
     "pyantigen/engine/Identifiability.py",
+    "pyantigen/engine/Model_cache.py",
     "pyantigen/engine/Model_optimize.py",
     "pyantigen/engine/Model_simulate.py",
+    "pyantigen/engine/Multistart.py",
     "pyantigen/engine/Nelder_mead.py",
     "pyantigen/engine/Noise_floor.py",
     "pyantigen/engine/Optimize.py",
@@ -37,6 +39,7 @@
     "pyantigen/engine/Results.py",
     "pyantigen/engine/Sensitivity_analysis.py",
     "pyantigen/engine/Simulate.py",
+    "pyantigen/engine/Stop_rules.py",
     "pyantigen/engine/__init__.py",
     "pyantigen/generate/AntimonyGen.py",
     "pyantigen/generate/RxnDict_to_antimony.py",
@@ -104,19 +107,26 @@
     "tests/engine/test_fast_profile.py",
     "tests/engine/test_fit_cache.py",
     "tests/engine/test_hessian_steps.py",
+    "tests/engine/test_model_cache.py",
+    "tests/engine/test_multistart_candidates.py",
+    "tests/engine/test_multistart_gradient.py",
+    "tests/engine/test_multistart_resume.py",
     "tests/engine/test_multistart_sampler.py",
     "tests/engine/test_multistart_stage.py",
+    "tests/engine/test_multistart_triage.py",
     "tests/engine/test_nelder_mead.py",
     "tests/engine/test_point_identity.py",
     "tests/engine/test_profile_grid_open.py",
     "tests/engine/test_profile_quadratic.py",
     "tests/engine/test_profile_records.py",
     "tests/engine/test_profile_stream.py",
+    "tests/engine/test_results_csv_policy.py",
     "tests/engine/test_search_mode.py",
     "tests/engine/test_sigma_floor.py",
     "tests/engine/test_slice_screen.py",
     "tests/engine/test_slice_window.py",
     "tests/engine/test_solver_fingerprint.py",
+    "tests/engine/test_stop_rules.py",
     "tests/engine/test_tolerance_floor.py",
     "tests/engine/test_wald_units.py",
     "tests/generate/test_gen_antimony_utils.py",

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

@@ -0,0 +1,8 @@
+{
+  "tag": "2.1.1",
+  "distance": 0,
+  "node": "g6282b0d51a9efb9b414f250be15a996d5e131645",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-08"
+}

{pyantigen-2.0.3 → pyantigen-2.1.1}/pyantigen/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.0.3'
-__version_tuple__ = version_tuple = (2, 0, 3)
+__version__ = version = '2.1.1'
+__version_tuple__ = version_tuple = (2, 1, 1)
 
-__commit_id__ = commit_id = 'g0218ed4d7'
+__commit_id__ = commit_id = 'g6282b0d51'

{pyantigen-2.0.3 → pyantigen-2.1.1}/pyantigen/engine/Evaluator.py

@@ -239,14 +239,40 @@ def _worker_nll(x, frozen_sigmas=None):
     )
 
 
-def _eval_task(x, frozen_sigmas=None):
+def _eval_context(eval_mode):
+    """Context for one task: the solver limits an ``eval_mode`` asks for.
+
+    ``eval_mode`` is a plain dict so it pickles cheaply:
+
+        {"retry_limits": (max_attempts, max_depth), "relax": factor}
+
+    Applied around ONE task and undone after it, never at worker start-up: both
+    settings are process-global, and the same worker goes on to serve profile
+    points and diagnostics that must run exactly as configured. Absent or empty,
+    this does nothing.
+    """
+    from contextlib import ExitStack
+
+    stack = ExitStack()
+    if eval_mode:
+        from pyantigen.engine.Simulate import relaxed_tolerances, retry_limits
+        limits = eval_mode.get("retry_limits")
+        if limits:
+            stack.enter_context(retry_limits(limits[0], limits[1]))
+        if eval_mode.get("relax"):
+            stack.enter_context(relaxed_tolerances(eval_mode["relax"]))
+    return stack
+
+
+def _eval_task(x, frozen_sigmas=None, eval_mode=None):
     """Evaluate one parameter vector. Never raises across the pool boundary."""
     if _WORKER["spec"] is None:
         return (FAILURE_VALUE, "worker-not-initialized", 0.0)
 
     t0 = time.time()
     try:
-        val = _worker_nll(x, frozen_sigmas=frozen_sigmas)
+        with _eval_context(eval_mode):
+            val = _worker_nll(x, frozen_sigmas=frozen_sigmas)
         _WORKER["n_evals"] += 1
         status = "ok" if np.isfinite(val) and val < FAILURE_VALUE else "sentinel"
         return (float(val), status, time.time() - t0)
@@ -327,6 +353,11 @@ def _profile_task(job):
     out.pop("frozen_sigmas", None)
     # A location on this machine's disk, meaningless in a stored record.
     out.pop("state_path", None)
+    # An input as well: the settings for the shadow stop rules. What they
+    # observed comes back as `trace`, `shadow_stops` and `stop_reason` below;
+    # `trace` and `shadow_stops` are also inputs when a point is resumed, and
+    # are overwritten with the continued history.
+    stop_rules = out.pop("stop_rules", None)
     out.update({"nll": None, "status": "ok", "n_evals": 0, "wall_s": 0.0,
                 "worker": os.getpid(), "converged": True, "nit": -1,
                 "nfev": -1, "opt_message": "", "interrupted": False})
@@ -358,6 +389,12 @@ def _profile_task(job):
         # because a point stopped before its first simplex is complete has no
         # sorted vertex to read it from.
         best = {"f": float("inf"), "x": x_start}
+        # The shadow stop rules' watcher (pyantigen.engine.Stop_rules). It only
+        # observes -- nothing it computes feeds back into the optimizer -- and
+        # is None unless the job asked for it. `base` is the point's evaluation
+        # count when this job began, so a resumed point numbers on from where
+        # it stopped.
+        shadow = {"mon": None, "base": 0}
 
         # Every profile point pins each floored block at its own sigma_used
         # from the fit rather than letting it re-concentrate (see
@@ -378,6 +415,12 @@ def _profile_task(job):
             if np.isfinite(v) and v < best["f"]:
                 best["f"] = float(v)
                 best["x"] = x_arr.copy()
+            if shadow["mon"] is not None:
+                try:
+                    shadow["mon"].update(shadow["base"] + eval_count["n"],
+                                         best["f"])
+                except Exception:       # a watcher must never fail a point
+                    shadow["mon"] = None
             return v
 
         def time_is_up():
@@ -393,7 +436,8 @@ def _profile_task(job):
             # is just the objective at the fixed value -- exact by definition.
             nll = raw_objective(x_start, x_fixed)
             x_opt = x_start
-            out.update({"converged": True, "nit": 0, "nfev": 1})
+            out.update({"converged": True, "nit": 0, "nfev": 1,
+                        "stop_reason": "exact"})
             eval_count["n"] = 1
         else:
             options, extra_kwargs = nuisance_options(
@@ -403,6 +447,19 @@ def _profile_task(job):
             resumable = str(method).lower() == "nelder-mead" and can_run(
                 options, extra_kwargs)
 
+            def start_shadow(base):
+                if not stop_rules or stop_rules.get("anchor") is None:
+                    return
+                try:
+                    from pyantigen.engine.Stop_rules import PointMonitor
+                    shadow["mon"] = PointMonitor(
+                        stop_rules["anchor"], max_fev, x_start.size,
+                        cfg=stop_rules, trace=job.get("trace"),
+                        fired=job.get("shadow_stops"))
+                    shadow["base"] = int(base)
+                except Exception:       # a watcher must never fail a point
+                    shadow["mon"] = None
+
             res = None
             outcome = "done"
             if resumable:
@@ -431,6 +488,7 @@ def _profile_task(job):
                     # run, and nothing to save either.
                     outcome = "capped"
                 else:
+                    start_shadow(nm_state["nfev"])
                     interval = float(job.get("state_interval_s",
                                              POINT_STATE_INTERVAL_S))
                     last_save = [0.0]
@@ -464,6 +522,8 @@ def _profile_task(job):
                 if nfev_used >= max_fev or nit_used >= max_it:
                     outcome = "capped"
                 else:
+                    start_shadow(nfev_used)
+
                     def guarded(x_nuisance, fixed_val):
                         v = nuisance_objective(x_nuisance, fixed_val)
                         if time_is_up():
@@ -523,6 +583,20 @@ def _profile_task(job):
                 out["nm_simplex"] = np.asarray(nm_state["sim"],
                                                dtype=float).tolist()
 
+            # Why this job's optimization ended, for reading a finished run:
+            # `converged` alone cannot tell a point that met its tolerance from
+            # one that spent its cap and happened to be at the minimum, and at
+            # a 1500 cap most points are the second kind.
+            if outcome == "interrupted":
+                out["stop_reason"] = "interrupted"
+            elif res is None or not np.isfinite(getattr(res, "fun", np.inf)):
+                out["stop_reason"] = "budget-spent"
+            elif outcome == "capped" or not getattr(res, "success", True):
+                out["stop_reason"] = ("maxiter" if getattr(res, "status", None) == 2
+                                      else "maxfev")
+            else:
+                out["stop_reason"] = "tolerance"
+
         if nm_state is not None:
             nfev_total, nit_total = nm_state["nfev"], nm_state["nit"]
         else:
@@ -539,6 +613,11 @@ def _profile_task(job):
             "nit_total": nit_total,
             "status": "ok" if np.isfinite(nll) and nll < FAILURE_VALUE else "sentinel",
         })
+        if shadow["mon"] is not None:
+            try:
+                out.update(shadow["mon"].finish(nfev_total, best["f"]))
+            except Exception:
+                pass
     except Exception as exc:
         out.update({"status": f"error: {type(exc).__name__}: {exc}",
                     "nll": FAILURE_VALUE, "interrupted": False})
@@ -791,9 +870,12 @@ class ParallelEvaluator:
     # -- evaluation --------------------------------------------------------
 
     def evaluate_batch(self, xs, label=None, heartbeat_s=_HEARTBEAT_SECONDS,
-                       frozen_sigmas=None):
+                       frozen_sigmas=None, eval_mode=None):
         """Evaluate every parameter vector in *xs*; return losses in input order.
 
+        ``eval_mode`` ({"retry_limits": (attempts, depth), "relax": factor})
+        runs each evaluation under those solver limits; see :func:`_eval_context`.
+
         Uses submit/wait, not map -- see profile_batch's docstring for the
         general reasoning. map() (the previous implementation here) returns
         nothing until the WHOLE batch is done, so one slow straggler among
@@ -833,7 +915,7 @@ class ParallelEvaluator:
                   flush=True)
 
         try:
-            futures = {self._pool.submit(_eval_task, x, frozen_sigmas): i
+            futures = {self._pool.submit(_eval_task, x, frozen_sigmas, eval_mode): i
                       for i, x in enumerate(xs)}
         except RuntimeError as exc:
             if "bootstrapping phase" in str(exc):

{pyantigen-2.0.3 → pyantigen-2.1.1}/pyantigen/engine/Fit_cache.py

@@ -161,7 +161,7 @@ def fit_fingerprint(param_names, x0_lin, bounds_lin, scales, groups, model_text,
     # spec a default stage does not invalidate the fits already cached.
     if int(n_starts or 1) <= 1:
         for k in ("multistart_method", "multistart_optimizer_kwargs",
-                  "multistart_limits"):
+                  "multistart_limits", "multistart_triage", "multistart_gradient"):
             kwargs.pop(k, None)
 
     key = {
@@ -387,6 +387,58 @@ class FitCache:
         data["complete"] = block
         return self._write(data)
 
+    def save_stage(self, state):
+        """Checkpoint of the multi-start stage in progress.
+
+        Written after every candidate scored and every local fit finished, so a
+        kill costs the evaluation or fit in flight and nothing before it. Kept
+        under its own key: the stage is not the fit, and the fit's partial must
+        not appear until the stage is over (see ``_persist_stage_result``). Must
+        already be plain JSON data.
+        """
+        if not self.enabled:
+            return False
+        data = self._read() or {}
+        data["multistart_stage"] = state
+        return self._write(data)
+
+    def load_stage(self):
+        """The stage checkpoint :meth:`save_stage` kept, or None."""
+        data = self._read()
+        block = data.get("multistart_stage") if data else None
+        return block if isinstance(block, dict) else None
+
+    def clear_stage(self):
+        """Drop the stage checkpoint, once the stage's result is on record."""
+        if not self.enabled:
+            return False
+        data = self._read()
+        if not data or "multistart_stage" not in data:
+            return False
+        data.pop("multistart_stage")
+        return self._write(data)
+
+    def save_multistart(self, report):
+        """Keep the multi-start stage's report with the fit it produced.
+
+        Stored beside the ``complete``/``partial`` records, not inside them, so it
+        survives both: a relaunch that resumes the standard fit skips the stage,
+        and one that reuses a finished fit skips both, yet the result written at
+        the end should still say how the starting point was found. *report* must
+        already be plain JSON data (see ``Multistart.json_safe``).
+        """
+        if not self.enabled:
+            return False
+        data = self._read() or {}
+        data["multistart"] = report
+        return self._write(data)
+
+    def load_multistart(self):
+        """The report :meth:`save_multistart` kept, or None."""
+        data = self._read()
+        block = data.get("multistart") if data else None
+        return block if isinstance(block, dict) else None
+
     def save_partial(self, x_lin, fun, n_evals=None, force=False, nm_state=None,
                      interval=None, de_state=None, cal_x_lin=None):
         """Record the best point so far, at most once per *interval*.

pyantigen-2.1.1/pyantigen/engine/Model_cache.py

@@ -0,0 +1,75 @@
+"""Per-model caches, stored on the RoadRunner instance without touching ``__getattr__``.
+
+The engine keeps a few values on each RoadRunner so they are computed once per
+model rather than once per evaluation (the state keys, the available symbols,
+the parameter baseline, the configured tolerance). The obvious way to read one
+back -- ``try: r._x`` / ``except AttributeError``, or ``getattr(r, "_x", None)`` --
+is a trap, because RoadRunner defines::
+
+    def __getattr__(self, name):
+        if name != "this" and name in self._getIds(SelectionRecord_ALL):
+            return self[name]
+        raise AttributeError(name)
+
+``__getattr__`` runs only after normal lookup has failed, so every *miss* builds
+the list of every selection id the model has, to learn that the name is not one
+of them. That list is roughly quadratic in model size: about a millisecond on a
+25-species model, over a second on 400 species, and on a model with ~9,000 ODEs
+~70 million ids, about 18 minutes and 16 GB per miss. A model pays it once per
+cache slot per instance, which is why small models never notice and a large one
+spends an hour before its first result.
+
+Reading through the instance ``__dict__`` never reaches ``__getattr__``, so a
+miss costs a dictionary lookup whatever the model size. Writing needs no care:
+RoadRunner defines no ``__setattr__``, so ``r._x = v`` is an ordinary
+instance-dict write.
+
+Use :func:`get` and :func:`put` for every engine-private attribute on a
+RoadRunner. ``tests/engine/test_model_cache.py`` fails if any of the engine's own
+cache reads causes a ``_getIds`` call.
+"""
+
+
+def _target(r):
+    """The object whose ``__dict__`` holds the caches.
+
+    ``OptRoadRunnerProxy`` wraps a RoadRunner in ``_r`` and forwards attribute
+    writes to it, so a cache written through the proxy lives on the RoadRunner.
+    Reading ``vars(proxy)`` would look in the proxy's own dict instead, which is
+    never where the value is.
+    """
+    try:
+        d = vars(r)
+    except TypeError:               # no __dict__ (slots, builtins): nothing cached
+        return None
+    inner = d.get("_r")
+    if inner is not None and "_opt_param_names" in d:
+        return inner
+    return r
+
+
+def get(r, name, default=None):
+    """The value cached on *r* under *name*, or *default*. Never calls ``__getattr__``."""
+    t = _target(r)
+    if t is None:
+        return default
+    try:
+        return vars(t).get(name, default)
+    except TypeError:
+        return default
+
+
+def put(r, name, value):
+    """Cache *value* on *r* under *name*. Returns whether it was stored.
+
+    A target that refuses attributes is tolerated, as the call sites always did:
+    the value is then recomputed next time instead of reused.
+    """
+    t = _target(r)
+    if t is None:
+        return False
+    try:
+        vars(t)[name] = value
+    except Exception:
+        return False
+    return True