Repository navigation
Conversation
…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.
| 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] |
There was a problem hiding this comment.
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.
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
mainas 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
b6e8a41from 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 aconvergedflag that also requires complementarity on every one-way edge. Includes enumeration-referee tests (tests/test_flow_complementarity.py) anddocs/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()printedln2*Vss/CLas "t1/2". That isln2× 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 ofM; terminal mode 71% adipose).DerivedParams.effective_half_life_hnamesln2*Vss/CLcorrectly;half_life_hstays as a documented alias with the same value (no API break).PBPKModel.terminal_half_life_h()returnsln2 / −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).docs/validation_body.{md,json}summary lines andweb/data/body.json(all five web individuals; JS engine checks pass). No solver behaviour changes:M, CL and Vss are untouched.Verification