pvtlib.thermodynamics

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

Z_from_sos_kappa(measured_sos, kappa, ...[, R])

Calculate compressibility factor Z from measured speed of sound, isentropic exponent, molar mass, and temperature.

density_from_sos_kappa(measured_sos, kappa, ...)

Calculate gas density from speed of sound, isentropic exponent and pressure.

energy_rate_balance(h_in, h_out, massflow, ...)

Energy rate balance over control volume

energy_rate_difference(energy_rate_A, ...)

Difference in energy rate between A and B, absolute values

energy_rate_diffperc(energy_rate_A, ...)

Diff percent in energy rate between A and B, absolute values

molar_mass_from_sos_kappa(measured_sos, ...)

Calculate molar mass from measured speed of sound, isentropic exponent, compressibility factor, and temperature.

natural_gas_viscosity_Lee_et_al(T, M, rho)

Calculate natural gas viscosity using Lee et al. correlation.

properties_from_sos_kappa(gas_composition, ...)

Calculate gas properties (density, molar mass, compressibility factor) from measured speed of sound, using the relationship between speed of sound, density, and isentropic exponent.

sos_from_rho_kappa(measured_rho, kappa, ...)

Calculate speed of sound from density, isentropic exponent and pressure.

pvtlib.thermodynamics.energy_rate_balance(h_in, h_out, massflow, vel_in, vel_out)[source]

Energy rate balance over control volume

Parameters:
  • h_in (float) – Enthalpy in [kJ/kg]

  • h_out (float) – Enthalpy out [kJ/kg]

  • massflow (float) – Mass flow [kg/s]

  • vel_in (float) – Velocity in [m/s]

  • vel_out (float) – Velocity out [m/s]

Returns:

energy_rate_change (float) – Energy rate change [kW]

pvtlib.thermodynamics.energy_rate_difference(energy_rate_A, energy_rate_B)[source]

Difference in energy rate between A and B, absolute values

Parameters:
  • energy_rate_A (float) – Energy rate A [kW]

  • energy_rate_B (float) – Energy rate B [kW]

Returns:

energy_rate_difference (float) – Difference between energy rate A and B [kW]

pvtlib.thermodynamics.energy_rate_diffperc(energy_rate_A, energy_rate_B)[source]

Diff percent in energy rate between A and B, absolute values

Parameters:
  • energy_rate_A (float) – Energy rate A [kW]

  • energy_rate_B (float) – Energy rate B [kW]

Returns:

energy_rate_diffperc (float) – Difference percentage between energy rate A and B [%]

pvtlib.thermodynamics.natural_gas_viscosity_Lee_et_al(T, M, rho)[source]

Calculate natural gas viscosity using Lee et al. correlation. Correlation developed for natural gases at pressures between 100 psia (6.9 bar) and 8000 psia (551 bar) and temperatures between 100 and 340 F (37.8 and 171.1 C)

Parameters:
  • T (float) – Temperature [C]

  • M (float) – Molar mass [g/mol]

  • rho (float) – Density [kg/m3]

Returns:

mu (float) – Viscosity [cP]

Notes

The correlation is developed for hydrocarbon natural gases at certain condistions and may not be valid for other gases. However, the simplicity of the correlation makes it a good choice for quick calculations where high accuracy is not required.

Lee, A.L., M.H. Gonzalez, and B.E. Eakin, The Viscosity of Natural Gases. Journal of Petroleum Technology, 1966 https://petrowiki.spe.org/Gas_viscosity

pvtlib.thermodynamics.density_from_sos_kappa(measured_sos, kappa, pressure_bara)[source]

Calculate gas density from speed of sound, isentropic exponent and pressure. The method is described in [1] from the GFMW2024.

Parameters:
  • measured_sos (float) – Measured Speed of Sound [m/s] Measured Speed of Sound [m/s]

  • kappa (float) – Isentropic Exponent calculated by appropriate equation of state [-]

  • pressure_bara (float) – Measured pressure [bara]

Returns:

rho (float) – Gas density from speed of sound, isentropic exponent and pressure [kg/m3]

References

pvtlib.thermodynamics.sos_from_rho_kappa(measured_rho, kappa, pressure_bara)[source]

Calculate speed of sound from density, isentropic exponent and pressure. The method is described in [2] from the GFMW2024.

Parameters:
  • measured_rho (float) – Measured gas density [kg/m3]

  • kappa (float) – Isentropic Exponent calculated by appropriate equation of state [-]

  • pressure_bara (float) – Measured pressure [bara]

Returns:

sos (float) – Speed of sound [m/s]

References

pvtlib.thermodynamics.molar_mass_from_sos_kappa(measured_sos, kappa, Z, temperature_C, R=8.3144621)[source]

Calculate molar mass from measured speed of sound, isentropic exponent, compressibility factor, and temperature. Based on the principles described in [3] from GFMW2024.

Same equation of state must be used to establish both kappa and Z, otherwise it can cause inconsistencies.

Parameters:
  • measured_sos (float) – Measured speed of sound [m/s]

  • kappa (float) – Isentropic exponent calculated by appropriate equation of state [-]

  • Z (float) – Compressibility factor calculated by appropriate equation of state [-]

  • temperature_C (float) – Temperature [C]

  • R (float, optional) – Universal gas constant [J/(mol·K)]. Default is 8.3144621 (GERG-2008).

Returns:

M (float) – Molar mass [kg/kmol]

References

pvtlib.thermodynamics.Z_from_sos_kappa(measured_sos, kappa, molar_mass, temperature_C, R=8.3144621)[source]

Calculate compressibility factor Z from measured speed of sound, isentropic exponent, molar mass, and temperature. Based on the principles described in [4] from GFMW2024.

Parameters:
  • measured_sos (float) – Measured speed of sound [m/s]

  • kappa (float) – Isentropic exponent calculated by appropriate equation of state [-]

  • molar_mass (float) – Molar mass [kg/kmol]

  • temperature_C (float) – Temperature [C]

  • R (float, optional) – Universal gas constant [J/(mol·K)]. Default is 8.3144621 (GERG-2008).

Returns:

Z (float) – Compressibility factor [-]

References

pvtlib.thermodynamics.properties_from_sos_kappa(gas_composition, measured_sos, pressure_bara, temperature_C, EOS='GERG-2008')[source]

Calculate gas properties (density, molar mass, compressibility factor) from measured speed of sound, using the relationship between speed of sound, density, and isentropic exponent.

This function uses an equation of state (EOS) to calculate kappa and Z at the given conditions, then applies these to determine the properties from the measured speed of sound.

Parameters:
  • gas_composition (dict) – Gas composition dictionary with component names as keys and mole percent or mole fraction as values. Uses the same format as AGA8 (C1, N2, CO2, C2, C3, iC4, nC4, iC5, nC5, nC6, etc.)

  • measured_sos (float) – Measured speed of sound [m/s]

  • pressure_bara (float) – Pressure [bara]

  • temperature_C (float) – Temperature [C]

  • EOS (str, optional) – Equation of state to use. Either ‘GERG-2008’ or ‘DETAIL’. Default is ‘GERG-2008’.

Notes

Only valid for single-phase gas conditions. AGA8 does not check for phase state and will produce erroneous results if the operating point is in the two-phase or liquid region.

Returns:

output (dict) –

Dictionary containing:

’rho’ : Mass density calculated from measured speed of sound [kg/m3] ‘mm’ : Molar mass calculated from measured speed of sound [kg/kmol] ‘z’ : Compressibility factor calculated from measured speed of sound [-]

References