Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Calculate the gas void fraction below the critical gas Froude number.
Uses the first expression for chi(X) in Equation (30), not the
alternative fitted approximation. This is the low-Froude branch of
Equation (29).
Parameters:
X (float) – Non-negative Lockhart-Martinelli liquid-loading parameter [-].
Returns:
alpha (float) – Fraction of the pipe volume occupied by gas [-], not the flowing
gas volume fraction (GVF). Dry gas (X = 0) gives 1.
NaN for non-finite/negative X or a predicted fraction outside (0, 1].
Notes
chi=1/(1+X)-X**0.76+1.44*X.
The JIP range extends to X = 0.30. Values above this are extrapolation,
even when the returned fraction is physically bounded.
Estimate the transition Froude number from gas properties and diameter.
Implements Fr_crit=2.3e-5*Oh_gas**(-1.1). This alternative to
the WLR approximation requires independently supplied fluid properties.
Parameters:
rho_g (float) – Positive gas density at line conditions [kg/m3].
mu_g (float) – Positive gas dynamic viscosity at line conditions [Pa.s].
surface_tension (float) – Positive gas-liquid interfacial tension at line conditions [N/m].
D (float) – Positive inner pipe diameter [m].
Returns:
Fr_gas_crit (float) – Critical gas densimetric Froude number [-].
NaN for non-finite or non-physical input/result.
Notes
Gas properties, not liquid viscosity, define Oh_gas in this correlation.
For an oil-water mixture, Equation (43) provides a simplified linear rule
weighted by the liquid volumetric-flow split, implemented in
fluid_mechanics.gas_liquid_interfacial_tension_linear_mixing.
Choosing this transition correlation does not implement Equation (28).
Calculate gas void fraction across the low- and high-Froude branches.
Below the transition, use the low-Froude correlation. Above it,
relax exponentially towards the no-slip limit GVF.
Parameters:
X (float) – Non-negative Lockhart-Martinelli parameter [-].
Fr_gas (float) – Non-negative gas densimetric Froude number based on actual gas
flow, not the over-reading indicated flow [-].
GVF (float) – Flowing gas volume fraction at line conditions [-], in (0, 1].
Must describe the same liquid loading and densities as X.
Fr_gas_crit (float, optional) – Positive transition Froude number [-]. Default 1.2 is the
WLR = 0 value. Either critical-Froude helper can supply this input.
Returns:
alpha_gas (float) – Gas void fraction and indicated-flow correction multiplier [-].
Model over-reading is 1/alpha_gas.
NaN for non-finite/non-physical input or a non-physical prediction.
Notes
Above the transition, alpha=(chi-GVF)*exp(-0.4*(Fr_gas-Fr_gas_crit))+GVF.
Both branches meet continuously at Fr_gas_crit. Without densities this
function cannot check consistency between X and GVF; the flow wrapper
computes both from a common set of inputs.
Check an operating point against the DNV USM wet-gas JIP ranges reported in 2015.
Parameters:
GVF (float) – Flowing gas volume fraction at line conditions [-].
X (float) – Lockhart-Martinelli parameter [-].
DR (float) – Gas-to-liquid density ratio [-].
Fr_gas (float) – Gas densimetric Froude number at corrected gas flow [-].
Returns:
checks (dict) – Boolean entries GVF, X, DR and Fr_gas. True means
the individual value is within the checked range:
0.95 < GVF <= 1, 0 <= X <= 0.30, 0.010 <= DR <= 0.032,
and 0.7 <= Fr_gas <= 2.2. Non-finite input gives False.
Notes
Checks only GVF, Lockhart-Martinelli parameter, density ratio and gas
densimetric Froude number against the ranges reported in the 2015 NSFMW
paper [1]. The year identifies that publication, not the test dates.
This is an operating-range check, not a wet-gas correction calculation.
Does not assess consistency between inputs, diameter, orientation,
pressure, temperature, fluid properties or meter suitability.
The JIP used a horizontal 6-inch line at 12-32 bara and 15-35 degC,
with natural gas, Exxsol D120 and saline water.
Passing all checks does not establish model accuracy for a meter.
An out-of-range flag denotes extrapolation, not necessarily an
unphysical input. The X = 0 limit includes the analytical dry-gas case.
Apply the Van Putten (2015) wet-gas over-reading correction to a USM.
Corrects an ultrasonic meter’s indicated gas volume flow for the
over-reading predicted under wet-gas conditions. Solves
Q_actual=alpha_gas(Q_actual)*Q_indicated using the simplified
Van Putten model from the 2015 NSFMW paper. Liquid loading must be supplied
independently; the meter reading alone cannot determine it.
Parameters:
VolFlow_gas_measured (float) – Non-negative indicated gas flow at line conditions [m3/h].
Any established dry-gas calibration must already have been applied.
This function applies only the wet-gas over-reading correction.
D (float) – Positive inner pipe diameter [m].
rho_g (float) – Positive gas density at line conditions [kg/m3].
rho_l (float) – Liquid density at the same conditions, greater than rho_g [kg/m3].
For oil/water, a supplied volume-weighted mixture density may be
calculated using fluid_mechanics.mixture_density_homogeneous.
It must be consistent with WLR; no properties are inferred here.
GVF (float, optional) – Flowing gas volume fraction [-], in (0, 1]. Supply GVF or GMF.
If both are supplied, GVF takes precedence and GMF is recalculated.
Both supplied fractions must nevertheless be valid.
GMF (float, optional) – Gas mass fraction [-], in (0, 1]. Converted to GVF when GVF is absent.
WLR (float, optional) – Water volume flow / total liquid volume flow [-], in [0, 1].
Default 0. Used only for the default critical-Froude correlation.
Ignored, including validation, when Fr_gas_crit is supplied.
Fr_gas_crit (float, optional) – Positive critical gas Froude number [-]. If omitted, calculated
from WLR, Equation (27). To use Equation (26), supply the result of
critical_froude_from_Ohnesorge_VanPutten_2015 explicitly.
check_input (bool, optional) – If True, raise on invalid input or calculation failure. If False
(default), return NaN numerical fields and a descriptive error.
Incorrect argument types can raise regardless of this setting.
Returns:
results (dict) – Fields (all flow rates are at line conditions):
VolFlow_gas_measured: supplied indicated gas flow [m3/h].
VolFlow_gas_corrected: corrected gas flow [m3/h].
VolFlow_liq: liquid flow inferred from the supplied fraction [m3/h].
VolFlow_tot: corrected gas plus liquid flow [m3/h].
MassFlow_gas, MassFlow_liq: phase mass flows [kg/h].
alpha_gas: gas void fraction / applied correction multiplier [-].
LockhartMartinelli: liquid-loading parameter X [-].
Fr_gas: gas Froude number at the returned corrected flow [-].
Fr_gas_crit: transition Froude number used [-].
GVF, GMF: consistent gas flow fractions [-].
DR: rho_g/rho_l [-].
iterations: number of fixed-point iterations.
within_JIP_envelope: whether all four dimensionless checks pass.
JIP_envelope_exceeded: tuple of failed check names.
error: None on success, otherwise a failure description.
On failure all numerical fields are NaN, the envelope flag is False
and the exceeded tuple is empty because no range assessment was made.
Raises:
ValueError – If input values are invalid and check_input is True.
RuntimeError – If a non-physical result or non-convergence occurs and check_input
is True.
Notes
The corrected flow determines superficial gas velocity and Fr_gas,
which in turn determines alpha_gas. Fixed-point iteration starts with
the indicated flow and stops at a relative flow change below 1e-10,
with at most 100 iterations. At zero indicated flow all phase flows
are zero; OverRead is the model factor, not an observed 0/0 ratio.
Uses Equations (29)-(30), not the full physical model of Equation (28).
The four JIP checks are diagnostics only; extrapolation is not blocked
unless the prediction is non-physical. Passing them does not establish
meter suitability or validate an uncertainty claim.
Examples
Illustrative inputs only, not measured data or a calibration: