PyAntiGen 2.0.0__tar.gz → 2.0.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyAntiGen
-Version: 2.0.0
+Version: 2.0.2
 Summary: Declarative generation, simulation and identifiability analysis of compartmental Antimony/SBML models
 Author-email: Don Elbert <elbert5770@gmail.com>
 License-Expression: MIT
@@ -191,6 +191,7 @@ python Model_run.py --optimize Example2
 python Model_run.py --optimize Example3
 python Model_run.py --optimize Example4
 python Model_run.py --optimize Example5
+python Model_run.py --optimize Example6   # Sobol multi-start, see docs/MULTISTART.md
 ```
 
 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`.

{pyantigen-2.0.0 → pyantigen-2.0.2}/PyAntiGen.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyAntiGen
-Version: 2.0.0
+Version: 2.0.2
 Summary: Declarative generation, simulation and identifiability analysis of compartmental Antimony/SBML models
 Author-email: Don Elbert <elbert5770@gmail.com>
 License-Expression: MIT
@@ -191,6 +191,7 @@ python Model_run.py --optimize Example2
 python Model_run.py --optimize Example3
 python Model_run.py --optimize Example4
 python Model_run.py --optimize Example5
+python Model_run.py --optimize Example6   # Sobol multi-start, see docs/MULTISTART.md
 ```
 
 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`.

{pyantigen-2.0.0 → pyantigen-2.0.2}/PyAntiGen.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ PyAntiGen.egg-info/requires.txt
 PyAntiGen.egg-info/scm_file_list.json
 PyAntiGen.egg-info/scm_version.json
 PyAntiGen.egg-info/top_level.txt
+docs/MULTISTART.md
 docs/PROTOCOL_LAYER.md
 docs/V2_DESIGN.md
 pyantigen/.gitignore
@@ -39,6 +40,7 @@ pyantigen/engine/Optimize.py
 pyantigen/engine/Petab_export.py
 pyantigen/engine/Preequil_cache.py
 pyantigen/engine/Profile_checkpoint.py
+pyantigen/engine/Profile_plan.py
 pyantigen/engine/README.md
 pyantigen/engine/Results.py
 pyantigen/engine/Sensitivity_analysis.py

{pyantigen-2.0.0 → pyantigen-2.0.2}/PyAntiGen.egg-info/scm_file_list.json

@@ -7,6 +7,7 @@
     "LICENSE",
     "MANIFEST.in",
     "README.md",
+    "docs/MULTISTART.md",
     "docs/PROTOCOL_LAYER.md",
     "docs/V2_DESIGN.md",
     "pyantigen/.agents/skills/module_generation/SKILL.md",
@@ -31,6 +32,7 @@
     "pyantigen/engine/Petab_export.py",
     "pyantigen/engine/Preequil_cache.py",
     "pyantigen/engine/Profile_checkpoint.py",
+    "pyantigen/engine/Profile_plan.py",
     "pyantigen/engine/README.md",
     "pyantigen/engine/Results.py",
     "pyantigen/engine/Sensitivity_analysis.py",
@@ -102,15 +104,25 @@
     "tests/engine/test_fast_profile.py",
     "tests/engine/test_fit_cache.py",
     "tests/engine/test_hessian_steps.py",
+    "tests/engine/test_multistart_sampler.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_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_tolerance_floor.py",
     "tests/engine/test_wald_units.py",
+    "tests/generate/test_gen_antimony_utils.py",
+    "tests/generate/test_gen_data_interpolation.py",
+    "tests/generate/test_gen_models.py",
+    "tests/generate/test_gen_pyantigen_api.py",
+    "tests/generate/test_gen_rxndict_to_antimony.py",
     "tests/silk_fixtures/antimony_models/Antimony_Bloomingdale_2021_1a_all_reactions.txt",
     "tests/silk_fixtures/antimony_models/Antimony_Bloomingdale_2021_1a_rules.txt",
     "tests/silk_fixtures/antimony_models/Antimony_Elbert_2022_1a_all_reactions.txt",

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

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

{pyantigen-2.0.0 → pyantigen-2.0.2}/README.md

@@ -159,6 +159,7 @@ python Model_run.py --optimize Example2
 python Model_run.py --optimize Example3
 python Model_run.py --optimize Example4
 python Model_run.py --optimize Example5
+python Model_run.py --optimize Example6   # Sobol multi-start, see docs/MULTISTART.md
 ```
 
 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`.

pyantigen-2.0.2/docs/MULTISTART.md

@@ -0,0 +1,67 @@
+# Multi-start and the start sampler
+
+Nelder-Mead is a local optimizer, so a fit lands in whichever basin it starts
+in. Multi-start runs it from several points and keeps the best. Four fields on
+the optimization spec control it:
+
+| field | default | meaning |
+|---|---|---|
+| `n_starts` | `1` | number of starts. `1` is a single fit and never touches the random generator |
+| `search_decades` | `None` | radius around `x0` that starts 2..n are drawn from, in log10 units for a log-scaled parameter. Unset, the radius is half the declared bound range |
+| `start_seed` | `None` | seed for the draw. Set it in the same edit that raises `n_starts`, or runs are not reproducible and cached fits cannot resume |
+| `start_sampler` | `"lhs"` | how starts 2..n are drawn: `"lhs"` (Latin hypercube) or `"sobol"` (scrambled Sobol sequence) |
+
+Start 1 is always the spec's own `x0`, so a multi-start fit cannot come back
+worse than the single fit it replaces. Cost is linear in `n_starts`.
+
+## Choosing a sampler
+
+Both are low-discrepancy samplers from `scipy.stats.qmc`, so for a handful of
+starts in a few parameters they behave alike. Sobol fills the box more evenly
+as the number of parameters grows.
+
+Sobol's balance holds only when the number of points drawn is a power of two.
+Starts 2..n are `n_starts - 1` points, so use `n_starts` of 3, 5, 9, 17, ...
+Other counts still run, with a warning from SciPy. Latin hypercube has no such
+restriction.
+
+```python
+Optimization(
+    ...,
+    n_starts=9,              # 1 + 8 Sobol points
+    start_sampler="sobol",
+    search_decades=0.5,
+    start_seed=20260909,
+)
+```
+
+## Keep the radius small
+
+Sample around `x0`, not across the whole bound box. Drawing log-uniformly over
+bounds such as (1e-9, 1) puts starts many decades from the answer, and they
+converge to far worse basins. A `search_decades` of 0.5 to 1.0 is a reasonable
+first try. `Example6` in the template uses 1.0, enough to reach the true mode of
+the flip-flop problem from the wrong basin.
+
+## Reading the result
+
+The spread of the final NLLs across starts is the report. If they agree, the
+objective is unimodal in that region and one start will do. If they scatter,
+the fit depends on where it began, and a profile or confidence interval
+anchored on any one of them may be measuring the wrong basin.
+
+## Caching
+
+`start_sampler` is part of the fit-cache key only when it is not `"lhs"`, so
+fits cached before the field existed keep their hash. Switching to `"sobol"`
+runs a fresh fit.
+
+## What it does not cover
+
+Multi-start applies to local methods. `differential_evolution`,
+`basin_hopping`, `dual_annealing` and `shgo` search the whole domain
+themselves and ignore `n_starts` and `start_sampler`.
+
+This is distinct from `sobol_analysis`, the variance-based sensitivity
+diagnostic (`_SOBOL_ONLY`), which samples the bounds to apportion variance in
+the loss and does not search for a minimum.

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

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

{pyantigen-2.0.0 → pyantigen-2.0.2}/pyantigen/engine/Evaluator.py

@@ -924,7 +924,7 @@ class ParallelEvaluator:
 
     def profile_batch(self, jobs, on_result=None, label=None,
                       heartbeat_s=_HEARTBEAT_SECONDS, budget=None,
-                      frozen_sigmas=None, state_dir=None):
+                      frozen_sigmas=None, state_dir=None, refill=None):
         """Run profile-likelihood points in parallel, within a wall budget.
 
         ``state_dir`` is where each running point keeps its own resumable
@@ -973,8 +973,20 @@ class ParallelEvaluator:
 
         *on_result* is called with each result dict the moment it arrives.
         Returns results in completion order; callers key off the job fields.
+
+        *refill*, when given, turns the batch into a stream. It is called as
+        ``refill(n_free, in_flight)`` at the start and again each time results
+        land, with the number of worker slots not occupied by a running or
+        waiting point and the job dicts currently running, and returns up to
+        *n_free* new jobs. Those are queued behind anything already waiting and
+        admitted like the rest, so the pool holds ``n_workers`` points whenever
+        there is work to give it and never more, and each new point is planned
+        from every result so far rather than from the state when the batch was
+        assembled. The batch ends when nothing is running and *refill* returns
+        nothing. It is not consulted once the wall budget has stopped
+        admissions, so a stream cannot plan work the clock will not allow.
         """
-        if not jobs:
+        if not jobs and refill is None:
             return []
         if self._pool is None:
             self.start()
@@ -1002,6 +1014,23 @@ class ParallelEvaluator:
             # them.
             sweep_stale_temp_files(state_dir)
 
+        def top_up():
+            """Ask the planner for work to fill whatever slots are empty."""
+            nonlocal n_jobs, halted
+            if refill is None or halted:
+                return
+            if budget is not None and not budget.admits():
+                # Nothing planned now could start, so do not plan it.
+                halted = True
+                return
+            n_free = self.n_workers - len(pending) - len(backlog)
+            if n_free <= 0:
+                return
+            new = refill(n_free, [futures[f] for f in pending]) or []
+            for j in list(new)[:n_free]:
+                backlog.append(dict(j, frozen_sigmas=frozen_sigmas))
+                n_jobs += 1
+
         def admit():
             """Start points until the pool is full or the clock says stop."""
             nonlocal halted
@@ -1035,6 +1064,7 @@ class ParallelEvaluator:
                 print(f"[pool]{tag} {budget.describe()}",
                       flush=True)
 
+        top_up()
         admit()
 
         while pending:
@@ -1097,6 +1127,7 @@ class ParallelEvaluator:
                           f"({res.get('n_evals')} evals, {res.get('wall_s', 0):.0f}s)"
                           f"  [{_fmt_dur(elapsed)} elapsed]", flush=True)
 
+            top_up()
             admit()
 
         if self.verbose:
@@ -1105,7 +1136,7 @@ class ParallelEvaluator:
             print(f"[pool]{tag} {done} profile points in {elapsed:.0f}s wall "
                   f"({work:.0f}s of work, {work / elapsed:.1f}x)", flush=True)
 
-        if backlog:
+        if backlog or (halted and refill is not None):
             if budget is not None:
                 budget.stopped_early = True
             raise DeadlineReached(len(backlog), label)

{pyantigen-2.0.0 → pyantigen-2.0.2}/pyantigen/engine/Fast_profile.py

@@ -282,7 +282,7 @@ def run_fast_profile(batch, nll_batch, res_x, nll_at_optimum, param_names,
                      near_zero_frac=DEFAULT_NEAR_ZERO_FRAC,
                      span_decades=SPAN_DECADES,
                      min_reach_decades=MIN_REACH_DECADES, verbose=True,
-                     nll_at_optimum_profile=None):
+                     nll_at_optimum_profile=None, window_hi=None):
     """Screen, then one capped profile point per crossed side, in rounds.
 
     *batch* has the profile_batch signature: ``batch(jobs, on_result, label)``.
@@ -314,13 +314,13 @@ def run_fast_profile(batch, nll_batch, res_x, nll_at_optimum, param_names,
 
     # ── The screen, reused when this fit already has one ──────────────────
     screen = load_screen(ckpt_dir, param_names, res_x, threshold,
-                         span_decades, min_reach_decades)
+                         span_decades, min_reach_decades, window_hi)
     if screen is None:
         screen = run_slice_screen(
             nll_batch, res_x, nll_at_optimum, param_names, bounds,
             scales=scales, wald_se=wald_se, threshold=threshold,
             span_decades=span_decades, min_reach_decades=min_reach_decades,
-            verbose=verbose)
+            verbose=verbose, window_hi=window_hi)
         save_screen(screen, ckpt_dir)
     elif verbose:
         print(f"\n[fast profile] reusing the slice screen already run for this "
@@ -400,7 +400,8 @@ def run_fast_profile(batch, nll_batch, res_x, nll_at_optimum, param_names,
                 # A cold grid point as far as the full profile is concerned:
                 # its warm pass owes this point a sweep like any other.
                 "phase": 1,
-                "direction": 0,
+                "direction": -1 if x_slice < p_opt else 1,
+                "pass_label": "fast",
                 "x_step": abs(x_slice - p_opt),
                 "fast_profile": True,
                 "_side": side_name,

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

@@ -126,7 +126,8 @@ def data_fingerprint(models):
 
 def fit_fingerprint(param_names, x0_lin, bounds_lin, scales, groups, model_text,
                     method, optimizer_kwargs, n_starts=1, start_seed=None,
-                    search_decades=None, solver_hash=None, data_hash=None):
+                    search_decades=None, solver_hash=None, data_hash=None,
+                    start_sampler="lhs"):
     """Hashes identifying a fit *problem*, before it has been solved.
 
     Deliberately distinct from :func:`pyantigen.engine.Profile_checkpoint.spec_fingerprint`,
@@ -156,8 +157,7 @@ def fit_fingerprint(param_names, x0_lin, bounds_lin, scales, groups, model_text,
               "profile_without_opt"):
         kwargs.pop(k, None)
 
-    blob = json.dumps(
-        {
+    key = {
             "format": _FORMAT,
             "param_names": list(param_names),
             "x0": [_r(v) for v in np.atleast_1d(x0_lin)],
@@ -173,9 +173,12 @@ def fit_fingerprint(param_names, x0_lin, bounds_lin, scales, groups, model_text,
             "search_decades": search_decades,
             "solver": solver_hash,
             "data": data_hash,
-        },
-        sort_keys=True, default=_json_default,
-    )
+    }
+    # 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":
+        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]
     return model_hash, fit_hash
 

{pyantigen-2.0.0 → pyantigen-2.0.2}/pyantigen/engine/Identifiability.py

@@ -98,6 +98,17 @@ SPAN_DECADES = 3.0
 # stops evaluating close in and the walk cannot get out to the span.
 MIN_REACH_DECADES = 1.0
 
+# The slice's own crossing, located. The ladder stops the round a side first
+# rises above THRESHOLD, and on a model whose other parameters compensate that
+# first point is wildly above it (a slice dNLL of 1e4 against a profile of 5).
+# With ``window_hi`` set, a side whose first crossing lands above it is walked
+# back inward until a point lands in (THRESHOLD, window_hi]: a slice crossing
+# that is actually near the threshold, and so a lower bound on the profile
+# crossing worth having. None keeps the old behaviour exactly.
+MAX_REFINE_ROUNDS = 6
+_REFINE_MIN_RATIO = 1.0 / 16.0
+_REFINE_MAX_RATIO = 0.95
+
 # One side's verdict. Only "open" halts the run.
 #   crossed      the slice rose above the threshold: profiling may proceed
 #   open         the slice is still below the threshold decades out: PROVEN open
@@ -392,11 +403,93 @@ def _verdict(points, bound, threshold, p_opt, sign, is_log,
     }
 
 
+def _side_distance(p_opt, x, is_log, ratio_mode):
+    """Distance from the optimum in the walk's own measure.
+
+    Opt-space offset for a log10 parameter, log10 ratio for a positive linear
+    one while every point so far is positive, plain offset otherwise.
+    """
+    if is_log:
+        return abs(float(x) - float(p_opt))
+    if ratio_mode:
+        return abs(float(np.log10(x)) - float(np.log10(p_opt)))
+    return abs(float(x) - float(p_opt))
+
+
+def _side_value(p_opt, d, sign, is_log, ratio_mode):
+    """Inverse of :func:`_side_distance`."""
+    if is_log:
+        return float(p_opt) + sign * float(d)
+    if ratio_mode:
+        return float(p_opt) * float(10.0 ** (sign * d))
+    return float(p_opt) + sign * float(d)
+
+
+def _refine_value(entry, threshold, window_hi):
+    """The next value on a side that is being walked back in, or None to stop.
+
+    Aims at the geometric middle of the window. With a point already at or
+    below the threshold inside the one that was too high, the crossing is
+    bracketed and the step is a sqrt(dNLL) interpolation, which is linear in
+    distance for a locally quadratic curve. With only the optimum inside, the
+    step is a power-law extrapolation from the too-high points, dNLL = c d^p
+    with p fitted from two of them when it can be and 2 otherwise. A value the
+    model could not evaluate counts as too high and halves the distance.
+    """
+    p_opt, sign, is_log = entry["p_opt"], entry["sign"], entry["is_log"]
+    pts = entry["points"]
+    ratio_mode = (not is_log) and p_opt > 0 and all(
+        float(p["x"]) > 0 for p in pts)
+    target = float(np.sqrt(threshold * window_hi))
+
+    recs = []
+    for p in pts:
+        d = _side_distance(p_opt, p["x"], is_log, ratio_mode)
+        usable = _is_usable(p)
+        recs.append((d, float(p["dnll"]) if usable else float("inf"), usable))
+
+    high = sorted((r for r in recs if r[1] > window_hi or not r[2]),
+                  key=lambda r: r[0])
+    if not high:
+        return None
+    d_hi, dnll_hi, hi_ok = high[0]
+    low = [r for r in recs if r[2] and r[1] <= threshold and r[0] < d_hi]
+    d_lo, dnll_lo = (max(low, key=lambda r: r[0])[:2]) if low else (0.0, 0.0)
+
+    if hi_ok and np.isfinite(dnll_hi) and dnll_hi > dnll_lo and d_hi > d_lo:
+        if d_lo > 0.0 and dnll_lo > 0.0:
+            r_lo, r_hi = np.sqrt(dnll_lo), np.sqrt(dnll_hi)
+            frac = (np.sqrt(target) - r_lo) / (r_hi - r_lo)
+            frac = float(min(max(frac, 0.1), 0.9))
+            d_new = d_lo + frac * (d_hi - d_lo)
+        else:
+            exponent = 2.0
+            ups = [r for r in high if r[2] and np.isfinite(r[1]) and r[1] > 0]
+            if len(ups) >= 2 and ups[1][0] > ups[0][0] * (1.0 + 1e-9) \
+                    and ups[1][1] > ups[0][1] * (1.0 + 1e-9):
+                cand = (np.log(ups[1][1] / ups[0][1])
+                        / np.log(ups[1][0] / ups[0][0]))
+                if np.isfinite(cand) and cand > 0:
+                    exponent = float(np.clip(cand, 0.5, 6.0))
+            ratio = (target / dnll_hi) ** (1.0 / exponent)
+            ratio = float(np.clip(ratio, _REFINE_MIN_RATIO, _REFINE_MAX_RATIO))
+            d_new = d_hi * ratio
+    else:
+        d_new = d_lo + 0.5 * (d_hi - d_lo)
+
+    if not np.isfinite(d_new) or d_new <= 1e-9:
+        return None
+    if any(abs(d_new - r[0]) <= 1e-12 * max(d_new, 1.0) for r in recs):
+        return None
+    return _side_value(p_opt, d_new, sign, is_log, ratio_mode)
+
+
 def run_slice_screen(nll_batch, res_x, nll_at_optimum, param_names, bounds,
                      scales=None, wald_se=None, threshold=THRESHOLD,
                      max_points=6, growth=2.0, range_factor=2.0,
                      span_decades=SPAN_DECADES,
-                     min_reach_decades=MIN_REACH_DECADES, verbose=True):
+                     min_reach_decades=MIN_REACH_DECADES, verbose=True,
+                     window_hi=None, max_refine_rounds=MAX_REFINE_ROUNDS):
     """Evaluate every parameter's slice out across decades, stopping each side
     the moment it crosses.
 
@@ -430,6 +523,15 @@ def run_slice_screen(nll_batch, res_x, nll_at_optimum, param_names, bounds,
     been read as "open" by a full evaluation, and reads "crossed" here
     instead. That trades a slower profile on a rare, specific slice shape for
     never paying an unbounded evaluation on the common one.
+
+    ``window_hi`` adds one thing after that first crossing. A side whose first
+    point above the threshold is also above ``window_hi`` is walked back inward
+    (see :func:`_refine_value`) until a point lands in (threshold, window_hi],
+    for at most ``max_refine_rounds`` further rounds. The points that come back
+    inside the first crossing are real evaluations and are kept: a slice point
+    at or below the threshold there is certified inside the interval, which is
+    what ``inner_bracket`` records. The "open" verdict is not touched, since a
+    side only enters this walk after it has crossed.
     """
     from pyantigen.engine.Optimize import _param_bounds
 
@@ -448,7 +550,8 @@ def run_slice_screen(nll_batch, res_x, nll_at_optimum, param_names, bounds,
                                  span_decades=span_decades)
             plan.append({"index": i, "name": name, "side": side, "sign": sign,
                         "is_log": is_log, "values": vals, "points": [],
-                        "settled": False,
+                        "settled": False, "ladder_i": 0, "refine": False,
+                        "n_refine": 0,
                         "p_opt": float(res_x[i]),
                         "bound": (lb if sign < 0 else ub)})
 
@@ -464,31 +567,56 @@ def run_slice_screen(nll_batch, res_x, nll_at_optimum, param_names, bounds,
               f"the profile, which is all the screen needs.", flush=True)
 
     n_evaluations = 0
-    for r in range(max_rounds):
+    r = 0
+    max_total = max_rounds + (int(max_refine_rounds) if window_hi else 0)
+    while r < max_total:
         round_xs, round_owner = [], []
         for entry in plan:
-            if entry["settled"] or r >= len(entry["values"]):
+            if entry["settled"]:
                 continue
-            v = entry["values"][r]
+            if entry["refine"]:
+                v = _refine_value(entry, threshold, window_hi)
+                if v is None:
+                    entry["settled"] = True
+                    continue
+            else:
+                if entry["ladder_i"] >= len(entry["values"]):
+                    continue
+                v = entry["values"][entry["ladder_i"]]
+                entry["ladder_i"] += 1
             x = res_x.copy()
             x[entry["index"]] = v
             round_xs.append(x)
             round_owner.append((entry, v))
         if not round_xs:
             break
+        r += 1
         if verbose:
-            print(f"[screen] round {r + 1}: {len(round_xs)} side(s) still "
-                  f"undecided.", flush=True)
+            n_ref = sum(1 for e, _ in round_owner if e["refine"])
+            extra = (f", {n_ref} walking back in toward the window"
+                     if n_ref else "")
+            print(f"[screen] round {r}: {len(round_xs)} side(s) still "
+                  f"undecided{extra}.", flush=True)
         n_evaluations += len(round_xs)
-        nlls = nll_batch(round_xs, label=f"slice-screen-r{r + 1}")
+        nlls = nll_batch(round_xs, label=f"slice-screen-r{r}")
         for (entry, v), nll in zip(round_owner, nlls):
             nll = float(nll)
             point = {"x": float(v),
                     "x_linear": float(10.0 ** v if entry["is_log"] else v),
                     "nll": nll, "dnll": float(nll - nll_at_optimum)}
             entry["points"].append(point)
-            if _is_usable(point) and point["dnll"] > threshold:
-                entry["settled"] = True
+            usable = _is_usable(point)
+            if entry["refine"]:
+                entry["n_refine"] += 1
+                if usable and threshold < point["dnll"] <= window_hi:
+                    entry["settled"] = True
+                elif entry["n_refine"] >= int(max_refine_rounds):
+                    entry["settled"] = True
+            elif usable and point["dnll"] > threshold:
+                if window_hi is None or point["dnll"] <= window_hi:
+                    entry["settled"] = True
+                else:
+                    entry["refine"] = True
 
     report = {"threshold": float(threshold),
               "anchor": float(nll_at_optimum),
@@ -496,17 +624,25 @@ def run_slice_screen(nll_batch, res_x, nll_at_optimum, param_names, bounds,
               "param_names": list(param_names),
               "span_decades": float(span_decades),
               "min_reach_decades": float(min_reach_decades),
+              "window_hi": (float(window_hi) if window_hi else None),
               "n_evaluations": n_evaluations,
               "n_candidates": n_candidates,
               "parameters": {}}
 
     for entry in plan:
+        # Evaluation order is not distance order once a side has been walked
+        # back in, and everything downstream (the verdict, the inner bracket,
+        # the fast profile's crossing) reads points outward from the optimum.
+        entry["points"].sort(key=lambda q: abs(q["x"] - entry["p_opt"]))
         side = _verdict(entry["points"], entry["bound"], threshold,
                         entry["p_opt"], entry["sign"], entry["is_log"],
                         min_reach_decades=min_reach_decades)
         side["is_log"] = entry["is_log"]
         side["stopped_early"] = bool(entry["settled"]
-                                     and len(entry["points"]) < len(entry["values"]))
+                                     and entry["ladder_i"] < len(entry["values"]))
+        side["crossing"] = _crossing_record(entry["points"], threshold,
+                                            window_hi, entry["p_opt"],
+                                            entry["is_log"])
         report["parameters"].setdefault(entry["name"], {})[entry["side"]] = side
 
     states = [s["state"] for sides in report["parameters"].values()
@@ -520,6 +656,27 @@ def run_slice_screen(nll_batch, res_x, nll_at_optimum, param_names, bounds,
     return report
 
 
+def _crossing_record(points, threshold, window_hi, p_opt, is_log):
+    """The slice point nearest the threshold from above, or None.
+
+    This is the slice's crossing as far as the screen located it: the usable
+    point with the smallest dNLL among those above the threshold. ``in_window``
+    says whether it landed inside (threshold, window_hi]; when it did not, the
+    refinement ran out of rounds or was never asked for, and the crossing is
+    only an upper limit on where the slice crosses.
+    """
+    above = [q for q in points if _is_usable(q) and q["dnll"] > threshold]
+    if not above:
+        return None
+    q = min(above, key=lambda t: t["dnll"])
+    ratio_mode = (not is_log) and p_opt > 0 and q["x"] > 0
+    return {"x": float(q["x"]), "x_linear": float(q["x_linear"]),
+            "dnll": float(q["dnll"]),
+            "decades": float(_side_distance(p_opt, q["x"], is_log, ratio_mode)),
+            "in_window": bool(window_hi is not None
+                              and q["dnll"] <= window_hi)}
+
+
 def failing_sides(report):
     """Every side the screen proved unbounded, flattened for reporting."""
     out = []
@@ -550,6 +707,7 @@ def screen_summary(report):
         "parameters": {
             name: {side: {"state": rec["state"],
                           "inner_bracket": rec["inner_bracket"],
+                          "crossing": rec.get("crossing"),
                           "reach": rec["reach"],
                           "reach_decades": rec["reach_decades"],
                           "dnll_at_reach": rec["dnll_at_reach"],
@@ -658,7 +816,7 @@ def save_screen(report, ckpt_dir):
 
 def load_screen(ckpt_dir, param_names, res_x, threshold=THRESHOLD,
                 span_decades=SPAN_DECADES,
-                min_reach_decades=MIN_REACH_DECADES):
+                min_reach_decades=MIN_REACH_DECADES, window_hi=None):
     """A screen already run for this exact fit, or None.
 
     The checkpoint directory is keyed by model hash, spec hash and the optimum,
@@ -689,6 +847,13 @@ def load_screen(ckpt_dir, param_names, res_x, threshold=THRESHOLD,
                 return None
         except (TypeError, ValueError):
             return None
+    # A screen run without the window must not answer for one asked to refine,
+    # and the reverse: the points it holds are different points.
+    stored_hi = report.get("window_hi")
+    if (stored_hi is None) != (window_hi is None):
+        return None
+    if window_hi is not None and abs(float(stored_hi) - float(window_hi)) > 1e-12:
+        return None
     stored = np.asarray(report.get("res_x") or [], dtype=float)
     current = np.asarray(res_x, dtype=float)
     if stored.shape != current.shape or not np.allclose(stored, current,
@@ -701,7 +866,8 @@ def screen_or_raise(nll_batch, res_x, nll_at_optimum, param_names, bounds,
                     scales=None, wald_se=None, ckpt_dir=None,
                     threshold=THRESHOLD, max_points=6, growth=2.0,
                     range_factor=2.0, span_decades=SPAN_DECADES,
-                    min_reach_decades=MIN_REACH_DECADES, verbose=True):
+                    min_reach_decades=MIN_REACH_DECADES, verbose=True,
+                    window_hi=None):
     """Run the screen (or reuse one), report it, and stop the run if it failed.
 
     Raises :class:`UnidentifiableParameters` when any side is proven unbounded.
@@ -709,7 +875,7 @@ def screen_or_raise(nll_batch, res_x, nll_at_optimum, param_names, bounds,
     to lie inside the confidence interval.
     """
     report = load_screen(ckpt_dir, param_names, res_x, threshold,
-                         span_decades, min_reach_decades)
+                         span_decades, min_reach_decades, window_hi)
     if report is not None:
         if verbose:
             print(f"\n[screen] reusing the slice screen already run for this "
@@ -722,7 +888,7 @@ def screen_or_raise(nll_batch, res_x, nll_at_optimum, param_names, bounds,
             scales=scales, wald_se=wald_se, threshold=threshold,
             max_points=max_points, growth=growth, range_factor=range_factor,
             span_decades=span_decades, min_reach_decades=min_reach_decades,
-            verbose=verbose,
+            verbose=verbose, window_hi=window_hi,
         )
         path = save_screen(report, ckpt_dir)