Merge pull request #1 from khalil-official/results/verification-suite · khalil-official/pipeflow-bench@71ea927 · GitHub
Skip to content

Commit 71ea927

Browse files
khalil-officialkhalil-official
authored
Merge pull request #1 from khalil-official/results/verification-suite
Publish verified pipe-flow diagnostics with actual bisection animation
2 parents 3a30384 + 4c98ac1 commit 71ea927

21 files changed

Lines changed: 7768 additions & 82 deletions

‎README.md‎

Lines changed: 144 additions & 0 deletions

‎docs/api.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# API reference
2+
3+
Public imports are re-exported by `pipeflow_bench`. Physical pipeline
4+
inputs are finite positive real scalars in SI; roughness eps may be zero.
5+
Booleans are rejected by scalar pipeline/solver validation. Invalid inputs
6+
raise `ValueError`; nonrepresentable derived results raise
7+
`FloatingPointError` instead of returning infinities or zeros.
8+
9+
| Function | Return and contract |
10+
| --- | --- |
11+
| `reynolds(rho, v, D, mu)` | Re=ρvD/μ; validates inputs and finite positive result |
12+
| `laminar_friction(Re)` | 64/Re; scalar or array with every element positive/finite |
13+
| `colebrook_residual(f, Re, rel_rough)` | Signed g(f); broadcasts arrays; f/Re positive and roughness in [0,0.1); rejects nonfinite residuals |
14+
| `colebrook_friction(Re, rel_rough, tol=1e-12, max_iter=200)` | `(f, residual_history, converged)`; scalar Re>=4000 and 0<=roughness<0.1 |
15+
| `colebrook_trace(Re, rel_rough, tol=1e-12, max_iter=200)` | Dictionary with `friction_factor`, `residual_history`, `converged`, and actual `iterations` records |
16+
| `haaland_friction(Re, rel_rough)` | Explicit turbulent comparison, Re>=4000, roughness [0,0.1); broadcasts arrays |
17+
| `blasius_friction(Re)` | Smooth-pipe comparison, restricted to 4000<=Re<=1e5; scalar or array |
18+
| `pressure_loss(f, L, D, rho, v)` | Darcy-Weisbach Δp [Pa]; f and every physical scalar positive/finite |
19+
| `solve_pipe(rho, mu, v, D, L, eps, tol=1e-12)` | Regime-specific friction, pressure loss and mass flow with diagnostics |
20+
21+
## Stopping and diagnostics
22+
23+
`tol` is a finite positive absolute tolerance on the dimensionless
24+
Colebrook residual; `max_iter` is an integer >=1 (not a boolean).
25+
`converged=True` guarantees abs(history[-1])<=tol. Width reduction alone
26+
never counts as convergence. If the budget runs out or no distinct
27+
floating-point midpoint remains, return the last evaluated f and `False`.
28+
Every trace record stores `iteration`, `lo`, `hi`, `f`, `residual`, with
29+
the bracket recorded **before** the probe. The final residual corresponds
30+
to the returned f, including unsuccessful solves.
31+
32+
`solve_pipe` returns `Re`, `regime`, `friction_factor`, `dp_Pa`,
33+
`mass_flow_kg_s`, `residual_history`, `converged`, `relative_roughness`.
34+
It validates eps/D<0.1 and tolerance in all regimes. For Re<2300,
35+
the direct laminar law has the diagnostic history `[0.0]`; this is not
36+
a Colebrook residual. For 2300<=Re<4000 the result is explicitly flagged
37+
`transition-band` and uses the turbulent equation as a modeling choice.
38+
If a root solve returns False, pressure loss is only a provisional value;
39+
callers must inspect the flag before accepting it.
40+
41+
## Worked operating point
42+
43+
```python
44+
from pipeflow_bench import solve_pipe, colebrook_trace
45+
46+
result = solve_pipe(rho=998, mu=.001, v=1.5, D=.05, L=100, eps=45e-6)
47+
assert result["converged"]
48+
print(result["Re"], result["friction_factor"], result["dp_Pa"])
49+
# 74850.0 0.022531362454543326 50594.17439167704
50+
51+
trace = colebrook_trace(4000, 1e-4)
52+
print(trace["iterations"][-1]) # actual final bracket, midpoint and residual
53+
```
54+
55+
Arrays are supported for equation/reference helpers as stated, not for
56+
the scalar root solver or complete pipe operating point. These friction
57+
factors use the **Darcy** convention (four times a Fanning factor).

‎docs/model.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Model and method
2+
3+
## Problem
4+
5+
Darcy-Weisbach pressure loss in a circular pipe with friction factor by
6+
flow regime.
7+
8+
## Relations implemented
9+
10+
**Reynolds number** Re = ρ v D / μ [-] (fluid density ρ [kg/m³], mean
11+
velocity v [m/s], diameter D [m], dynamic viscosity μ [Pa·s]).
12+
13+
**Laminar regime (Re < 2300):** exact Hagen–Poiseuille friction factor
14+
15+
f = 64 / Re.
16+
17+
**Turbulent regime (Re ≥ 4000):** the Colebrook–White implicit equation
18+
19+
1/√f = −2 log₁₀( ε/(3.7 D) + 2.51/(Re √f) ),
20+
21+
solved by bracketed bisection on g(f) = 1/√f + 2 log₁₀(ε/(3.7D) +
22+
2.51/(Re√f)) over f ∈ [1e-6, 0.2] (bracket validity checked; root residual
23+
≤ the requested absolute tolerance is the only success criterion).
24+
Default tol=1e-12; the recorded Re=4000, ε/D=1e-4 case takes 43 probes.
25+
Residual histories and optional actual bracket/midpoint traces are returned.
26+
Budget exhaustion or floating-point stagnation returns a false flag.
27+
28+
**Transition band (2300 ≤ Re < 4000):** flagged `"transition-band"`; the
29+
turbulent correlation is applied WITH the band recorded — a stated modeling
30+
choice, never silent interpolation.
31+
32+
**Pressure loss (Darcy-Weisbach):**
33+
34+
Δp = f (L/D) (ρ v²/2) [Pa], ṁ = ρ v π D²/4 [kg/s].
35+
36+
## Explicit references (comparisons, never the solver)
37+
38+
- Haaland (1983): 1/√f = −1.8 log₁₀( (ε/3.7D)^1.11 + 6.9/Re ) — measured
39+
maximum relative difference vs Colebrook across the recorded sweep:
40+
**1.34%** (documented accuracy band of the approximation).
41+
- Blasius (smooth pipes, Re < 1e5): f = 0.316 Re^−0.25 — agrees with
42+
Colebrook within 5% in its validity range.
43+
44+
## Validation and domain checks
45+
46+
Finite-positive validation of every physical input (ρ, v, D, μ, L);
47+
relative roughness domain 0 ≤ ε/D < 0.1; Colebrook's public contract
48+
requires Re ≥ 4000 (the band path uses the internal bisection directly and
49+
flags the result). Laminar `laminar_friction` also accepts arrays for
50+
charting; invalid elements raise consistently for scalars and arrays.
51+
Roughness and tolerance are checked before regime selection, including
52+
laminar flow. Derived Re, pressure loss and mass flow must remain finite
53+
and positive; overflow/underflow raises rather than silently propagating.
54+
55+
## Limits
56+
57+
Single-phase incompressible fully developed flow; no minor losses, no
58+
compressibility, no non-circular ducts. The transition band has no exact
59+
correlation — the band flag exists precisely so users know when physics is
60+
uncertain.
61+
62+
63+
## Symbols, units and algorithm
64+
65+
| Symbol | Meaning | SI unit |
66+
| --- | --- | --- |
67+
| ρ | Density | kg/m³ |
68+
| μ | Dynamic viscosity | Pa·s |
69+
| v | Mean axial speed | m/s |
70+
| D | Circular internal diameter | m |
71+
| L | Pipe length | m |
72+
| ε | Equivalent wall roughness | m |
73+
| f | Darcy friction factor | dimensionless |
74+
| Re, ε/D, g | Reynolds number, relative roughness, residual | dimensionless |
75+
| Δp, ṁ | Frictional pressure loss, mass rate | Pa, kg/s |
76+
77+
Bisection first checks opposite residual signs on [1e-6,0.2]. It evaluates
78+
one midpoint, records its pre-probe bracket and residual, and stops only
79+
if abs(g)<=tol. Otherwise the sign identifies the half containing a root.
80+
If no distinct floating midpoint exists, the solver reports nonconvergence.
81+
Shrinking brackets do not imply monotonically decreasing residual
82+
magnitudes: a probe can lie farther from the root than the previous probe.
83+
The same loop drives the animation; no illustrative or fabricated probe
84+
coordinates are used. A residual tolerance verifies the equation, not an
85+
absolute friction-factor error bound or correlation accuracy.
86+
87+
The friction-chart comparison uses true Reynolds-number coordinates from
88+
the saved 30-case CSV. The Blasius line ends at Re=1e5. The 100-point
89+
pressure sweep includes low velocities in all three regimes and a separate
90+
low-speed view; transition-band points are never labeled turbulent.
91+
92+
The model assumes steady, single-phase, incompressible, fully developed
93+
flow in a straight circular pipe. It excludes entry effects, fittings,
94+
elevation, compressibility, multiphase flow, heat transfer and networks.

‎docs/results/bisection_trace.csv‎

Lines changed: 44 additions & 0 deletions

0 commit comments

Comments
 (0)