Skip to content

Make reported numbers match the model's own equations (flow convergence, PBPK half-life) - #5

Open
ahrazzle wants to merge 2 commits into
mainfrom
fix/reported-numbers
Open

ahrazzle wants to merge 2 commits into
mainfrom
fix/reported-numbers

Conversation

@ahrazzle

@ahrazzle ahrazzle commented Nov 8, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Stack: #5 → #6 → #7 → #8 (this PR is layer 1 of 4). Each branch contains the previous layer, so merging in order with merge commits lands the whole stack in one sweep with no conflicts (verified locally: four sequential merges, final tree identical to the #8 tip, 304 tests passing). GitHub retargets each child to main as its parent merges. Please avoid squash- or rebase-merging individual layers, which would strand the child branches' copies of the parent commits.
The two open correctness reports share one theme — reported numbers must match the model's own equations — so they land together. File overlap with the integration PR is limited to README/index lines, already union-resolved in #6's branch.

Fixes #3
Fixes #4

#3 — steady-state flow solver (commit by @MikeMike88, carried verbatim)

The first commit is @MikeMike88's b6e8a41 from his fork, cherry-picked with authorship preserved, per his offer in #3 to open this PR. If he would rather open it himself, close this PR in favour of his — no objection.

It replaces the mixed-unit absolute tolerances in FlowNetwork.steady_state() (m³/s node rows and Pa edge rows judged against one absolute 1e-6) with scaled residual rows, Newton with the analytic Jacobian per open/closed pattern, Murty least-index pivoting, and a converged flag that also requires complementarity on every one-way edge. Includes enumeration-referee tests (tests/test_flow_complementarity.py) and docs/steady_complementarity.md (uniqueness via the minimum-content KKT system; Starling uniqueness recorded as an enumeration-backed conjecture), plus documentation of the expanding-edge multi-steady-state behaviour and the one-way nature of collapsible edges.

Independent verification here (not the author's own tests): a brute-force 2^k valve-pattern enumeration probe over 400 seeded random valved networks went from 10 false-converged (worst 7.4e-3) before the fix to 0 false-converged, worst error 2.0e-15 after. The headline venous result is unchanged (88.7 mmHg standing, scripts/validate_flow.py). Note #3's exact example happens to solve correctly under this machine's scipy even before the fix — the defect class is environment-sensitive, which is exactly why the enumeration property test is the right referee.

#4 — PBPK half-life reporting

summary() printed ln2*Vss/CL as "t1/2". That is ln2 × mean residence time, which equals the elimination half-life only for a one-compartment model; for reference-male midazolam it prints 2.61 h against the model's own terminal half-life of 4.14 h (slowest eigenvalue −0.16752/h of the non-sink block of M; terminal mode 71% adipose).

  • DerivedParams.effective_half_life_h names ln2*Vss/CL correctly; half_life_h stays as a documented alias with the same value (no API break).
  • PBPKModel.terminal_half_life_h() returns ln2 / −max Re(eig) over the non-sink states; summary() now prints both: t1/2,terminal ~4.1 h (effective ln2*Vss/CL ~2.6 h).
  • New test referees the eigenvalue value against the fitted terminal log-slope of a simulated IV curve — independent of the eig computation.
  • Regenerated docs/validation_body.{md,json} summary lines and web/data/body.json (all five web individuals; JS engine checks pass). No solver behaviour changes: M, CL and Vss are untouched.

Verification

MikeMike88 and others added 2 commits November 8, 2026 17:48
…ed flag

steady_state() mixed m^3/s node rows and Pa edge rows under one absolute
tolerance (1e-7 inside, 1e-6 for converged). At physiological scale a node
imbalance of 3e-7 m^3/s passed as zero, so on random valve networks 39/2000
solves returned converged=True with wrong flows (worst 23%; a 4-node
regression network is off by 87%). A final max(q, 0) clamp hid the negative
flows through closed valves.

The solver now scales every residual row, solves each open/closed pattern by
Newton with the analytic Jacobian (exact in one step for linear edges), pivots
with Murty's least-index rule, and sets converged only if the scaled residual
is below tol and every one-way edge satisfies complementarity. The implicit
Euler Newton step gets the same scaling and warns instead of silently
returning a non-converged iterate.

Referee: exact enumeration of all valve / collapse regimes. 0/6000 wrong,
error <= 8e-15; the headline venous network is unchanged (88.6688 mmHg).
docs/steady_complementarity.md proves flow uniqueness for valves (minimum
content KKT), reduces linear valves to a P-matrix LCP, records Starling
uniqueness as an enumeration-backed conjecture, and documents that the
expansion kinetic term makes the lumped model ill-posed above 0.53 L/min
for a 3->6 mm vessel (not fixed here).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
summary() printed ln2*Vss/CL as t1/2. That is ln2 * mean residence time,
which equals the elimination half-life only for a one-compartment model;
for reference-male midazolam it is 2.61 h against the model's own
terminal half-life of 4.14 h (slowest eigenvalue of the non-sink block
of M, terminal mode 71% adipose).

- DerivedParams.effective_half_life_h names ln2*Vss/CL correctly;
  half_life_h remains as a documented alias with the same value.
- PBPKModel.terminal_half_life_h() returns ln2 / -max Re(eig) on the
  non-sink block; summary() now prints both quantities.
- New test referees the eigenvalue value against the fitted terminal
  log-slope of a simulated IV curve (independent of eig).
- Regenerated docs/validation_body and web/data/body.json summaries
  (all five web individuals); JS engine checks still pass.

No solver behavior changes: M, CL and Vss are untouched.
Comment thread vh/body/pbpk.py
measure. Returns inf if the non-sink system has no decaying mode
(e.g. all clearances zero).
"""
keep = [i for i, n in enumerate(self.names) if n not in self.SINKS]

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reported IV half-life can come from an unvisited gut compartment.

The eigenvalue calculation removes the accumulator states but keeps the stomach and intestinal transit states. An IV dose enters the venous pool and never reaches those states. If a gut mode decays more slowly than the circulating drug, its eigenvalue sets the reported half-life even though that mode is absent from the plasma curve.

Repro: construct a PBPKModel from replace(MIDAZOLAM, renal_filtration=0.0) with clint_hepatic_l_h=1e5, peff_1e4_cm_s=0 and every tissue kp=0.01. After a 5 mg IV bolus, terminal_half_life_h() reports 0.32875 h. A log-linear fit of the simulated plasma curve from 1 to 5 h gives 0.04525 h.

For IV, use the circulating block reached by the dose and observed in plasma. If reporting an oral terminal half-life too, account for absorption separately and add a regression where the IV terminal slope is faster than intestinal transit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

3 participants