ExchangeLaw.hpp File Reference

Regime-aware 1D↔2D exchange law (COUPLING_LAW WEIR_ORIFICE): free / submerged weir and orifice, surface→sewer and sewer→surface. More...

#include <cmath>

Include dependency graph for ExchangeLaw.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	openswmm::twoD::exchange::Geometry
	A coupling point's structure, SI. More...
struct	openswmm::twoD::exchange::Coefficients
	Discharge coefficients and the φ regularisation head. More...
struct	openswmm::twoD::exchange::Result

Namespaces
namespace	openswmm
namespace	openswmm::twoD
namespace	openswmm::twoD::exchange

Macros
#define	OPENSWMM_EXCHANGE_HD   inline

Functions
OPENSWMM_EXCHANGE_HD double	openswmm::twoD::exchange::phi (double x, double eps)
	C¹-regularised √x: √x for x ≥ ε, (3/(2√ε))x − x²/(2ε^{3/2}) below.
OPENSWMM_EXCHANGE_HD double	openswmm::twoD::exchange::dphi (double x, double eps)
	dφ/dx (finite at 0).
OPENSWMM_EXCHANGE_HD double	openswmm::twoD::exchange::smoothstep (double t)
	Hermite smoothstep of t clamped to [0, 1].
OPENSWMM_EXCHANGE_HD double	openswmm::twoD::exchange::softmin (double a, double b, double &wa, double &wb)
	p-norm minimum, p = 16: (a^−16 + b^−16)^(−1/16) for a, b > 0, else 0. Evaluated as min / (1 + r^16)^(1/16), r = min/max ∈ (0, 1], with four square roots — no overflow, no pow. Weights ∂Q/∂a, ∂Q/∂b go to wa, wb.
OPENSWMM_EXCHANGE_HD Result	openswmm::twoD::exchange::exchange (const Geometry &geo, const Coefficients &c, double h2, double h1)
	Evaluate the bidirectional regularized weir/orifice exchange and damping.

Variables
constexpr double	openswmm::twoD::exchange::kGravity = 9.80665
	m/s²
constexpr double	openswmm::twoD::exchange::kSigmaBand = 0.1
	submergence blend width

Detailed Description

Regime-aware 1D↔2D exchange law (COUPLING_LAW WEIR_ORIFICE): free / submerged weir and orifice, surface→sewer and sewer→surface.

Pure functions of the two heads and a point's geometry and coefficients — no mesh, no SimulationContext — so the CPU marcher, the Kokkos solver and a HydroCouple component evaluate one law. Header-only and host/device callable (KOKKOS_INLINE_FUNCTION when Kokkos is included first).

SI throughout; heads and the crest in the 2D metre frame. Sign: Q > 0 drains 2D→1D, Q < 0 spills 1D→2D.

h_s = max(0, h2 − z) is the surface depth over the crest z.

Surface → sewer (h2 > h1, h_s > 0): free weir Qf = ⅔ C_w L_w √(2g) h_s φ(h_s) (h1 ≤ z) submerged weir Qs = C_sw L_w √(2g) h_s φ(h2 − h1) (h1 > z) orifice free Of = C_oi A_o √(2g) φ(h_s), submerged Os = C_oi A_o √(2g) φ(h2 − h1) The free and submerged forms blend over the submergence band σ = (h1 − z)/h_s ∈ [0, σ_band] with the Hermite smoothstep, so the law is C¹ across h1 = z whatever C_sw is (Rubinato et al. 2017 give C_sw per regime; with C_sw = ⅔ C_w the two weir forms already agree at h1 = z). The weir and the orifice then combine through the p-norm minimum (the limiting control governs): Q = (Qw^−p + Qo^−p)^(−1/p), p = 16 (≤ min, 4.3 % under at Qw = Qo)

Sewer → surface (h1 > h2, h1 > z), orifice: Q = −C_oo A_o √(2g) [(1 − S) φ(h1 − z) + S φ(h1 − h2)], S the smoothstep of σ_out = (h2 − z)/(h1 − z) over [0, σ_band]: a dry surface (h2 ≤ z) discharges against the crest, a wet one against its own head, C¹ across h2 = z.

φ is the C¹-regularised square root (φ(x) = √x for x ≥ ε, a quadratic with finite slope below) that bounds the sensitivity as the heads meet. ε is a parameter: 0.02 m at field scale, scaled with the structure for a laboratory rig.

See also

plans/1D2D_FINE_SCALE_COUPLING_PLAN_2026-10-19.md §3 and §0R (R1–R6)

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright

Copyright (c) 2026 Caleb Buahin. All rights reserved.

License

Apache-2.0

Macro Definition Documentation

OPENSWMM_EXCHANGE_HD

#define OPENSWMM_EXCHANGE_HD   inline