An original Python tool that solves the implicit Colebrook–White equation by bracketed bisection — with visible residual histories, regime flags, and the root verified against its own equation to 1e-12.
Quick start · Method · Results · Verification · References
A transparent pipe-flow pressure-loss tool built around an honestly solved implicit friction relation: the Colebrook equation is solved by bracketed bisection with visible residual histories and explicit regime/transition-band flags, and explicit approximations (Haaland, Churchill) are carried as comparison references — never as the solver.
Scope: single-phase incompressible fully developed flow in circular pipes. No minor losses, compressibility, or non-circular ducts — every exclusion is stated, nothing is silently approximated.
| 🔬 Physics | Darcy friction factor across laminar, transition and turbulent regimes |
| 🧮 Numerics | Bracketed bisection with validated brackets and full residual histories |
| 🔍 Diagnostics | Transition-band flag, stagnation detection, equation-satisfaction check |
| 📊 Evidence | 39 tests, CSV traces, verification report, animated solver convergence |
| Regime | Reynolds | Treatment |
|---|---|---|
| Laminar | Re < 2300 | Exact law f = 64/Re |
| Transition | 2300 ≤ Re < 4000 | Flagged; turbulent correlation applied with the band recorded |
| Turbulent | Re ≥ 4000 | Colebrook–White by bisection on g(f) = 1/√f + 2 log₁₀(ε/3.7D + 2.51/(Re√f)) |
The solver validates its bracket, requires the requested residual before returning
converged=True, and returns the complete residual history; budget exhaustion or
floating-point stagnation returns an explicit False. Pressure loss follows
Δp = f (L/D) ρv²/2 with ṁ = ρvπD²/4 and finite-positive validation throughout.
flowchart LR
A[Inputs: rho, mu, v, D, L, eps] --> B{"Validate finite & positive"}
B -- invalid --> E1[❌ ValueError]
B -- ok --> C{Regime from Re}
C -- laminar --> D1[f = 64/Re]
C -- transition --> D2[🚩 flag band + turbulent path]
C -- turbulent --> D3["Bracket + bisection on Colebrook g(f)"]
D1 --> F[Darcy–Weisbach Δp, ṁ]
D2 --> F
D3 --> G{"residual ≤ tol?"}
G -- yes --> F
G -- no --> E2[❌ converged = False + history]
F --> H[✅ result dict + regime + flags]
Full details: docs/model.md · API: docs/api.md
python -m pip install -r requirements-dev.txt
python -m pytest tests -q # 39 verification tests
python examples/run_verification.py # figures + GIF + raw data📦 Verified environments
Verified: Python 3.13.5, NumPy 2.1.3, Windows 11; CI on Ubuntu. Tests complete in
under 1 s locally; generation runtime is recorded in docs/results/run_summary.json.
🧱 Repository layout & API example
pipeflow_bench/
└── colebrook.py # regime logic, implicit solver, references, pipeline
tests/test_colebrook.py # 39 verification tests
examples/run_verification.py
docs/ model.md api.md verification.md results/
from pipeflow_bench import solve_pipe
result = solve_pipe(rho=998.0, mu=1.0e-3, v=1.5, D=0.05, L=100.0, eps=4.5e-5)
print(result["Re"], result["regime"], result["friction_factor"], result["dp_Pa"])
# 74850.0 turbulent 0.022531362454543326 50594.17439167704| Correlation | Type | Role here |
|---|---|---|
| Colebrook (1939) | Implicit | The solved reference root |
| Haaland (1983) | Explicit | Comparison band — max 1.34% off Colebrook in the recorded sweep |
| Churchill (1977) | Explicit, all regimes | Full-range cross-check (< 4%, laminar limit exact) |
| Blasius | Explicit, smooth turbulent | Smooth-pipe comparison (< 5%) |
39 test cases: equation-satisfaction at the returned root, analytic fully-rough limit, Blasius/Haaland accuracy bands, monotonicity, transition band flagging, exact hand pressure loss, input validation. Evidence and limits: docs/verification.md.
Not claimed: correlation-vs-nature accuracy (Colebrook is an empirical relation); anything outside fully developed incompressible pipe flow.
🔍 Repaired failure cases
- At Re=10⁷ and zero roughness, a width-based early exit previously claimed success at |g|=1.031e-9 for a requested tolerance of 1e-9. Success now requires the requested residual; excessively tight tolerance yields an explicit false flag on finite-precision stagnation.
- NaN roughness at Re=3,000 previously produced a nonfinite residual with a true convergence flag. Invalid roughness is now rejected before every regime branch, including laminar flow.
- The comparison plot now uses numerical Reynolds numbers from its CSV, and the animation's range contains the actual root and evaluated probes.
- Empirical correlations: solver correctness ≠ physical accuracy of the correlation.
- Transition band results are flagged approximations.
- No minor losses / fittings / networks.
▶ Watch the implicit solver converge:
43 frames of the recorded bisection residual history on the implicit
Colebrook–White equation (Re = 4·10³, ε/D = 10⁻⁴); the dashed line marks
the converged root. Produced by examples/run_verification.py.
Each frame adds a real evaluated solver state; the left plot shows the
equation, current probe and bracket, the right the full residual history.
The final root is f=0.0400084312335583 with absolute residual 2.1e-13 —
iteration progression, not time.
▶ Open the 43-frame GIF directly · Actual brackets, midpoints and residuals
- friction_chart.png — friction factor vs Reynolds across regimes with the transition band marked
- pipeline_sweep.png — operating-point sweep with a second view of the low-speed regimes so flagged transition data are visible
- residual_history.png — solver residual history
- Raw CSVs:
explicit_comparison.csv,residual_history.csv,pipeline_sweep.csv,run_summary.jsonin docs/results/
- S. W. Churchill, "Friction factor equation spans all fluid-flow regimes" (Chemical Engineering, 1977) — full-range explicit comparison.
- S. E. Haaland, "Simple and explicit formulas for the friction factor in turbulent pipe flow" (1983).
- C. F. Colebrook, "Turbulent flow in pipes" (1939).
- L. F. Moody, "Friction factors for pipe flow" (1944) — the Moody chart.
- Darcy–Weisbach framework as consolidated in modern fluid-mechanics texts.
Dependencies: NumPy (BSD-3), Matplotlib (PSF-based), Pillow (HPND), pytest (MIT). This repository's own code is original and MIT-licensed; see LICENSE.