PyAntiGen 2.0.2__tar.gz → 2.0.3__tar.gz

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

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

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

@@ -105,6 +105,7 @@
     "tests/engine/test_fit_cache.py",
     "tests/engine/test_hessian_steps.py",
     "tests/engine/test_multistart_sampler.py",
+    "tests/engine/test_multistart_stage.py",
     "tests/engine/test_nelder_mead.py",
     "tests/engine/test_point_identity.py",
     "tests/engine/test_profile_grid_open.py",

{pyantigen-2.0.2 → pyantigen-2.0.3}/PyAntiGen.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "2.0.2",
+  "tag": "2.0.3",
   "distance": 0,
-  "node": "g6b1549beb3e3a5bc372670dbc2e8e502501b547d",
+  "node": "g0218ed4d70bfc541384240d1eda8c923794f4d21",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-05"

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

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

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

@@ -156,6 +156,13 @@ def fit_fingerprint(param_names, x0_lin, bounds_lin, scales, groups, model_text,
     for k in ("profile_method", "profile_optimizer_kwargs", "profile_grid",
               "profile_without_opt"):
         kwargs.pop(k, None)
+    # The multi-start stage decides where the fit starts, which matters only
+    # when there is more than one start. Dropped otherwise so that giving every
+    # 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"):
+            kwargs.pop(k, None)
 
     key = {
             "format": _FORMAT,
@@ -175,8 +182,9 @@ def fit_fingerprint(param_names, x0_lin, bounds_lin, scales, groups, model_text,
             "data": data_hash,
     }
     # Left out at the default so fits cached before the sampler existed keep
-    # their hash; it matters only when n_starts > 1.
-    if (start_sampler or "lhs") != "lhs":
+    # their hash, and left out at one start, where nothing is sampled, so that
+    # a project-wide default of "sobol" does not invalidate single-start fits.
+    if int(n_starts or 1) > 1 and (start_sampler or "lhs") != "lhs":
         key["start_sampler"] = start_sampler
     blob = json.dumps(key, sort_keys=True, default=_json_default)
     fit_hash = hashlib.sha256(blob.encode("utf-8")).hexdigest()[:16]

{pyantigen-2.0.2 → pyantigen-2.0.3}/pyantigen/engine/Model_optimize.py

@@ -973,12 +973,20 @@ def _slice_dnll_at_optimum(param_vals, dnll, opt_val, rtol=1e-6):
     return float(y[i])
 
 
-def _save_likelihood_slice_plot(opt, param_names, plot_path, model_name, tag="ALL"):
-    """Run likelihood slice once per parameter and save plot."""
+def _save_likelihood_slice_plot(opt, param_names, plot_path, model_name, tag="ALL",
+                                slice_settings=None):
+    """Run likelihood slice once per parameter and save plot.
+
+    slice_settings is the spec's ``slice_settings`` ({"n_points", "range_factor"});
+    absent keys keep the values that used to be fixed here, 20 and 2.0.
+    """
     from datetime import datetime
     import numpy as np
     import matplotlib.pyplot as plt
 
+    n_points = int((slice_settings or {}).get("n_points", 20))
+    range_factor = float((slice_settings or {}).get("range_factor", 2.0))
+
     slice_func = opt.get("stats", {}).get("likelihood_slice")
     if not slice_func:
         print("Warning: no likelihood_slice closure in opt['stats'] — skipping plot.")
@@ -1004,7 +1012,7 @@ def _save_likelihood_slice_plot(opt, param_names, plot_path, model_name, tag="AL
     results = None
     if slice_all is not None:
         try:
-            results = slice_all(n_points=20, range_factor=2.0)
+            results = slice_all(n_points=n_points, range_factor=range_factor)
         except Exception as exc:
             print(f"  batched slice failed ({exc}); falling back per parameter.")
 
@@ -1014,7 +1022,7 @@ def _save_likelihood_slice_plot(opt, param_names, plot_path, model_name, tag="AL
             if results is not None and pname in results:
                 pv, nr = results[pname]
             else:
-                pv, nr = slice_func(i, n_points=20, range_factor=2.0)
+                pv, nr = slice_func(i, n_points=n_points, range_factor=range_factor)
             cache[i] = (pv, nr)
             slice_traces[pname] = {"x": np.asarray(pv).tolist(),
                                    "y": np.asarray(nr).tolist()}
@@ -1233,7 +1241,9 @@ def setup_optimization_from_groups(settings, optimization_settings, EXPERIMENT_d
 
         if settings.get("slice_analysis") and opt.get("stats", {}).get("likelihood_slice"):
             _save_likelihood_slice_plot(opt, optimization_settings.param_names, paths["plot_path"],
-                                        MODEL_NAME, tag=groups_tag)
+                                        MODEL_NAME, tag=groups_tag,
+                                        slice_settings=getattr(optimization_settings,
+                                                               "slice_settings", None))
         if (settings.get("profile_likelihood_analysis") or settings.get("fast_profile_likelihood_analysis")) and opt.get("stats", {}).get("profile_likelihood"):
             _save_profile_likelihood_plot(
                 opt, optimization_settings.param_names, paths["plot_path"],

{pyantigen-2.0.2 → pyantigen-2.0.3}/pyantigen/engine/Optimize.py

@@ -2259,6 +2259,10 @@ _ENGINE_ONLY_OPTIMIZER_KEYS = (
     "profile_method",
     "profile_optimizer_kwargs",
     "profile_grid",             # read by pyantigen.engine.Model_optimize._profile_kwargs
+    # Multi-start as its own stage: see _resolve_multistart_stage.
+    "multistart_method",
+    "multistart_optimizer_kwargs",
+    "multistart_limits",
 )
 
 
@@ -2314,6 +2318,58 @@ def _resolve_profile_optimizer(method, optimizer_kwargs):
     return profile_method, profile_kwargs
 
 
+def _resolve_multistart_stage(method, optimizer_kwargs):
+    """Method and kwargs for a separate multi-start stage, or (None, {}).
+
+    Absent ``multistart_method`` in optimizer_kwargs, multi-start is what it
+    always was: every start is fitted with the spec's own method and options and
+    the best of them IS the fit.
+
+    Present, multi-start becomes a stage that runs BEFORE the fit. Each start is
+    run with this method and ``multistart_optimizer_kwargs`` -- typically a
+    bounds-respecting method with a small iteration cap, since the point is to
+    find the basin, not to converge -- and the best point it reaches is where
+    the standard fit then starts. A global method is not accepted here: it would
+    search the box the starts are meant to sample.
+    """
+    kw = optimizer_kwargs or {}
+    ms_method = kw.get("multistart_method")
+    if not ms_method:
+        return None, {}
+    if str(ms_method).lower() in _GLOBAL_METHODS:
+        raise ValueError(
+            f"multistart_method {ms_method!r} is a global method; the multi-start "
+            f"stage runs a local method from each sampled start.")
+    return ms_method, dict(kw.get("multistart_optimizer_kwargs") or {})
+
+
+# What a multi-start evaluation may spend, and what a failure costs.
+#   max_attempts   safe_simulate attempts per simulation, the first included.
+#   max_depth      levels of time-span subdivision after those fail; 0 = none.
+#   failure_dnll   a failed evaluation is scored at the worst finite NLL among
+#                  the screened starts PLUS this, instead of 1e10.
+# 1e10 is a cliff: a gradient method that steps into it reads a slope of
+# ~1e10/step, shrinks to nothing and stalls. A finite, merely large penalty is
+# something the line search can step back from. It is fixed once, from the
+# screen, so the surface does not move under the optimizer while it runs.
+_MULTISTART_LIMIT_DEFAULTS = {"max_attempts": 4, "max_depth": 0, "failure_dnll": 1000.0}
+
+
+def _resolve_multistart_limits(optimizer_kwargs):
+    """The multi-start stage's evaluation limits: defaults overlaid by the spec's
+    ``multistart_limits``. An unknown key is an error, not a silent no-op."""
+    given = dict((optimizer_kwargs or {}).get("multistart_limits") or {})
+    unknown = sorted(set(given) - set(_MULTISTART_LIMIT_DEFAULTS))
+    if unknown:
+        raise ValueError(f"unknown multistart_limits key(s) {unknown}; expected a "
+                         f"subset of {sorted(_MULTISTART_LIMIT_DEFAULTS)}")
+    out = {**_MULTISTART_LIMIT_DEFAULTS, **given}
+    if out["failure_dnll"] is not None and not float(out["failure_dnll"]) > 0:
+        raise ValueError("multistart_limits['failure_dnll'] must be positive, or "
+                         "None to keep the 1e10 failure value")
+    return out
+
+
 def _resolve_named(value, param_names, label):
     """Normalize a per-parameter spec value (``x0`` or ``bounds``) to a list
     aligned with ``param_names``.
@@ -2558,7 +2614,8 @@ def _multistart_points(x0, bounds, scales, n_starts, search_decades=None,
 
 
 def _run_multistart(objective, starts, method, bounds, opt_kw, scales,
-                    screen=True, failure_value=1e10, verbose=True):
+                    screen=True, failure_value=1e10, verbose=True,
+                    failure_dnll=None):
     """Fit from every start, keep the best, and report the spread.
 
     The spread is as much the point as the best value.  If every start lands on
@@ -2567,6 +2624,13 @@ def _run_multistart(objective, starts, method, bounds, opt_kw, scales,
     confidence interval anchored on any single one of them is measuring the
     wrong basin -- which the engine can otherwise only discover much later, via
     ``profile_anchor_gap`` finding a point better than the reported optimum.
+
+    ``failure_dnll``: when given, an evaluation that fails (the objective's
+    ``failure_value``, or a non-finite NLL) is scored at the worst finite NLL
+    seen in the screen plus this, for the fits. The fits then see a large but
+    finite wall rather than a 1e10 cliff, which a gradient method such as
+    L-BFGS-B can step back from. The reference is fixed once, so the surface
+    does not move while the optimizer runs.
     """
     from scipy.optimize import minimize
 
@@ -2582,17 +2646,24 @@ def _run_multistart(objective, starts, method, bounds, opt_kw, scales,
     #
     # Start 1 is never screened out. It is the spec's own x0, and if that
     # cannot be integrated the caller needs to see the failure, not a silent skip.
+    def _eval(s):
+        try:
+            return float(objective(s))
+        except Exception:
+            return float("inf")
+
+    seen = []          # finite NLLs from the screen: the failure penalty's reference
     if screen and len(starts) > 1:
         kept, dropped = [], 0
         for i, s in enumerate(starts):
-            if i == 0:
+            if i == 0 and failure_dnll is None:
                 kept.append(s)
                 continue
-            try:
-                v = float(objective(s))
-            except Exception:
-                v = float("inf")
-            if np.isfinite(v) and v < failure_value:
+            v = _eval(s)
+            ok = np.isfinite(v) and v < failure_value
+            if ok:
+                seen.append(v)
+            if i == 0 or ok:
                 kept.append(s)
             else:
                 dropped += 1
@@ -2601,14 +2672,42 @@ def _run_multistart(objective, starts, method, bounds, opt_kw, scales,
                   f"the model does not integrate there.")
         starts = kept
 
+    fit_objective, failed, penalty = objective, [0], None
+    if failure_dnll is not None:
+        if not seen and starts:
+            v = _eval(starts[0])
+            if np.isfinite(v) and v < failure_value:
+                seen.append(v)
+        if seen:
+            penalty = max(seen) + float(failure_dnll)
+
+            def fit_objective(x):
+                v = _eval(x)
+                if np.isfinite(v) and v < failure_value:
+                    return v
+                failed[0] += 1
+                return penalty
+
+            if verbose:
+                print(f"  [opt] a failed evaluation scores {penalty:.6g} "
+                      f"(worst screened nll {max(seen):.6g} + {float(failure_dnll):g}) "
+                      f"during the multi-start fits.")
+        elif verbose:
+            print("  [opt] no screened start evaluated, so failed evaluations keep "
+                  "their 1e10 value in the multi-start fits.")
+
     records, best, best_i = [], None, -1
     for i, s in enumerate(starts):
         s = np.asarray(s, dtype=float)
         try:
-            r = minimize(objective, s, method=method,
+            r = minimize(fit_objective, s, method=method,
                          bounds=bounds or None, **opt_kw)
             fun = float(r.fun)
             ok, msg = bool(r.success), str(r.message)
+            if penalty is not None and fun >= penalty:
+                # Ended on the failure plateau: not an optimum of anything.
+                fun, ok = float("inf"), False
+                msg = "ended where the model does not integrate (failure penalty)"
         except Exception as exc:
             r, fun, ok = None, float("inf"), False
             msg = f"{type(exc).__name__}: {exc}"
@@ -2626,6 +2725,10 @@ def _run_multistart(objective, starts, method, bounds, opt_kw, scales,
             print(f"  [opt] start {i + 1}/{len(starts)}: nll={fun:.6g}{mark}",
                   flush=True)
 
+    if verbose and failed[0]:
+        print(f"  [opt] {failed[0]} evaluation(s) failed during the multi-start fits "
+              f"and were scored at the failure penalty.")
+
     if verbose:
         vals = [rec["fun"] for rec in records if rec["fun"] is not None]
         if len(vals) > 1:
@@ -6713,8 +6816,43 @@ def run_optimization_from_groups(
                 seed=getattr(optimization_spec, "start_seed", None),
                 sampler=getattr(optimization_spec, "start_sampler", "lhs"),
             )
+            # A separate multi-start stage, when the spec asks for one: the
+            # starts are run with their own (cheaper, bounds-respecting) method
+            # and the best point reached is where the standard fit below starts.
+            # Without it, the branch further down fits every start with the
+            # spec's own method and the best of them is the answer.
+            staged_start = None
+            ms_method, ms_kw_raw = _resolve_multistart_stage(method, optimizer_kwargs)
+            if len(starts) > 1 and ms_method:
+                if fit_cache is not None and fit_cache.load_partial() is not None:
+                    # The standard fit already started in an earlier launch, so
+                    # the stage finished then; its answer is in the partial.
+                    print("[opt] multi-start stage skipped: an earlier launch "
+                          "already began the standard fit from its result.")
+                else:
+                    ms_kw = _prepare_optimizer_kwargs(ms_method, ms_kw_raw, fast, None, None)
+                    limits = _resolve_multistart_limits(optimizer_kwargs)
+                    print(f"[opt] multi-start stage: {len(starts)} starts with "
+                          f"{ms_method}, then the standard fit ({method}) from the best. "
+                          f"Per evaluation: {limits['max_attempts']} solver attempt(s), "
+                          f"subdivision depth {limits['max_depth']}.")
+                    from pyantigen.engine.Simulate import retry_limits
+                    # The full ladder is restored on leaving the block, so the
+                    # standard fit and every diagnostic after it run as before.
+                    with retry_limits(limits["max_attempts"], limits["max_depth"]):
+                        ms_res, start_records, _best_start = _run_multistart(
+                            objective, starts, ms_method, bounds, ms_kw, scales,
+                            failure_dnll=limits["failure_dnll"])
+                    if ms_res is None:
+                        print("[opt] every multi-start fit failed; the standard "
+                              "fit starts from the spec's x0.")
+                    else:
+                        staged_start = np.asarray(ms_res.x, dtype=float)
+                        print(f"[opt] multi-start stage best nll {float(ms_res.fun):.6g} "
+                              f"(start {_best_start + 1}); the standard fit starts there.")
+                starts = starts[:1]
             if len(starts) == 1:
-                x_start = x0
+                x_start = x0 if staged_start is None else staged_start
                 partial = fit_cache.load_partial() if fit_cache is not None else None
                 if partial is not None:
                     # A previous launch of this same fit was killed before it

{pyantigen-2.0.2 → pyantigen-2.0.3}/pyantigen/engine/Simulate.py

@@ -359,6 +359,62 @@ class search_mode:
         return False
 
 
+# ---------------------------------------------------------------------------
+# Retry limits: a shorter ladder, but still a ladder
+# ---------------------------------------------------------------------------
+#
+# Search mode (above) removes the ladder altogether. The multi-start stage wants
+# something in between: most vectors it samples integrate on the first attempt,
+# and a handful need a looser tolerance, but none is worth the full ladder of ten
+# attempts and four levels of time-span subdivision that a vector somebody cares
+# about gets. Limits cap both. With max_attempts=4 and max_depth=0 a vector gets
+# the fast path plus three loosened retries, is never subdivided, and a failure
+# raises -- which the objective turns into its failure value.
+#
+# Unlike search mode this does not cap the step allowance, so a vector that
+# integrates slowly still integrates. Process-global, like search mode; the
+# default (None) is the original behaviour, 10 attempts and depth 4.
+_DEFAULT_MAX_ATTEMPTS = 10
+_DEFAULT_MAX_DEPTH = 4
+_RETRY_LIMITS = None
+
+
+def set_retry_limits(max_attempts=None, max_depth=None):
+    """Cap safe_simulate's ladder. ``None`` for both restores the defaults.
+
+    max_attempts counts the first (fast-path) attempt, as the log's
+    "Attempt n/N" does. Returns the previous setting so a caller can restore it.
+    """
+    global _RETRY_LIMITS
+    previous = _RETRY_LIMITS
+    if max_attempts is None and max_depth is None:
+        _RETRY_LIMITS = None
+        return previous
+    attempts = _DEFAULT_MAX_ATTEMPTS if max_attempts is None else int(max_attempts)
+    depth = _DEFAULT_MAX_DEPTH if max_depth is None else int(max_depth)
+    if attempts < 1 or depth < 0:
+        raise ValueError(f"retry limits need max_attempts >= 1 and max_depth >= 0, "
+                         f"got {attempts} and {depth}")
+    _RETRY_LIMITS = (attempts, depth)
+    return previous
+
+
+class retry_limits:
+    """``with retry_limits(4, 0): ...`` -- the limits for the block."""
+
+    def __init__(self, max_attempts=None, max_depth=None):
+        self.max_attempts, self.max_depth = max_attempts, max_depth
+
+    def __enter__(self):
+        self._previous = set_retry_limits(self.max_attempts, self.max_depth)
+        return self
+
+    def __exit__(self, *exc):
+        global _RETRY_LIMITS
+        _RETRY_LIMITS = self._previous
+        return False
+
+
 def _simulate_search(r, start, end, points, observed_species):
     """One capped attempt. Raises on failure; leaves the step allowance as found."""
     original = r.integrator.maximum_num_steps
@@ -454,7 +510,7 @@ def safe_simulate(r, solver_settings, observed_species, depth=0, label=None):
     label_prefix = f" [{label}]" if label else ""
     print(f"      [safe_simulate]{label_prefix} (Depth {depth}) Initial attempt failed: {first_err_str}")
 
-    max_attempts = 10
+    max_attempts, max_depth = _RETRY_LIMITS or (_DEFAULT_MAX_ATTEMPTS, _DEFAULT_MAX_DEPTH)
     attempt = 1  # one attempt already burned on the fast path
 
     while attempt < max_attempts:
@@ -513,7 +569,7 @@ def safe_simulate(r, solver_settings, observed_species, depth=0, label=None):
             )
 
     # Subdivide as last resort
-    if depth < 4 and points >= 2:
+    if depth < max_depth and points >= 2:
         mid = (start + end) / 2.0
         p1 = max(2, points // 2)
         p2 = max(2, points - p1)