PyAntiGen 2.1.6__tar.gz → 2.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyAntiGen
-Version: 2.1.6
+Version: 2.2.0
 Summary: Declarative generation, simulation and identifiability analysis of compartmental Antimony/SBML models
 Author-email: Don Elbert <elbert5770@gmail.com>
 License-Expression: MIT
@@ -28,6 +28,10 @@ Requires-Dist: pypesto
 Requires-Dist: SALib
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
+Provides-Extra: amici
+Requires-Dist: amici>=1.1.0; sys_platform != "win32" and extra == "amici"
+Requires-Dist: cmake; sys_platform != "win32" and extra == "amici"
+Requires-Dist: swig; sys_platform != "win32" and extra == "amici"
 Dynamic: license-file
 
 # PyAntiGen

{pyantigen-2.1.6 → pyantigen-2.2.0}/PyAntiGen.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyAntiGen
-Version: 2.1.6
+Version: 2.2.0
 Summary: Declarative generation, simulation and identifiability analysis of compartmental Antimony/SBML models
 Author-email: Don Elbert <elbert5770@gmail.com>
 License-Expression: MIT
@@ -28,6 +28,10 @@ Requires-Dist: pypesto
 Requires-Dist: SALib
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
+Provides-Extra: amici
+Requires-Dist: amici>=1.1.0; sys_platform != "win32" and extra == "amici"
+Requires-Dist: cmake; sys_platform != "win32" and extra == "amici"
+Requires-Dist: swig; sys_platform != "win32" and extra == "amici"
 Dynamic: license-file
 
 # PyAntiGen

{pyantigen-2.1.6 → pyantigen-2.2.0}/PyAntiGen.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ PyAntiGen.egg-info/scm_file_list.json
 PyAntiGen.egg-info/scm_version.json
 PyAntiGen.egg-info/top_level.txt
 docs/ANALYTIC_GRADIENT.md
+docs/BACKENDS.md
 docs/MULTISTART.md
 docs/PROTOCOL_LAYER.md
 docs/V2_DESIGN.md
@@ -22,17 +23,22 @@ pyantigen/.gitignore
 pyantigen/__init__.py
 pyantigen/_version.py
 pyantigen/cli.py
+pyantigen/setup_env.py
 pyantigen/.agents/skills/module_generation/SKILL.md
 pyantigen/.agents/skills/ode_conversion_antimony/SKILL.md
 pyantigen/.agents/skills/ode_extraction_pipeline/SKILL.md
 pyantigen/engine/Analytic_gradient.py
 pyantigen/engine/Anchor_cache.py
+pyantigen/engine/Backend.py
 pyantigen/engine/Deadline.py
 pyantigen/engine/Differential_evolution.py
 pyantigen/engine/Evaluator.py
 pyantigen/engine/Event_times.py
 pyantigen/engine/Fast_profile.py
+pyantigen/engine/Fim.py
 pyantigen/engine/Fit_cache.py
+pyantigen/engine/Fit_lm.py
+pyantigen/engine/Floors.py
 pyantigen/engine/Identifiability.py
 pyantigen/engine/Model_cache.py
 pyantigen/engine/Model_optimize.py
@@ -43,8 +49,12 @@ pyantigen/engine/Noise_floor.py
 pyantigen/engine/Optimize.py
 pyantigen/engine/Petab_export.py
 pyantigen/engine/Preequil_cache.py
+pyantigen/engine/Profile.py
+pyantigen/engine/Profile_amici.py
 pyantigen/engine/Profile_checkpoint.py
+pyantigen/engine/Profile_lm.py
 pyantigen/engine/Profile_plan.py
+pyantigen/engine/Profile_record.py
 pyantigen/engine/README.md
 pyantigen/engine/Results.py
 pyantigen/engine/Scaled_amici.py

{pyantigen-2.1.6 → pyantigen-2.2.0}/PyAntiGen.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 pyantigen-create = pyantigen.cli:create_project
+pyantigen-setup = pyantigen.setup_env:main

{pyantigen-2.1.6 → pyantigen-2.2.0}/PyAntiGen.egg-info/requires.txt

@@ -8,5 +8,12 @@ matplotlib
 pypesto
 SALib
 
+[amici]
+
+[amici:sys_platform != "win32"]
+amici>=1.1.0
+cmake
+swig
+
 [test]
 pytest

{pyantigen-2.1.6 → pyantigen-2.2.0}/PyAntiGen.egg-info/scm_file_list.json

@@ -8,6 +8,7 @@
     "MANIFEST.in",
     "README.md",
     "docs/ANALYTIC_GRADIENT.md",
+    "docs/BACKENDS.md",
     "docs/MULTISTART.md",
     "docs/PROTOCOL_LAYER.md",
     "docs/V2_DESIGN.md",
@@ -19,12 +20,16 @@
     "pyantigen/cli.py",
     "pyantigen/engine/Analytic_gradient.py",
     "pyantigen/engine/Anchor_cache.py",
+    "pyantigen/engine/Backend.py",
     "pyantigen/engine/Deadline.py",
     "pyantigen/engine/Differential_evolution.py",
     "pyantigen/engine/Evaluator.py",
     "pyantigen/engine/Event_times.py",
     "pyantigen/engine/Fast_profile.py",
+    "pyantigen/engine/Fim.py",
     "pyantigen/engine/Fit_cache.py",
+    "pyantigen/engine/Fit_lm.py",
+    "pyantigen/engine/Floors.py",
     "pyantigen/engine/Identifiability.py",
     "pyantigen/engine/Model_cache.py",
     "pyantigen/engine/Model_optimize.py",
@@ -35,8 +40,12 @@
     "pyantigen/engine/Optimize.py",
     "pyantigen/engine/Petab_export.py",
     "pyantigen/engine/Preequil_cache.py",
+    "pyantigen/engine/Profile.py",
+    "pyantigen/engine/Profile_amici.py",
     "pyantigen/engine/Profile_checkpoint.py",
+    "pyantigen/engine/Profile_lm.py",
     "pyantigen/engine/Profile_plan.py",
+    "pyantigen/engine/Profile_record.py",
     "pyantigen/engine/README.md",
     "pyantigen/engine/Results.py",
     "pyantigen/engine/Scaled_amici.py",
@@ -60,6 +69,7 @@
     "pyantigen/generate/rate_laws.py",
     "pyantigen/generate/reaction_creation.py",
     "pyantigen/generate/scaled_time.py",
+    "pyantigen/setup_env.py",
     "pyantigen/study/__init__.py",
     "pyantigen/study/assay.py",
     "pyantigen/study/describe.py",
@@ -109,14 +119,20 @@
     "tests/engine/test_analytic_gradient.py",
     "tests/engine/test_analytic_gradient_amici.py",
     "tests/engine/test_anchor_cache.py",
+    "tests/engine/test_backend.py",
     "tests/engine/test_better_point.py",
+    "tests/engine/test_block_title.py",
     "tests/engine/test_de_fit.py",
     "tests/engine/test_deadline.py",
     "tests/engine/test_differential_evolution.py",
     "tests/engine/test_event_parameter_reset.py",
     "tests/engine/test_event_times.py",
     "tests/engine/test_fast_profile.py",
+    "tests/engine/test_fim.py",
     "tests/engine/test_fit_cache.py",
+    "tests/engine/test_fit_lm.py",
+    "tests/engine/test_fixed_sigma.py",
+    "tests/engine/test_floors.py",
     "tests/engine/test_hessian_steps.py",
     "tests/engine/test_model_cache.py",
     "tests/engine/test_multistart_candidates.py",
@@ -127,10 +143,15 @@
     "tests/engine/test_multistart_triage.py",
     "tests/engine/test_nelder_mead.py",
     "tests/engine/test_point_identity.py",
+    "tests/engine/test_profile.py",
+    "tests/engine/test_profile_amici.py",
     "tests/engine/test_profile_grid_open.py",
+    "tests/engine/test_profile_lm.py",
     "tests/engine/test_profile_quadratic.py",
+    "tests/engine/test_profile_record.py",
     "tests/engine/test_profile_records.py",
     "tests/engine/test_profile_stream.py",
+    "tests/engine/test_protocol_profile.py",
     "tests/engine/test_results_csv_policy.py",
     "tests/engine/test_schedule_bounds.py",
     "tests/engine/test_search_mode.py",
@@ -138,6 +159,7 @@
     "tests/engine/test_segment_sensitivity.py",
     "tests/engine/test_segmented.py",
     "tests/engine/test_sigma_floor.py",
+    "tests/engine/test_sigma_key_fingerprint.py",
     "tests/engine/test_slice_screen.py",
     "tests/engine/test_slice_window.py",
     "tests/engine/test_solver_fingerprint.py",

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

@@ -0,0 +1,8 @@
+{
+  "tag": "2.2.0",
+  "distance": 0,
+  "node": "g48927540482fa68669cb63e24ba6437f15b2669f",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-28"
+}

pyantigen-2.2.0/docs/BACKENDS.md

@@ -0,0 +1,60 @@
+# Solver backends: RoadRunner and AMICI
+
+| | RoadRunner | AMICI |
+|---|---|---|
+| install | core dependency (`pip install pyantigen`) | `pip install "pyantigen[amici]"`, then `pyantigen-setup` |
+| platforms | Linux, macOS, Windows | Linux, macOS; **Windows only through WSL** |
+| start-up | seconds | each model is compiled to C++ once (minutes to tens of minutes), then cached |
+| run time | slower; no sensitivities | much faster per evaluation, with exact sensitivities |
+| use for | simulate, quick fits | multistart, profile likelihood, FIM |
+
+AMICI needs g++ >= 10.1 (or Apple clang), cmake and swig. `pyantigen-setup` checks all of these and
+prints the fix for anything missing (it never uses sudo). `pyantigen-setup --install-amici` pip-installs
+the package; it refuses on native Windows and on a cluster login node.
+
+## Choosing
+
+Per stage (`simulate`, `fit`, `multistart`, `profile`, `fim`), first match wins:
+
+1. `Model_run.py --backend roadrunner|amici|auto`
+2. environment variable `PYANTIGEN_BACKEND` (reaches spawned workers)
+3. `BACKEND` in the project's `Modules/Solver_settings.py`
+4. `amici`, if the optimization spec already sets `optimizer_kwargs["analytic_gradient"]`
+5. the stage default: RoadRunner for `simulate` and `fit`, AMICI for `multistart`, `profile`, `fim`
+
+`auto` at any level means no preference. A backend named at levels 1-4 that cannot run here stops the run
+with the reason and the fix. Only the stage default falls back to RoadRunner, with a note.
+
+`--backend amici` on `--optimize` switches on `analytic_gradient` for a spec that lacks it;
+`--backend roadrunner` removes it. `--simulate` is always RoadRunner.
+
+## Compiled-model cache
+
+`Solver_settings.AMICI_CACHE_DIR`, else `PYANTIGEN_AMICI_CACHE`, else a per-user cache directory
+(`~/.cache/pyantigen/amici_models`, `~/Library/Caches/...` on macOS). On a cluster, point it at group or
+scratch storage: a home directory has a small quota and compiled models are large.
+
+## Not covered yet
+
+This layer chooses and checks the backend. The multistart, profile and FIM stages still run from the
+project's `tools/` scripts; moving them into the engine is the next phase. BLAS is not checked.
+
+## Sigma rule
+
+How a data-floored block gets its sigma is a separate setting from the backend, but the AMICI long stages
+depend on it.
+
+| `sigma_floor` | sigma used | loss | for |
+|---|---|---|---|
+| `"fixed"` | the LOESS floor, as a known sigma, calibrated once | `const + 0.5 r.r` | AMICI multistart, profile, FIM |
+| `"cap"` (engine default) | `min(sigma_hat, floor)`, re-estimated at every point | concentrated NLL | older RoadRunner fits; to be retired |
+
+Precedence: the spec's `optimizer_kwargs["sigma_floor"]`, then `Solver_settings.SIGMA_FLOOR`, then the stage:
+multistart, profile and FIM on AMICI get `"fixed"`. `"cap"` there is an error, because the residual form of
+the loss (Levenberg-Marquardt, `J^T J` as the FIM) needs known sigmas.
+
+In fixed mode the floors are calibrated once, at the first point evaluated (normally x0), and are not
+recalibrated when a fit ends. `pyantigen.engine.Floors` saves them to a file and returns a sha256 stamp to put
+on every result, loads them back into worker processes, and compares two calibrations. Recalibrating at the
+optimum is a deliberate second pass: `Floors.calibrate`, refit, `Floors.compare`, and accept when
+`Floors.stable` holds.

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

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

{pyantigen-2.1.6 → pyantigen-2.2.0}/pyantigen/engine/Analytic_gradient.py

@@ -32,6 +32,8 @@ engine's parameter updates is what AMICI is given.
 AMICI is optional; on Windows it needs WSL. Nothing here imports it until a
 gradient is built.
 """
+import contextlib
+import fcntl
 import hashlib
 import json
 import os
@@ -63,7 +65,9 @@ class SimTable:
         self._index = {c: i for i, c in enumerate(self.colnames)}
 
     def __getitem__(self, key):
-        return self.data[:, self._index[key]]
+        if isinstance(key, str):
+            return self.data[:, self._index[key]]
+        return self.data[key]          # numpy-style, as RoadRunner's result array allows: table[:, j], table[i, j]
 
     def __len__(self):
         return self.data.shape[0]
@@ -134,6 +138,74 @@ class LossGradient:
             raise AnalyticGradientError("the loss is not finite")
         return v
 
+    def residual_vector(self, items, p_lin):
+        """``(r, const)``: the scaled residuals ``sqrt(w) (y - yhat) / sigma`` of every datum, and ``sum n ln sigma``.
+
+        With every block's sigma known (``PYANTIGEN_SIGMA_FLOOR=fixed`` and declared sigmas) the loss is exactly
+        ``const + 0.5 * r.r``, a nonlinear least-squares problem. Raises if any block still profiles its sigma.
+        """
+        from pyantigen.engine import Optimize as O
+        p_lin = np.asarray(p_lin, dtype=float)
+        p_dict = dict(zip(self.param_names, p_lin.tolist()))
+        sink = []
+        O._RESIDUAL_SINK = sink
+        try:
+            blocks = O.collect_loss_blocks(items, self.groups, self.replicates, self.param_names, p_lin, p_dict,
+                                           frozen_sigmas=self.frozen_sigmas)
+        finally:
+            O._RESIDUAL_SINK = None
+        sig, const = {}, 0.0
+        for key, v in blocks.items():
+            sse, n, ks, fl = O._unpack_block(v)
+            if n <= 0:
+                continue
+            s, _cost, state = O._block_sigma_resolution(sse, n, ks, fl)
+            if state != "declared":
+                raise AnalyticGradientError(
+                    f"block {key} profiles its sigma ({state}): the residual form needs every sigma known "
+                    "(set PYANTIGEN_SIGMA_FLOOR=fixed)")
+            sig[key] = s
+            const += n * np.log(max(s, 1e-300))
+        parts = [v / sig[key] for key, v in sink if key in sig and v.size]
+        if not parts:
+            raise AnalyticGradientError("the loss has no data to score")
+        return np.concatenate(parts), float(const)
+
+    def residual_jacobian(self, items, directions, p_lin):
+        """``(r, J, const)``: residuals, ``J[i, k] = d r_i / d theta_k`` (linear units), and ``sum n ln sigma``.
+
+        The derivative is taken the way :meth:`gradient` takes the loss's: central differences of the residual
+        vector along the sensitivity tables (Richardson), plus a partial for each parameter the loss names itself.
+        ``J.T @ r`` is then the gradient of ``const + 0.5 r.r`` and ``J.T @ J`` its Gauss-Newton Hessian.
+        """
+        p_lin = np.asarray(p_lin, dtype=float)
+        K = len(self.param_names)
+        r0, const = self.residual_vector(items, p_lin)
+        J = np.zeros((r0.size, K))
+
+        def res(it, p):
+            r, _c = self.residual_vector(it, p)
+            if r.size != r0.size:
+                raise AnalyticGradientError("the number of scored data changed between shifted evaluations")
+            return r
+
+        for k in range(K):
+            for units, h in self._step_groups(items, directions, k):
+                def central(x, units=units, k=k):
+                    return (res(self._shift_units(items, directions, units, k, x), p_lin)
+                            - res(self._shift_units(items, directions, units, k, -x), p_lin)) / (2.0 * x)
+                J[:, k] += (4.0 * central(h / 2.0) - central(h)) / 3.0
+            if k in self.explicit:
+                d = 1e-6 * max(abs(p_lin[k]), 1e-8)
+
+                def partial(s, k=k):
+                    up, dn = p_lin.copy(), p_lin.copy()
+                    up[k] += s
+                    dn[k] -= s
+                    return (res(items, up) - res(items, dn)) / (2.0 * s)
+                J[:, k] += (4.0 * partial(d / 2.0) - partial(d)) / 3.0
+        return r0, J, const
+
     @staticmethod
     def _shift(items, directions, k, h):
         out = {}
@@ -143,10 +215,12 @@ class LossGradient:
             out[sim] = {**item, "results": table}
         return out
 
-    def _step(self, items, directions, k):
+    def _step(self, items, directions, k, sims=None):
         """The step along direction k that moves the smallest-scale entry by ``rel_step`` of itself."""
         ratio = 0.0
         for sim, item in items.items():
+            if sims is not None and sim not in sims:
+                continue
             D = directions.get(sim)
             if D is None:
                 continue
@@ -156,6 +230,68 @@ class LossGradient:
             ratio = max(ratio, float(np.nanmax(np.abs(D[:, :, k]) / scale)) if D.size else 0.0)
         return self.rel_step / ratio if ratio > 0 else None
 
+    # One finite-difference step for the whole loss is set by the table entry with the largest relative sensitivity in ANY
+    # column of ANY simulation. A column the loss never reads (45 states in a typical table) can have sensitivities of 1e12
+    # that fix a step far too small for the column it does read, and the central difference of that is lost in rounding:
+    # on aggregation_silk the Jacobian of one arm changed by a relative 1e-3 between two points 1e-9 apart while its residuals
+    # changed by 1e-10 (the gradient jumped by 1.9). The chain rule allows a step per (simulation, column) unit:
+    # dL/dtheta_k = sum_u dL/dR_u . D_u,k, each term by shifting only that column. Units whose steps are within SPLIT_RATIO
+    # of each other are shifted together, because splitting everything into single columns turns offsetting partial
+    # derivatives (mass balances) into rounding error. Only columns that are not read could be left out, and a probe for
+    # "read" columns proved unreliable (it missed columns on silk_appfull, error 18.7), so every column with a non-zero
+    # sensitivity is a unit. Measured (silk_appfull optimum, aggregation_silk traced points): SPLIT_RATIO from 3 to 1e5 gives
+    # the old gradient on silk_appfull (error vs forward differences 0.021) and no jump on aggregation_silk (3e-4, was 1.9);
+    # 1e7 is already too coarse there (8e-3).
+    SPLIT_RATIO = 1e3
+
+    def _unit_steps(self, items, directions, k):
+        """``{(sim, column): h}``: the step that moves that column's most sensitive entry by ``rel_step`` of itself."""
+        steps = {}
+        for sim, item in items.items():
+            D = directions.get(sim)
+            if D is None or not D.size:
+                continue
+            R = item["results"].data
+            colmax = np.nanmax(np.abs(R), axis=0)
+            for c in range(R.shape[1]):
+                Dc = D[:, c, k]
+                if not np.any(Dc):
+                    continue
+                scale = np.maximum(np.abs(R[:, c]), 1e-6 * colmax[c] + 1e-300)
+                ratio = float(np.nanmax(np.abs(Dc) / scale))
+                if ratio > 0:
+                    steps[(sim, c)] = self.rel_step / ratio
+        return steps
+
+    def _step_groups(self, items, directions, k, read=None, p_lin=None):
+        """``[(units, h)]``: (simulation, column) units that share a step. The smallest remaining step serves every unit
+        within SPLIT_RATIO of it; the rest are grouped the same way. (``read`` and ``p_lin`` are accepted and ignored.)"""
+        remaining = self._unit_steps(items, directions, k)
+        groups = []
+        while remaining:
+            h0 = min(remaining.values())
+            joint = {u for u, h in remaining.items() if h <= max(self.SPLIT_RATIO, 1.0) * h0}      # always includes the smallest
+            groups.append((joint, h0))
+            for u in joint:
+                del remaining[u]
+        return groups
+
+    @staticmethod
+    def _shift_units(items, directions, units, k, h):
+        from collections import defaultdict
+        by_sim = defaultdict(list)
+        for sim, c in units:
+            by_sim[sim].append(c)
+        out = dict(items)
+        for sim, cols in by_sim.items():
+            table = items[sim]["results"]
+            data = table.data.copy()
+            D = directions[sim]
+            for c in cols:
+                data[:, c] += h * D[:, c, k]
+            out[sim] = {**items[sim], "results": type(table)(table.colnames, data)}
+        return out
+
     def gradient(self, items, directions, p_lin):
         """``(nll, grad)`` at *p_lin*.
 
@@ -167,11 +303,10 @@ class LossGradient:
         f0 = self.value(items, p_lin)
         g = np.zeros(K)
         for k in range(K):
-            h = self._step(items, directions, k)
-            if h is not None:
-                def central(s, k=k):
-                    return (self.value(self._shift(items, directions, k, s), p_lin)
-                            - self.value(self._shift(items, directions, k, -s), p_lin)) / (2.0 * s)
+            for units, h in self._step_groups(items, directions, k):
+                def central(x, units=units, k=k):
+                    return (self.value(self._shift_units(items, directions, units, k, x), p_lin)
+                            - self.value(self._shift_units(items, directions, units, k, -x), p_lin)) / (2.0 * x)
                 g[k] += (4.0 * central(h / 2.0) - central(h)) / 3.0
             if k in self.explicit:                      # the loss names this parameter itself
                 d = 1e-6 * max(abs(p_lin[k]), 1e-8)
@@ -263,6 +398,40 @@ class ParameterReplay:
 # AMICI
 # ---------------------------------------------------------------------------------------
 
+@contextlib.contextmanager
+def _build_lock(directory):
+    """Hold an exclusive lock on one model's build, across processes (a Slurm array compiles the same model at once).
+
+    Whoever gets the lock first compiles; the rest wait, then find the finished module and import it. The lock file
+    sits beside the model directory, and ``flock`` is released if the holder dies.
+    """
+    os.makedirs(os.path.dirname(directory) or ".", exist_ok=True)
+    with open(directory + ".lock", "a") as fh:
+        fcntl.flock(fh, fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(fh, fcntl.LOCK_UN)
+
+
+def _model_directory(cache_dir, name, tag):
+    """Where a compiled model lives: the simulation's name made safe for a path and a shell, plus the model's hash.
+
+    A name such as ``Aducanumab 1 mg/kg (Q4W)`` would otherwise nest a directory at the slash and break the build's
+    shell command at the parentheses.
+    """
+    return os.path.join(cache_dir, re.sub(r"\W", "_", name) + f"_{tag}")
+
+
+def _never_reached(param_names, lost_per_sim):
+    """Fitted parameters that reach no plain parameter of the model in any simulation.
+
+    A parameter one arm does not use (another drug's binding rate) is ``lost`` there by design; only one that no arm
+    reaches would silently get a zero gradient.
+    """
+    return [p for p in param_names if lost_per_sim and all(p in lost for lost in lost_per_sim)]
+
+
 def _tracked_window(settings):
     blocks = settings["simulation_blocks"]
     blocks = list(blocks.values()) if isinstance(blocks, dict) else list(blocks)
@@ -399,12 +568,9 @@ class _SimGradient:
                     f"{name}: a hook sets species initial values that depend on the fitted parameters "
                     f"({sorted(set(found) | set(direct))}); their sensitivities are not available")
             direct = found
-        lost = [p for p, hit in zip(param_names, reach.any(axis=0)) if not hit]
-        if lost:
-            raise AnalyticGradientError(
-                f"{name}: fitted parameter(s) {lost} reach no plain parameter of the model (a species "
-                "initial value, or a parameter with an initial assignment?): the analytic gradient "
-                "would be zero for them")
+        # a parameter this arm does not use (another drug's binding rate) has a zero column here by design;
+        # AmiciGradient raises if no arm at all is reached by it
+        self.lost = [p for p, hit in zip(param_names, reach.any(axis=0)) if not hit]
         self.free = [p for p, used in zip(plain, reach.any(axis=1)) if used]
 
         columns = [c for c in replicate["Observed_species"](r) if c != "time"]
@@ -418,16 +584,18 @@ class _SimGradient:
         outputs = concentration_outputs(sbml, usable)
         tag = hashlib.sha256(json.dumps([scaled.sbml, sorted(self.free), list(outputs.items())],
                                         sort_keys=True).encode()).hexdigest()[:16]
-        directory = os.path.join(cache_dir, f"{name}_{tag}")
+        directory = _model_directory(cache_dir, name, tag)
         module_name = re.sub(r"\W", "_", f"pag_{name}_{tag}")
         import amici
-        if os.path.exists(os.path.join(directory, module_name, "__init__.py")):
-            module = amici.import_model_module(module_name, directory)
-        else:
-            if verbose:
-                print(f"  [amici] compiling {name}: {len(self.free)} sensitivity parameter(s), "
-                      f"{len(usable)} output(s) -> {directory}", flush=True)
-            module = compile_model(scaled, module_name, directory, free=self.free, outputs=outputs)
+        init = os.path.join(directory, module_name, "__init__.py")
+        with _build_lock(directory):       # an __init__.py seen without the lock may belong to a build still in progress
+            if os.path.exists(init):
+                module = amici.import_model_module(module_name, directory)
+            else:
+                if verbose:
+                    print(f"  [amici] compiling {name}: {len(self.free)} sensitivity parameter(s), "
+                          f"{len(usable)} output(s) -> {directory}", flush=True)
+                module = compile_model(scaled, module_name, directory, free=self.free, outputs=outputs)
         self.runner = AmiciSegmentRunner(scaled, schedule, module, states=[], rtol=rtol, atol=atol,
                                          max_steps=max_steps)
         self.t_start, self.t_first, self.t_last = _tracked_window(settings)
@@ -571,6 +739,12 @@ class AmiciGradient:
                 model_text=model_text, paths=paths, cache_dir=cache_dir, rtol=settings["rtol"],
                 atol=settings["atol"], max_steps=settings["max_steps"], verbose=settings["verbose"],
                 seed=settings["seed"], extra_times=(settings["extra_times"] or {}).get(name, ()))
+        never = _never_reached(self.param_names, [sim.lost for sim in self.sims.values()])
+        if never:
+            raise AnalyticGradientError(
+                f"fitted parameter(s) {never} reach no plain parameter of the model in any arm (a species "
+                "initial value, or a parameter with an initial assignment?): the analytic gradient "
+                "would be zero for them")
         self.n_calls = 0
 
     @staticmethod
@@ -605,6 +779,17 @@ class AmiciGradient:
         self.n_calls += 1
         return self.loss.gradient(items, dirs, p_lin)
 
+    def linear_residual_jacobian(self, p_lin):
+        """``(r, J, const)`` on AMICI's own simulation; see :meth:`LossGradient.residual_jacobian`."""
+        items, dirs = {}, {}
+        for name, sim in self.sims.items():
+            table, D = sim.tables(p_lin, self.groups, self.replicates, self.models)
+            items[name] = {"results": table, "data": self.models[name]["df_dict"],
+                           "replicate": self.replicates[name]}
+            dirs[name] = D
+        self.n_calls += 1
+        return self.loss.residual_jacobian(items, dirs, p_lin)
+
     def __call__(self, x_opt):
         """The gradient in optimizer space (a log10 parameter's derivative is taken with respect to log10 p)."""
         from pyantigen.engine.Optimize import _to_linear