PyAntiGen 1.0.7__tar.gz → 1.0.9__tar.gz

{pyantigen-1.0.7 → pyantigen-1.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyAntiGen
-Version: 1.0.7
+Version: 1.0.9
 Summary: Short one-line description of what PyAntiGen does
 Author: Open Source Contributor
 Author-email: Don <you@example.com>
@@ -108,8 +108,16 @@ To run optimization examples use the --optimize flag:
 python Model_run.py --optimize Example1
 python Model_run.py --optimize Example2
 python Model_run.py --optimize Example3
+python Model_run.py --optimize Example4
+python Model_run.py --optimize Example5
 ```
 
+Each example prints a banner explaining what it demonstrates before the run and a "what to look for" summary after it. All output lands in `results/Example/`, prefixed with the example and group names so runs never overwrite each other — e.g. `Example_Example2_ADpos_profile_likelihood.png`, `Example_Example4_Flipflop_optimization_results.csv`.
+
+Examples 1–3 demonstrate structural identifiability: Example1/2 split the fit so each sub-problem is well-posed, while Example3 deliberately fits two exactly confounded parameters (`SF`/`V_Comp1`) jointly and shows how profile likelihood flags the ridge that likelihood slices and Sobol indices miss.
+
+Examples 4–5 go further and test the *accuracy* of the profile likelihood ΔNLL itself, on a genuinely multimodal problem with a log10 objective. The chain A → B → C observed through `SF*B_Comp1/V_Comp1` has the classic pharmacokinetic "flip-flop" ambiguity — swapping the two rate constants and rescaling `SF` reproduces the data exactly — so the likelihood has two modes separated by a known ΔNLL gap (~2.4 at the NLL optimum, set by a few deliberately noisy observations of A and printed by `data/make_flipflop_data.py`). Example4 starts in the correct basin. Accurate profiles must (a) dip below zero by a known amount (~−2.1), because the fitting objective's per-observable averaging places the fit away from the inference NLL optimum that ΔNLL is anchored to, and (b) show the second mode at ~+0.8 — below the 95% threshold, so the correct confidence set is a union of two disjoint intervals; a walker that stops at the first threshold crossing never finds it, and a first-crossing CI extractor cannot represent it. Example5 starts in the wrong basin: sigmas are frozen at the wrong mode (inflating σ for the A data and deflating every ΔNLL), and the profile must dip to ~−0.98 at the true mode. `Projects/Example/Flipflop_reference.py` recomputes the exact reference profiles from the closed-form solution with scipy (independent of RoadRunner and of the framework's loss code), replicating the pipeline's conventions — fit objective for the anchor, MLE-frozen sigmas, summed NLL — and its `--compare results/Example/<run>.json` mode scores the framework's stored profile traces against the reference automatically.
+
 Your own model lives under `Projects/MyNewModel/`. Modify the code for your model in `Projects/MyNewModel/Modules/`, `Projects/MyNewModel/Model_generate.py`, and `Projects/MyNewModel/Model_run.py`. Your problem will also require new modules in `antimony_modules/` to define the model.
 
 

{pyantigen-1.0.7 → pyantigen-1.0.9}/PyAntiGen.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyAntiGen
-Version: 1.0.7
+Version: 1.0.9
 Summary: Short one-line description of what PyAntiGen does
 Author: Open Source Contributor
 Author-email: Don <you@example.com>
@@ -108,8 +108,16 @@ To run optimization examples use the --optimize flag:
 python Model_run.py --optimize Example1
 python Model_run.py --optimize Example2
 python Model_run.py --optimize Example3
+python Model_run.py --optimize Example4
+python Model_run.py --optimize Example5
 ```
 
+Each example prints a banner explaining what it demonstrates before the run and a "what to look for" summary after it. All output lands in `results/Example/`, prefixed with the example and group names so runs never overwrite each other — e.g. `Example_Example2_ADpos_profile_likelihood.png`, `Example_Example4_Flipflop_optimization_results.csv`.
+
+Examples 1–3 demonstrate structural identifiability: Example1/2 split the fit so each sub-problem is well-posed, while Example3 deliberately fits two exactly confounded parameters (`SF`/`V_Comp1`) jointly and shows how profile likelihood flags the ridge that likelihood slices and Sobol indices miss.
+
+Examples 4–5 go further and test the *accuracy* of the profile likelihood ΔNLL itself, on a genuinely multimodal problem with a log10 objective. The chain A → B → C observed through `SF*B_Comp1/V_Comp1` has the classic pharmacokinetic "flip-flop" ambiguity — swapping the two rate constants and rescaling `SF` reproduces the data exactly — so the likelihood has two modes separated by a known ΔNLL gap (~2.4 at the NLL optimum, set by a few deliberately noisy observations of A and printed by `data/make_flipflop_data.py`). Example4 starts in the correct basin. Accurate profiles must (a) dip below zero by a known amount (~−2.1), because the fitting objective's per-observable averaging places the fit away from the inference NLL optimum that ΔNLL is anchored to, and (b) show the second mode at ~+0.8 — below the 95% threshold, so the correct confidence set is a union of two disjoint intervals; a walker that stops at the first threshold crossing never finds it, and a first-crossing CI extractor cannot represent it. Example5 starts in the wrong basin: sigmas are frozen at the wrong mode (inflating σ for the A data and deflating every ΔNLL), and the profile must dip to ~−0.98 at the true mode. `Projects/Example/Flipflop_reference.py` recomputes the exact reference profiles from the closed-form solution with scipy (independent of RoadRunner and of the framework's loss code), replicating the pipeline's conventions — fit objective for the anchor, MLE-frozen sigmas, summed NLL — and its `--compare results/Example/<run>.json` mode scores the framework's stored profile traces against the reference automatically.
+
 Your own model lives under `Projects/MyNewModel/`. Modify the code for your model in `Projects/MyNewModel/Modules/`, `Projects/MyNewModel/Model_generate.py`, and `Projects/MyNewModel/Model_run.py`. Your problem will also require new modules in `antimony_modules/` to define the model.
 
 

{pyantigen-1.0.7 → pyantigen-1.0.9}/PyAntiGen.egg-info/SOURCES.txt

@@ -24,14 +24,22 @@ framework/pyantigen.py
 framework/rate_laws.py
 framework/reaction_creation.py
 framework/template/Example/AntiGen_paths.py
+framework/template/Example/Flipflop_reference.py
 framework/template/Example/Model_generate.py
 framework/template/Example/Model_run.py
+framework/template/Example/Engine/Anchor_cache.py
+framework/template/Example/Engine/Deadline.py
 framework/template/Example/Engine/Evaluator.py
+framework/template/Example/Engine/Event_times.py
+framework/template/Example/Engine/Fast_profile.py
+framework/template/Example/Engine/Fit_cache.py
+framework/template/Example/Engine/Identifiability.py
 framework/template/Example/Engine/Model_optimize.py
 framework/template/Example/Engine/Model_simulate.py
 framework/template/Example/Engine/Nuisance_sensitivity.py
 framework/template/Example/Engine/Optimize.py
 framework/template/Example/Engine/Petab_export.py
+framework/template/Example/Engine/Preequil_cache.py
 framework/template/Example/Engine/Profile_checkpoint.py
 framework/template/Example/Engine/Results.py
 framework/template/Example/Engine/Sensitivity_analysis.py
@@ -47,4 +55,6 @@ framework/template/Example/Modules/Solver_settings.py
 framework/template/Example/Modules/Update_opt_parameters.py
 framework/template/Example/Modules/Update_parameters.py
 framework/template/data/ADneg.csv
-framework/template/data/ADpos.csv
+framework/template/data/ADpos.csv
+framework/template/data/Flipflop.csv
+framework/template/data/make_flipflop_data.py

{pyantigen-1.0.7 → pyantigen-1.0.9}/README.md

@@ -82,8 +82,16 @@ To run optimization examples use the --optimize flag:
 python Model_run.py --optimize Example1
 python Model_run.py --optimize Example2
 python Model_run.py --optimize Example3
+python Model_run.py --optimize Example4
+python Model_run.py --optimize Example5
 ```
 
+Each example prints a banner explaining what it demonstrates before the run and a "what to look for" summary after it. All output lands in `results/Example/`, prefixed with the example and group names so runs never overwrite each other — e.g. `Example_Example2_ADpos_profile_likelihood.png`, `Example_Example4_Flipflop_optimization_results.csv`.
+
+Examples 1–3 demonstrate structural identifiability: Example1/2 split the fit so each sub-problem is well-posed, while Example3 deliberately fits two exactly confounded parameters (`SF`/`V_Comp1`) jointly and shows how profile likelihood flags the ridge that likelihood slices and Sobol indices miss.
+
+Examples 4–5 go further and test the *accuracy* of the profile likelihood ΔNLL itself, on a genuinely multimodal problem with a log10 objective. The chain A → B → C observed through `SF*B_Comp1/V_Comp1` has the classic pharmacokinetic "flip-flop" ambiguity — swapping the two rate constants and rescaling `SF` reproduces the data exactly — so the likelihood has two modes separated by a known ΔNLL gap (~2.4 at the NLL optimum, set by a few deliberately noisy observations of A and printed by `data/make_flipflop_data.py`). Example4 starts in the correct basin. Accurate profiles must (a) dip below zero by a known amount (~−2.1), because the fitting objective's per-observable averaging places the fit away from the inference NLL optimum that ΔNLL is anchored to, and (b) show the second mode at ~+0.8 — below the 95% threshold, so the correct confidence set is a union of two disjoint intervals; a walker that stops at the first threshold crossing never finds it, and a first-crossing CI extractor cannot represent it. Example5 starts in the wrong basin: sigmas are frozen at the wrong mode (inflating σ for the A data and deflating every ΔNLL), and the profile must dip to ~−0.98 at the true mode. `Projects/Example/Flipflop_reference.py` recomputes the exact reference profiles from the closed-form solution with scipy (independent of RoadRunner and of the framework's loss code), replicating the pipeline's conventions — fit objective for the anchor, MLE-frozen sigmas, summed NLL — and its `--compare results/Example/<run>.json` mode scores the framework's stored profile traces against the reference automatically.
+
 Your own model lives under `Projects/MyNewModel/`. Modify the code for your model in `Projects/MyNewModel/Modules/`, `Projects/MyNewModel/Model_generate.py`, and `Projects/MyNewModel/Model_run.py`. Your problem will also require new modules in `antimony_modules/` to define the model.
 
 

{pyantigen-1.0.7 → pyantigen-1.0.9}/framework/cli.py

@@ -66,6 +66,26 @@ def create_project():
                             
                             # Add the reaction to the model
                             self.add_reaction(Reaction_name, Reactants, Products, Rate_type, Rate_eqtn_prototype)
+
+
+                    class BasicChainReaction(PyAntiGenModule):
+                        \"\"\"
+                        Adds the second step of the chain A -> B -> C.
+                        With k_B_to_C = 0 (the default in Example_parameters.csv) the
+                        model behaves exactly like the single-step A -> B examples;
+                        Example4/Example5 fit k_B_to_C to demonstrate flip-flop
+                        bimodality.
+                        \"\"\"
+                        def build(self):
+                            Compartments = ['Comp1']
+                            for Comp in Compartments:
+                                Reaction_name = f"Basic_B_to_C_{{Comp}}"
+                                Reactants = f"[B_{{Comp}}]"
+                                Products = f"[C_{{Comp}}]"
+                                Rate_type = "MA"
+                                Rate_eqtn_prototype = "k_B_to_C"
+
+                            self.add_reaction(Reaction_name, Reactants, Products, Rate_type, Rate_eqtn_prototype)
                 """))
         print(f"  Created folder: {d}/")
 
@@ -126,6 +146,7 @@ def create_project():
     with open(param_csv_path, "w") as f:
         f.write("Parameter,Value,Units,Comment\n")
         f.write("k_A_to_B,0.1,,Default rate constant for A to B\n")
+        f.write("k_B_to_C,0.0,,Default rate constant for B to C (0 disables the chain step)\n")
         f.write("V_Comp1,1.0,,Default compartment volume\n")
     print("  Created file: antimony_models/Example/Example_parameters.csv")
 
@@ -134,6 +155,7 @@ def create_project():
         f.write("Species,InitialCondition,Units,Comment\n")
         f.write("A_Comp1,0.0,,Initial amount of A\n")
         f.write("B_Comp1,0.0,,Initial amount of B\n")
+        f.write("C_Comp1,0.0,,Initial amount of C\n")
     print("  Created file: antimony_models/Example/Example_InitialConditions.csv")
 
     init_cond_path = os.path.join(example_antimony_dir, "Example_manual.txt")

pyantigen-1.0.9/framework/template/Example/Engine/Anchor_cache.py

@@ -0,0 +1,193 @@
+"""Hessian-derived quantities, cached against the fit they belong to.
+
+The Wald statistics cost ``1 + 2k + 2k(k-1)`` objective evaluations -- 513 on
+the 16-parameter SILK APP spec -- and they are recomputed from scratch on every
+launch. That was tolerable when an evaluation was assumed to cost seconds. It
+is not: the measured cost on that spec is 116 s, so across 39 workers the
+Hessian alone is about 25 minutes, and it is charged again on every link of a
+chain that may run to a hundred links.
+
+On a preemptible partition the number matters for a second and sharper reason.
+Nothing is written until a profile point finishes, so a link only makes
+progress if the node survives setup *plus* one slice. Cutting 25 minutes off
+setup lowers that threshold directly, which is the difference between a
+short-lived node contributing something and contributing nothing at all.
+
+Caching is safe here because the Hessian is a pure function of things the run
+already fingerprints: the model, the optimization spec, the parameter scaling
+and the optimum it is taken at. A change in any of them produces a different
+key and a miss, so a stale Hessian cannot be silently reused -- the failure
+mode that would matter, since an SE that does not belong to this fit would set
+the profile's whole grid in the wrong place.
+"""
+
+import hashlib
+import json
+import os
+from datetime import datetime
+
+import numpy as np
+
+from Engine.Profile_checkpoint import sweep_stale_temp_files
+
+# Everything _attach_wald_stats puts in out["stats"]. Cached and restored as a
+# set: a partial restore would leave the CI from one fit beside the SE of
+# another.
+WALD_FIELDS = ("wald_cov", "wald_se", "wald_se_opt", "wald_ci",
+               "wald_correlation")
+
+# Bumped when the set or meaning of the cached fields changes, so old files
+# miss rather than being misread.
+#   v1 held only the linear "wald_se".
+#   v2 adds "wald_se_opt", the SE in the optimizer's own space, which is what
+#      the profile and slice grids are placed with. A v1 file restored into a
+#      v2 run would leave that key absent and silently drop every grid back to
+#      the range_factor fallback.
+_FORMAT = "wald-v2"
+
+# Without this the block is not worth restoring: the profile grid is placed
+# from it, and "no SE at all" triggers a different, deliberate fallback than
+# "an SE in the wrong units".
+_REQUIRED = ("wald_se", "wald_se_opt")
+
+
+def _encode(obj):
+    """Arrays to nested lists, with non-finite values as null.
+
+    Non-finite entries are meaningful here -- an SE of nan is how "this
+    direction is flat, there is no usable standard error" is reported -- but
+    they are not portable JSON. They come back as nan, which is what every
+    consumer tests for with ``np.isfinite``.
+    """
+    if obj is None:
+        return None
+    arr = np.asarray(obj, dtype=float)
+    out = arr.tolist()
+
+    def _clean(v):
+        if isinstance(v, list):
+            return [_clean(x) for x in v]
+        return v if np.isfinite(v) else None
+
+    return _clean(out)
+
+
+def _decode(obj):
+    """The inverse: nulls back to nan, lists back to arrays."""
+    if obj is None:
+        return None
+
+    def _fill(v):
+        if isinstance(v, list):
+            return [_fill(x) for x in v]
+        return float("nan") if v is None else float(v)
+
+    return np.asarray(_fill(obj), dtype=float)
+
+
+def bounds_fingerprint(bounds):
+    """Hash of the declared bounds.
+
+    Separate from the profile's own spec hash on purpose. Bounds change the
+    Wald *interval* (it is clipped to them) without changing the model or the
+    optimum, so they belong in this cache's key -- but adding them to
+    ``spec_fingerprint`` would change every existing profile directory name and
+    orphan work already done.
+    """
+    if bounds is None:
+        return "none"
+    try:
+        blob = json.dumps(
+            [None if b is None else [None if v is None else round(float(v), 12)
+                                     for v in b]
+             for b in bounds],
+            sort_keys=True,
+        )
+    except (TypeError, ValueError):
+        return "unhashable"
+    return hashlib.sha256(blob.encode("utf-8")).hexdigest()[:16]
+
+
+class AnchorCache:
+    """Reads and writes the Wald block for one fit."""
+
+    def __init__(self, root, run_id, model_hash, spec_hash, bounds_hash,
+                 n_params, enabled=True):
+        self.enabled = bool(enabled and root)
+        self.model_hash = model_hash
+        self.spec_hash = spec_hash
+        self.bounds_hash = bounds_hash
+        self.n_params = int(n_params)
+        self.dir = os.path.join(root, "profiles", run_id) if root else None
+        if self.enabled and self.dir:
+            try:
+                os.makedirs(self.dir, exist_ok=True)
+                # A kill between writing a temp file and renaming it leaves the
+                # temp behind; this directory is where they collect.
+                sweep_stale_temp_files(self.dir)
+            except OSError:
+                self.enabled = False
+
+    @property
+    def path(self):
+        return os.path.join(self.dir, "anchor.json") if self.dir else None
+
+    def load(self):
+        """The cached Wald block, or None on any miss.
+
+        Every failure is a miss rather than an error: a corrupt, truncated or
+        stale file must cost the 25 minutes of recomputation it was meant to
+        save, never the correctness of the run.
+        """
+        if not (self.enabled and self.path and os.path.exists(self.path)):
+            return None
+        try:
+            with open(self.path, "r", encoding="utf-8") as fh:
+                data = json.load(fh)
+        except (OSError, ValueError):
+            return None
+
+        if (data.get("format") != _FORMAT
+                or data.get("model_hash") != self.model_hash
+                or data.get("spec_hash") != self.spec_hash
+                or data.get("bounds_hash") != self.bounds_hash
+                or int(data.get("n_params") or -1) != self.n_params):
+            return None
+
+        stats = {}
+        for field in WALD_FIELDS:
+            if field in data:
+                stats[field] = _decode(data[field])
+
+        for field in _REQUIRED:
+            arr = stats.get(field)
+            if arr is None or np.asarray(arr).shape != (self.n_params,):
+                return None
+        return stats
+
+    def save(self, stats):
+        """Write the Wald block, atomically."""
+        if not (self.enabled and self.path):
+            return
+        payload = {
+            "format": _FORMAT,
+            "model_hash": self.model_hash,
+            "spec_hash": self.spec_hash,
+            "bounds_hash": self.bounds_hash,
+            "n_params": self.n_params,
+            "saved": datetime.now().isoformat(timespec="seconds"),
+        }
+        for field in WALD_FIELDS:
+            if stats.get(field) is not None:
+                payload[field] = _encode(stats[field])
+
+        tmp = f"{self.path}.{os.getpid()}.tmp"
+        try:
+            with open(tmp, "w", encoding="utf-8") as fh:
+                json.dump(payload, fh)
+            os.replace(tmp, self.path)
+        except (OSError, TypeError, ValueError):
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass