Skip to content

steady_state(): converged=True with wrong flows when valves close (mixed-unit tolerance) #3

Open

Description

@MikeMike88

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 below tol and 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 term c q|q| has c < 0. The edge law then stops increasing at q_crit = R/(2|c|). Between two reservoirs this gives three steady states for small dp, and no forward solution above R²/(4|c|). Example: a 10 cm vessel going from 3 to 6 mm has q_crit ≈ 0.53 L/min and R²/(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

  1. rohanarun commented on Nov 10, 2026

    @rohanarun
    Owner

    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. On main, 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.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions