Repository navigation
Description
Found while testing the flow solver from #2 (branch auto/E-vein-flow-graph, commit 8152583).
When some valves are closed, FlowNetwork.steady_state() can return converged=True with wrong flows. The headline venous result of #2 is not affected: all its valves are open, and it matches an exact solution to 2e-16.
Reproduce
import numpy as np
from vh.graph.flow import FlowNetwork, FlowNodeSpec, VesselSpec
def ves(i, a, b, r, valve=False):
return VesselSpec(i, a, b, length_m=0.1, radius_m=0.003, resistance_pa_s_m3=r,
gravity_head_pa=0.0, valve=valve)
nodes = [FlowNodeSpec("r0", "reservoir", pressure_pa=500.0),
FlowNodeSpec("j0", "junction", source_m3_s=8.7e-7),
FlowNodeSpec("j1", "junction"),
FlowNodeSpec("j2", "junction", source_m3_s=4.2e-7)]
vessels = [ves("e0", "r0", "j0", 6.7e8), ves("e1", "j1", "j0", 1.3e8),
ves("e2", "j0", "j2", 5.5e8), ves("e3", "r0", "j2", 8.4e8),
ves("e4", "j0", "j2", 1.3e8, valve=True), ves("e5", "j0", "j2", 1.7e7, valve=True),
ves("e6", "r0", "j1", 1.2e7, valve=True)]
net = FlowNetwork.from_specs(nodes, vessels)
sol = net.steady_state()
q = np.array([sol.flow[e] for e in net.edge_ids])
imbalance = (net.B @ q + net.source)[~net.is_reservoir]
print("converged:", sol.converged, " residual_norm: %.1e" % sol.residual_norm)
print("node imbalance / max|q|: %.2f" % (np.max(np.abs(imbalance)) / np.max(np.abs(q))))
print("q(e6) = %.2e through valve r0 -> j1, p(r0) = %.0f Pa, p(j1) = %.0f Pa"
% (sol.flow["e6"], sol.pressure["r0"], sol.pressure["j1"]))Output on 8152583:
converged: True residual_norm: 3.0e-07
node imbalance / max|q|: 0.22
q(e6) = 2.84e-07 through valve r0 -> j1, p(r0) = 500 Pa, p(j1) = 1475 Pa
So mass balance is off by 22% of the largest flow, and valve e6 carries flow against its pressure difference. The exact solution has q(e6) = 0 and p(j1) = 982 Pa. Overall the flows are off by 87%.
Cause
The steady residual mixes units: node rows are flows in m³/s, edge rows are pressures in Pa. It is compared with one absolute number: 1e-7 in _solve_active, 1e-6 for converged. At physiological scale (q ~ 1e-6 m³/s, p ~ 1e3 Pa), a node imbalance of 3e-7 m³/s passes as zero. The root finder is given the same badly scaled system, so nothing else catches it. A final max(q, 0) clamp then hides the negative flows through valves that should be closed. Also, converged does not check complementarity (closed valve with positive driving pressure, open valve with q < 0), and the active-set loop stops after 20 sweeps without reporting it.
Referee. Try every open/closed valve pattern (2^k linear solves) and keep the self-consistent one. This is exact, and it is independent of the solver. Against it, 39 of 2000 random valve networks gave wrong flows with converged=True; the worst error among them was 23%.
A fix, if useful
Branch auto/E-steady-complementarity in the fork MikeMike88/virtual-human (one commit on top of #2): MikeMike88@b6e8a41
- Solver. Scaled residual rows; Newton per pattern with the analytic Jacobian; Murty least-index pivoting.
converged. True only if the scaled residual is belowtoland complementarity holds.- Result. 0 of 6000 random networks wrong, flow error ≤ 8e-15 against enumeration. Venous result unchanged (88.6688 mmHg).
- Tests.
tests/test_flow_complementarity.py, with enumeration referees for valves and Starling regimes. - Docs.
docs/steady_complementarity.md. With valves and monotone losses, the steady equations are the KKT system of a strictly convex minimum-content program, so the flows are unique. Linear valves give a P-matrix LCP. Starling uniqueness holds in every enumerated case but is not proved.
Two model notes from the same work, not changed in the branch:
- Expanding edge. On a single edge that widens (
area_dst > area_src), the kinetic termc q|q|hasc < 0. The edge law then stops increasing atq_crit = R/(2|c|). Between two reservoirs this gives three steady states for smalldp, and no forward solution aboveR²/(4|c|). Example: a 10 cm vessel going from 3 to 6 mm hasq_crit ≈ 0.53 L/minandR²/(4|c|) ≈ 49 Pa. A contraction followed by the matching expansion is fine, because the two kinetic terms cancel. - Collapsible edges are one-way. Reverse flow through a Starling vessel is forbidden. This is not stated in the docs.
Happy to open a PR against auto/E-vein-flow-graph (or main after #2 merges) if you want it.
Activity
rohanarun commentedon Nov 10, 2026
I reproduced the false convergence on current
main. In a seeded run of 400 valve networks, I compared the solver with an independent solve that enumerates every open/closed valve pattern. Onmain, 5 results marked converged failed the node balance or valve checks. The flow changes in #5 passed all 400 cases.The flow fix is in #5, which also carries the half-life change for #4. I left a review comment on that change with an IV case it still needs to handle before merge.