pvtlib.fluid_mechanics

MIT License

Copyright (c) 2025 Christian Hågenvik

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.

Functions

GMF_to_GVF(GMF, rho_gas, rho_liquid)

Convert from gas mass fraction (GMF) to gas volume fraction (GVF).

GVF_to_GMF(GVF, rho_gas, rho_liquid)

Convert from gas volume fraction (GVF) to gas mass fraction (GMF).

GVF_to_lockhart_martinelli(GVF, ...)

Calculate liquid loading X from the flowing gas volume fraction.

contaminant_volume_percent_from_mixed_density(...)

Calculate the fraction of contaminant phase in a two-phase system, based on a measured total density and the densities of the two phases.

critical_velocity_for_uniform_wio_dispersion_horizontal(...)

Calculate critical (minimum) velocity for maintaining a dispersion degree G, based on NFOGM HANDBOOK of Water Fraction Metering [6].

critical_velocity_for_uniform_wio_dispersion_vertical(...)

Calculate the critical (minimum) velocity Vc which is required to maintain a homogeneous flow in a vertical, or inclined pipe, based on NFOGM HANDBOOK of Water Fraction Metering [7].

densimetric_froude_number(v, D, rho_phase, ...)

Calculate the lighter phase's density-weighted Froude number.

dominant_phase_corrected_density(...)

Use measured total density (for example from a coriolis meter) to estimate a "measured" density of the dominant phase corrected for contamination, i.e. the density with the contaminant phase removed.

froude_number(v, D)

Calculate the ratio of flow velocity to the gravity-wave velocity scale.

gas_liquid_density_ratio(rho_gas, rho_liquid)

Calculate the gas-to-liquid density ratio at the same conditions.

gas_liquid_interfacial_tension_linear_mixing(...)

Estimate gas-liquid interfacial tension by simplified volume-split weighting.

liquid_holdup_from_density(measured_density, ...)

Based on a measured mix density and liquid and gas densities, calculate liquid hold-up.

lockhart_martinelli_parameter(...)

Calculate the Lockhart-Martinelli parameter X.

lockhart_martinelli_to_GVF(X, ...)

Convert liquid loading X to the flowing gas volume fraction.

mass_percent_to_volume_percent(...)

Convert from mass percentage to volume percentage The EOS density can be calculated from an equation of state, or from another source, as long as it represents the density of the dominant and contaminant phases.

mixture_density_homogeneous(...)

Calculate the density of a mixture of fluids or components assuming a homogeneous mixture (no slip between phases/components and no interaction between phases/components).

ohnesorge_number(mu, rho, D, surface_tension)

Calculate the viscous-to-inertial/capillary scale ratio.

reynolds_number(rho, v, D, mu)

Calculate Reynolds number for a fluid flow.

superficial_velocity(Q_phase, D)

Calculates superficial velocity of a phase

volume_percent_to_mass_percent(...)

Convert from volume percentage to mass percentage The EOS density can be calculated from an equation of state, or from another source, as long as it represents the density of the dominant and contaminant phases.

pvtlib.fluid_mechanics.reynolds_number(rho, v, D, mu)[source]

Calculate Reynolds number for a fluid flow.

Parameters:
  • rho (float) – Fluid density [kg/m3].

  • v (float) – Fluid velocity [m/s].

  • D (float) – Inner pipe diameter [m].

  • mu (float) – Fluid dynamic viscosity [Pa⋅s].

Returns:

Re (float) – Reynolds number [-].

Return type:

float

pvtlib.fluid_mechanics.superficial_velocity(Q_phase, D)[source]

Calculates superficial velocity of a phase

Parameters:
  • Q_phase (float) – Volume flow rate of the phase [m3/h].

  • D (float) – Inner pipe diameter [m].

Returns:

Us (float) – Superficial velcotiy of the phase [m/s]

pvtlib.fluid_mechanics.mixture_density_homogeneous(volume_fractions, densities)[source]

Calculate the density of a mixture of fluids or components assuming a homogeneous mixture (no slip between phases/components and no interaction between phases/components). The volume fractions do not need to sum to 1, as they will be normalized in the function. This allows for easy use of volume fractions given in percentage (0-100 %) or with volume flowrates as direct input.

Parameters:
  • volume_fractions (list or np.ndarray of float) – Volume fractions of each phase [-].

  • densities (list or np.ndarray of float) – Densities of each phase [kg/m3].

Returns:

rho_mixture (float) – Mixture density [kg/m3].

pvtlib.fluid_mechanics.GMF_to_GVF(GMF, rho_gas, rho_liquid)[source]

Convert from gas mass fraction (GMF) to gas volume fraction (GVF).

Parameters:
  • GMF (float) – Gas mass fraction [-].

  • rho_gas (float) – Gas density [kg/m3].

  • rho_liquid (float) – Liquid density [kg/m3].

Returns:

GVF (float) – Gas volume fraction [-]. NaN for non-finite or non-physical input.

pvtlib.fluid_mechanics.GVF_to_GMF(GVF, rho_gas, rho_liquid)[source]

Convert from gas volume fraction (GVF) to gas mass fraction (GMF).

Parameters:
  • GVF (float) – Gas volume fraction [-].

  • rho_gas (float) – Gas density [kg/m3].

  • rho_liquid (float) – Liquid density [kg/m3].

Returns:

GMF (float) – Gas mass fraction [-]. NaN for non-finite or non-physical input.

pvtlib.fluid_mechanics.lockhart_martinelli_parameter(mass_flow_rate_liquid, mass_flow_rate_gas, density_liquid, density_gas)[source]

Calculate the Lockhart-Martinelli parameter X.

Note: The units for mass flow rates and densities must be consistent between phases, but do not need to be SI units (e.g., both in kg/h and both in kg/m3 are valid).

Parameters:
  • mass_flow_rate_liquid (float) – Mass flow rate of liquid phase [kg/h or kg/s].

  • mass_flow_rate_gas (float) – Mass flow rate of gas phase [kg/h or kg/s].

  • density_liquid (float) – Density of liquid phase [kg/m3].

  • density_gas (float) – Density of gas phase [kg/m3].

Returns:

X (float) – Lockhart-Martinelli parameter [-]. Zero for zero liquid flow. NaN for non-finite input, negative liquid flow, non-positive gas flow or non-positive densities.

pvtlib.fluid_mechanics.froude_number(v, D)[source]

Calculate the ratio of flow velocity to the gravity-wave velocity scale.

Parameters:
  • v (float) – Non-negative characteristic velocity [m/s].

  • D (float) – Positive characteristic length; inner diameter for pipe flow [m].

Returns:

Fr (float) – Froude number, v / sqrt(g * D) [-]. NaN for non-finite or non-physical input. Zero velocity gives zero.

Notes

Uses the standard acceleration of free fall, g_n = 9.806 65 m/s2 exactly [1]. This is the ordinary Froude number, not the density-weighted Froude number used in gas-liquid flow correlations.

References

pvtlib.fluid_mechanics.densimetric_froude_number(v, D, rho_phase, rho_other)[source]

Calculate the lighter phase’s density-weighted Froude number.

Compares inertia of the lighter phase with the buoyancy velocity scale. The same definition is used by the wet-gas venturi and USM corrections.

Parameters:
  • v (float) – Non-negative superficial velocity of the lighter phase [m/s].

  • D (float) – Positive inner pipe diameter [m].

  • rho_phase (float) – Positive density of the lighter phase, normally gas [kg/m3].

  • rho_other (float) – Density of the heavier phase, greater than rho_phase [kg/m3].

Returns:

Fr (float) – v / sqrt(g * D) * sqrt(rho_phase / (rho_other - rho_phase)) [-]. NaN for non-finite or non-physical input.

Notes

Uses the standard acceleration of free fall, g_n = 9.806 65 m/s2 exactly [4]. The velocity is superficial, not the in-situ phase velocity. This definition does not cover a phase denser than its surroundings; no absolute density difference is substituted.

References

pvtlib.fluid_mechanics.ohnesorge_number(mu, rho, D, surface_tension)[source]

Calculate the viscous-to-inertial/capillary scale ratio.

Parameters:
  • mu (float) – Positive dynamic viscosity of the phase [Pa.s].

  • rho (float) – Positive density of the same phase [kg/m3].

  • D (float) – Positive characteristic length [m].

  • surface_tension (float) – Positive interfacial tension [N/m].

Returns:

Oh (float) – Ohnesorge number, mu / sqrt(rho * surface_tension * D) [-]. NaN for non-finite or non-physical input.

Notes

Independent of velocity. Equals sqrt(We) / Re when We and Re use the same properties, length and non-zero velocity. Use gas properties and inner pipe diameter for the Van Putten critical-Froude correlation.

pvtlib.fluid_mechanics.gas_liquid_density_ratio(rho_gas, rho_liquid)[source]

Calculate the gas-to-liquid density ratio at the same conditions.

Parameters:
  • rho_gas (float) – Positive gas density [kg/m3].

  • rho_liquid (float) – Positive liquid density [kg/m3].

Returns:

DR (float) – rho_gas / rho_liquid [-]. NaN for non-finite or non-positive densities. No pressure is inferred from this ratio.

pvtlib.fluid_mechanics.GVF_to_lockhart_martinelli(GVF, density_liquid, density_gas)[source]

Calculate liquid loading X from the flowing gas volume fraction.

Parameters:
  • GVF (float) – Q_gas / (Q_gas + Q_liquid) at line conditions [-], in (0, 1]. This is a flow fraction, not the in-situ gas void fraction.

  • density_liquid (float) – Positive liquid density at line conditions [kg/m3].

  • density_gas (float) – Positive gas density at the same conditions [kg/m3].

Returns:

X (float) – Lockhart-Martinelli parameter [-]. Zero for dry gas (GVF = 1). NaN for non-finite or non-physical input.

Notes

Equivalent to ((1 - GVF) / GVF) * sqrt(density_liquid / density_gas). Reuses the mass-flow definition rather than maintaining a second X correlation for volume-based meters.

See also

lockhart_martinelli_parameter

Mass-flow definition of X.

lockhart_martinelli_to_GVF

Inverse conversion.

pvtlib.fluid_mechanics.lockhart_martinelli_to_GVF(X, density_liquid, density_gas)[source]

Convert liquid loading X to the flowing gas volume fraction.

Parameters:
  • X (float) – Non-negative Lockhart-Martinelli parameter [-].

  • density_liquid (float) – Positive liquid density at line conditions [kg/m3].

  • density_gas (float) – Positive gas density at the same conditions [kg/m3].

Returns:

GVF (float) – 1 / (1 + X * sqrt(density_gas / density_liquid)) [-]. NaN for non-finite or non-physical input.

See also

GVF_to_lockhart_martinelli

Forward conversion.

pvtlib.fluid_mechanics.gas_liquid_interfacial_tension_linear_mixing(WLR, surface_tension_oil, surface_tension_water)[source]

Estimate gas-liquid interfacial tension by simplified volume-split weighting.

Parameters:
  • WLR (float) – Water volume flow / total oil-water volume flow [-], in [0, 1]. Volume flows must refer to the same line conditions.

  • surface_tension_oil (float) – Positive gas-oil interfacial tension at line conditions [N/m].

  • surface_tension_water (float) – Positive gas-water interfacial tension at the same conditions [N/m].

Returns:

surface_tension (float) – Approximate gas-liquid interfacial tension [N/m], weighted by the oil-water liquid volumetric-flow split. NaN for non-finite or non-physical input.

Notes

This is a simplified linear mixing rule, not a general method for calculating the interfacial tension of an oil-water mixture against gas. It implements the approximation in Equation (43) of [1]:

surface_tension = (1 - WLR) * surface_tension_oil + WLR * surface_tension_water

The weights are the oil and water fractions of the total liquid volume flow: 1 - WLR and WLR, respectively. They are not mass fractions or in-situ liquid holdups. The rule assumes that the two supplied gas-liquid interfacial tensions can be combined linearly; applicability to the actual fluid system must be assessed separately. Both supplied tensions must be positive, even at the pure-component endpoints.

References

pvtlib.fluid_mechanics.liquid_holdup_from_density(measured_density, liquid_density, gas_density)[source]

Based on a measured mix density and liquid and gas densities, calculate liquid hold-up. Assuming no slip between gas and liquid.

If measured density is higher then liquid density, return 1 in liquid hold-up. If measured density is lower then gas density, return 0 in liquid hold-up.

Parameters:
  • measured_density (float) – Measured mix density [kg/m3]

  • liquid_density (float) – Liquid density [kg/m3]

  • gas_density (float) – Gas density [kg/m3]

Returns:

liquid holdup, float – Liquid holdup fraction, assuming no slip [-].

pvtlib.fluid_mechanics.critical_velocity_for_uniform_wio_dispersion_horizontal(ST_oil_aq, rho_o, rho_aq, Visc_o, D, K1=2.02, G=10)[source]

Calculate critical (minimum) velocity for maintaining a dispersion degree G, based on NFOGM HANDBOOK of Water Fraction Metering [6].

The value G = 10 gives a concentration ratio 0.9, and is recommended by ISO 3171. This corresponds to ±5 % deviation from the mean concentration and it is in practise considered as a homogeneous mixture.

The numerical constant K1 depends on the unit system being used, and the default K1 corresponds to SI units, which is being used in this function. The function will also work for field SI units (K1 = 0.5), but the units will no longer be valid.

The method described here should be used with care since it is based on a simplified concentration model, as well as other simplified and semi-theoretical models. The water concentration model is only valid for small water volume fractions, i.e. less than approximately 10–15 % water in oil.

Equation and info from NFOGM HANDBOOK of Water Fraction Metering (Revision 2, December 2004), chapter 5.1, Equation 2.

Parameters:
  • ST_oil_aq (float) – Interfacial (surface) tension between oil and water [N/m].

  • rho_o (float) – Oil density [kg/m3].

  • rho_aq (float) – Aqueous density [kg/m3].

  • Visc_o (float) – Oil viscosity [Pa⋅s].

  • D (float) – Inner pipe diameter [m].

  • K1 (float) – Constant depending on unit system (SI or field units) The default is 2.02 which corresponds to SI units.

  • G (float, optional) – Parameter defining the degree of dispersion (usually G = 10). The default is 10.

Returns:

Vc (float) – Critical (minimum) velocity for maintaining a dispersion degree G [m/s].

References

pvtlib.fluid_mechanics.critical_velocity_for_uniform_wio_dispersion_vertical(beta, ST_oil_aq, rho_o, rho_aq, Visc_o, D, K2=2910)[source]

Calculate the critical (minimum) velocity Vc which is required to maintain a homogeneous flow in a vertical, or inclined pipe, based on NFOGM HANDBOOK of Water Fraction Metering [7]. The numerical constant K2 depends on the unit system being used and the default K2 corresponds to SI units, which is being used in this function. The function will also work for field SI units (K2 = 550), but the units will no longer be valid.

This model is valid for vertical and inclined pipe flow (45° - 90° from the horizontal plane). Furthermore, the model is valid for low to moderate high water concentrations, i.e. 20 – 25 %.

Equation and info from NFOGM HANDBOOK of Water Fraction Metering (Revision 2, December 2004), chapter 5.1, Equation 9.

Parameters:
  • beta (float) – Volumetric water fraction in per cent [vol%].

  • ST_oil_aq (float) – Interfacial (surface) tension between oil and water [N/m].

  • rho_o (float) – Oil density [kg/m3].

  • rho_aq (float) – Aqueous density [kg/m3].

  • Visc_o (float) – Oil viscosity [Pa⋅s].

  • D (float) – Inner pipe diameter [m].

  • K2 (float) – Constant depending on unit system (SI or field units) The default is 2910 which corresponds to SI units.

Returns:

Vc (float) – Critical (minimum) velocity Vc which is required to maintain a homogeneous flow in a vertical, or inclined pipe [m/s].

References

pvtlib.fluid_mechanics.volume_percent_to_mass_percent(ContaminantVolP, DominantPhase_EOS_density, ContaminantPhase_EOS_density)[source]

Convert from volume percentage to mass percentage The EOS density can be calculated from an equation of state, or from another source, as long as it represents the density of the dominant and contaminant phases.

Parameters:
  • ContaminantVolP (float) – Volume percentage, contaminant phase [%]

  • DominantPhase_EOS_density (float) – Calculated denstiy from equation of state, dominant phase [kg/m3]

  • ContaminantPhase_EOS_density (float) – Calculated denstiy from equation of state, contaminant phase [kg/m3]

Returns:

ContaminantMassP (float) – Mass percentage, contaminant phase [%]

pvtlib.fluid_mechanics.mass_percent_to_volume_percent(ContaminantMassP, DominantPhase_EOS_density, ContaminantPhase_EOS_density)[source]

Convert from mass percentage to volume percentage The EOS density can be calculated from an equation of state, or from another source, as long as it represents the density of the dominant and contaminant phases.

Parameters:
  • ContaminantMassP (float) – Mass percentage, contaminant phase [%]

  • DominantPhase_EOS_density (float) – Calculated denstiy from equation of state, dominant phase [kg/m3]

  • ContaminantPhase_EOS_density (kg/m3) – Calculated denstiy from equation of state, contaminant phase [kg/m3]

Returns:

ContaminantVolP (float) – Volume percentage, contaminant phase [%]

pvtlib.fluid_mechanics.dominant_phase_corrected_density(measured_total_density, ContaminantVolP, ContaminantPhase_EOS_density)[source]

Use measured total density (for example from a coriolis meter) to estimate a “measured” density of the dominant phase corrected for contamination, i.e. the density with the contaminant phase removed. The EOS density can be calculated from an equation of state, or from another source, as long as it represents the density of the dominant and contaminant phases.

If ContaminantVolP is zero, the function returns the measured_total_density.

Example of usage: What is the density of the oil phase if the measured density is 800 kg/m3 and the water fraction is 1vol%?

Parameters:
  • measured_total_density (float) – Measured total density, i.e. density including both dominant and contaminant phase [kg/m3]

  • ContaminantVolP (float) – Volume percentage, contaminant phase [%]

  • ContaminantPhase_EOS_density (float) – Calculated denstiy from equation of state, contaminant phase [kg/m3]

Returns:

Density_dominant_corr (float) – Estimated density of the dominant phase, based on measured density, corrected for contaminant phase [kg/m3] If ContaminantVolP is zero, returns measured_total_density.

pvtlib.fluid_mechanics.contaminant_volume_percent_from_mixed_density(measured_total_density, DominantPhase_EOS_density, ContaminantPhase_EOS_density)[source]

Calculate the fraction of contaminant phase in a two-phase system, based on a measured total density and the densities of the two phases. The EOS density can be calculated from an equation of state, or from another source, as long as it represents the density of the dominant and contaminant phases.

Example of usage: What is the water fraction if the measured density is 850 kg/m3, the oil density is 800 kg/m3 and the water density is 1000 kg/m3?

Parameters:
  • measured_total_density (float) – Measured total density, i.e. density including both dominant and contaminant phase [kg/m3]

  • DominantPhase_EOS_density (float) – Calculated denstiy from equation of state, dominant phase [kg/m3]

  • ContaminantPhase_EOS_density (float) – Calculated denstiy from equation of state, contaminant phase [kg/m3]

Returns:

ContaminantVolP (float) – Volume percentage, contaminant phase [%]