High-Level Interface

PropsSI function

For many users, all that is needed is a simple call to the PropsSI function for pure fluids, pseudo-pure fluids and mixtures. For humid air properties, see Humid air properties. An example using PropsSI:

# Import the PropsSI function
In [1]: from CoolProp.CoolProp import PropsSI

# Saturation temperature of Water at 1 atm in K
In [2]: PropsSI('T','P',101325,'Q',0,'Water')
Out[2]: 373.1242958476844

More information:

All the wrappers wrap this function in exactly the same way.

For pure and pseudo-pure fluids, two state points are required to fix the state. The equations of state are based on \(T\) and \(\rho\) as state variables, so \(T, \rho\) will always be the fastest inputs. \(P,T\) will be a bit slower (3-10 times), and then comes inputs where neither \(T\) nor \(\rho\) are given, like \(p,h\). They will be much slower. If speed is an issue, you can look into table-based interpolation methods using TTSE or bicubic interpolation.

Trivial inputs

In order to obtain trivial inputs that do not depend on the thermodynamic state, in wrappers that support the Props1SI function, you can obtain the trivial parameter (in this case the critical temperature of water) like:

Props1SI(“Tcrit”,”Water”)

In python, the PropsSI function is overloaded to also accept two inputs:

In [3]: import CoolProp.CoolProp as CP

In [4]: CP.PropsSI("Tcrit","Water")
Out[4]: 647.096

In [5]: CP.PropsSI("Tcrit","REFPROP::Water")
Out[5]: 647.096

Furthermore, you can in all languages call the PropsSI function directly using dummy arguments for the other unused parameters:

In [6]: import CoolProp.CoolProp as CP

In [7]: CP.PropsSI("Tcrit","",0,"",0,"Water")
Out[7]: 647.096

PhaseSI function

It can be useful to know what the phase of a given state point is. A high-level function called PhaseSI has been implemented to allow for access to the phase.

In [8]: import CoolProp.CoolProp as CP

In [9]: CP.PhaseSI('P',101325,'Q',0,'Water')
Out[9]: u'twophase'

The phase index (as floating point number) can also be obtained using the PropsSI function. In python you would do:

In [10]: import CoolProp.CoolProp as CP

In [11]: CP.PropsSI('Phase','P',101325,'Q',0,'Water')
Out[11]: 6.0

where you can obtain the integer indices corresponding to the phase flags using the get_phase_index function:

In [12]: import CoolProp.CoolProp as CP

In [13]: CP.get_phase_index('phase_twophase')
Out[13]: 6

# Or for liquid
In [14]: CP.get_phase_index('phase_liquid')
Out[14]: 0

For a given fluid, the phase can be plotted in T-p coordinates:

(Source code, png, .pdf)

../_images/HighLevelAPI-1.png

Partial Derivatives

First Partial Derivatives for Single-phase States

For some applications it can be useful to have access to partial derivatives of thermodynamic properties. A generalized first partial derivative has been implemented into CoolProp, which can be obtained using the PropsSI function by encoding the desired derivative as a string. The format of the string is d(OF)/d(WRT)|CONSTANT which is the same as

\[\left. \frac{\partial OF}{\partial WRT}\right|_{CONSTANT}\]

At the low-level, the CoolProp code calls the function AbstractState::first_partial_deriv(). Refer to the function documentation to see how the generalized derivative works.

Warning

This derivative formulation is currently only valid for homogeneous (single-phase) states. Two phase derivatives are not defined, and are for many combinations, invalid.

Here is an example of calculating the constant pressure specific heat, which is defined by the relation

\[c_p = \left.\frac{\partial h}{\partial T}\right|_{p}\]

and called through python

In [15]: import CoolProp.CoolProp as CP

# c_p using c_p
In [16]: CP.PropsSI('C','P',101325,'T',300,'Water')
Out[16]: 4180.6357765560715

# c_p using derivative
In [17]: CP.PropsSI('d(Hmass)/d(T)|P','P',101325,'T',300,'Water')
Out[17]: 4180.6357765560715

It is also possible to call the derivatives directly using the low-level partial derivatives functionality. The low-level routine is in general faster because it avoids the string parsing.

Second Partial Derivatives for Single-Phase States

In a similar fashion it is possible to evaluate second derivatives. For instance, the derivative of \(c_p\) with respect to mass-based specific enthalpy at constant pressure could be obtained by

In [18]: import CoolProp.CoolProp as CP

# c_p using derivative
In [19]: CP.PropsSI('d(d(Hmass)/d(T)|P)/d(Hmass)|P','P',101325,'T',300,'Water')
Out[19]: -7.767989468924389e-05

where the inner part d(Hmass)/d(T)|P is the definition of \(c_p\).

Warning

This derivative formulation is currently only valid for homogeneous (single-phase) states. Two phase derivatives are not defined, and are for many combinations, invalid.

It is also possible to call the derivatives directly using the low-level partial derivatives functionality. The low-level routine is in general faster because it avoids the string parsing.

First Saturation Derivatives

It is also possible to retrieve the derivatives along the saturation curves using the high-level interface, encoding the desired derivative as a string just like for the single-phase derivatives.

Warning

This derivative formulation is currently only valid for saturated states where the vapor quality is either 0 or 1.

For instance, to calculate the saturation derivative of enthalpy ALONG the saturated vapor curve, you could do:

In [20]: import CoolProp

In [21]: CoolProp.CoolProp.PropsSI('d(Hmolar)/d(T)|sigma','P',101325,'Q',1,'Water')
Out[21]: 28.427795995713694

It is also possible to call the derivatives directly using the low-level partial derivatives functionality. The low-level routine is in general faster because it avoids the string parsing.

Predefined Mixtures

A number of predefined mixtures are included in CoolProp. You can retrieve the list of predefined mixtures by calling get_global_param_string("predefined_mixtures") which will return a comma-separated list of predefined mixtures. In Python, to get the first 6 mixtures, you would do

In [22]: import CoolProp.CoolProp as CP

In [23]: CP.get_global_param_string('predefined_mixtures').split(',')[0:6]
Out[23]: 
[u'Air.mix',
 u'Amarillo.mix',
 u'Ekofisk.mix',
 u'GulfCoast.mix',
 u'GulfCoastGas(NIST1).mix',
 u'HighCO2.mix']

and then to calculate the density of air using the mixture model at 1 atmosphere (=101325 Pa) and 300 K, you could do

In [24]: import CoolProp.CoolProp as CP

In [25]: CP.PropsSI('D','P',101325,'T',300,'Air.mix')
Out[25]: 1.1766922904316655

Exactly the same methodology can be used from other wrappers.

User-Defined Mixtures

When using mixtures in CoolProp, you can specify mixture components and composition by encoding the mixture components and mole fractions by doing something like

In [26]: import CoolProp.CoolProp as CP

In [27]: CP.PropsSI('D','T',300,'P',101325,'HEOS::R32[0.697615]&R125[0.302385]')
Out[27]: 2.986886779635724

You can handle ternary and multi-component mixtures in the same fashion, just add the other components to the fluid string with a & separating components and the fraction of the component in [ and ] brackets

Reference States

Enthalpy and entropy are relative properties! You should always be comparing differences in enthalpy rather than absolute values of the enthalpy or entropy. That said, if can be useful to set the reference state values for enthalpy and entropy to one of a few standard values. This is done by the use of the set_reference_state function in python, or the set_reference_stateS function most everywhere else. For documentation of the underlying C++ function, see CoolProp::set_reference_stateS().

Warning

The changing of the reference state should be part of the initialization of your program, and it is not recommended to change the reference state during the course of making calculations

A number of reference states can be used:

  • IIR: h = 200 kJ/kg, s=1 kJ/kg/K at 0C saturated liquid
  • ASHRAE: h = 0, s = 0 @ -40C saturated liquid
  • NBP: h=0, s=0 for saturated liquid at 1 atmosphere
  • DEF: Go back to the default reference state for the fluid

which can be used like

In [28]: import CoolProp.CoolProp as CP

In [29]: CP.set_reference_state('n-Propane','ASHRAE')

# Should be zero (or very close to it)
In [30]: CP.PropsSI('H', 'T', 233.15, 'Q', 0, 'n-Propane')
Out[30]: 2.928438593838672e-11

# Back to the original value
In [31]: CP.set_reference_state('n-Propane','DEF')

# Should not be zero
In [32]: CP.PropsSI('H', 'T', 233.15, 'Q', 0, 'n-Propane')
Out[32]: 105123.27213761522

Calling REFPROP

If you have the REFPROP library installed, you can call REFPROP in the same way that you call CoolProp, but with REFPROP:: preceding the fluid name. For instance, as in python:

In [33]: import CoolProp.CoolProp as CP

# Using properties from CoolProp to get R410A density
In [34]: CP.PropsSI('D','T',300,'P',101325,'HEOS::R32[0.697615]&R125[0.302385]')
Out[34]: 2.986886779635724

# Using properties from REFPROP to get R410A density
In [35]: CP.PropsSI('D','T',300,'P',101325,'REFPROP::R32[0.697615]&R125[0.302385]')
Out[35]: 2.9868825938765213

C++ Sample Code

#include "CoolProp.h"
#include <iostream>
using namespace CoolProp;
int main()
{
    // First type (slowest, due to most string processing, exposed in DLL)
    std::cout << PropsSI("Dmolar","T",298,"P",1e5,"Propane[0.5]&Ethane[0.5]") << std::endl; // Default backend is HEOS
    std::cout << PropsSI("Dmolar","T",298,"P",1e5,"HEOS::Propane[0.5]&Ethane[0.5]") << std::endl;
    std::cout << PropsSI("Dmolar","T",298,"P",1e5,"REFPROP::Propane[0.5]&Ethane[0.5]") << std::endl;

    std::vector<double> z(2,0.5);
    // Second type (C++ only, a bit faster, allows for vector inputs and outputs)
	std::vector<std::string> fluids; fluids.push_back("Propane"); fluids.push_back("Ethane");
	std::vector<std::string> outputs; outputs.push_back("Dmolar");
	std::vector<double> T(1,298), p(1,1e5);
    std::cout << PropsSImulti(outputs,"T", T, "P", p, "", fluids, z)[0][0] << std::endl; // Default backend is HEOS
    std::cout << PropsSImulti(outputs,"T", T, "P", p, "HEOS", fluids, z)[0][0] << std::endl;
    // Comment me out if REFPROP is not installed
    std::cout << PropsSImulti(outputs,"T", T, "P", p, "REFPROP", fluids, z)[0][0] << std::endl;
    
    return EXIT_SUCCESS;
}

C++ Sample Code Output

40.8269
40.8269
40.8269
40.8269
40.8269
40.8269

Sample Code

In [36]: import CoolProp as CP

In [37]: print CP.__version__
6.1.0

In [38]: print CP.__gitrevision__
7864c2614ce5a0ef972386ee7f39859f0d3f8038

#Import the things you need
In [39]: from CoolProp.CoolProp import PropsSI

# Specific heat (J/kg/K) of 20% ethylene glycol as a function of T
In [40]: PropsSI('C','T',298.15,'P',101325,'INCOMP::MEG-20%')
Out[40]: 3905.2706242925874

# Density of Air at standard atmosphere in kg/m^3
In [41]: PropsSI('D','T',298.15,'P',101325,'Air')
Out[41]: 1.1843184839089664

# Saturation temperature of Water at 1 atm
In [42]: PropsSI('T','P',101325,'Q',0,'Water')
Out[42]: 373.1242958476844

# Saturated vapor density of R134a at 0C
In [43]: PropsSI('H','T',273.15,'Q',1,'R134a')
Out[43]: 398603.45362765493

# Using properties from CoolProp to get R410A density
In [44]: PropsSI('D','T',300,'P',101325,'HEOS::R32[0.697615]&R125[0.302385]')
Out[44]: 2.986886779635724

# Using properties from REFPROP to get R410A density
In [45]: PropsSI('D','T',300,'P',101325,'REFPROP::R32[0.697615]&R125[0.302385]')
Out[45]: 2.9868825938765213

# Check that the same as using pseudo-pure
In [46]: PropsSI('D','T',300,'P',101325,'R410A')
Out[46]: 2.986868076922677

Table of string inputs to PropsSI function

Note

Please note that any parameter that is indicated as a trivial parameter can be obtained from the Props1SI function as shown above in Trivial inputs

Parameter Units Input/Output Trivial Description
DELTA, Delta   IO False Reduced density (rho/rhoc)
DMOLAR, Dmolar mol/m^3 IO False Molar density
D, DMASS, Dmass kg/m^3 IO False Mass density
HMOLAR, Hmolar J/mol IO False Molar specific enthalpy
H, HMASS, Hmass J/kg IO False Mass specific enthalpy
P Pa IO False Pressure
Q mol/mol IO False Mass vapor quality
SMOLAR, Smolar J/mol/K IO False Molar specific entropy
S, SMASS, Smass J/kg/K IO False Mass specific entropy
TAU, Tau   IO False Reciprocal reduced temperature (Tc/T)
T K IO False Temperature
UMOLAR, Umolar J/mol IO False Molar specific internal energy
U, UMASS, Umass J/kg IO False Mass specific internal energy
ACENTRIC, acentric   O True Acentric factor
ALPHA0, alpha0   O False Ideal Helmholtz energy
ALPHAR, alphar   O False Residual Helmholtz energy
A, SPEED_OF_SOUND, speed_of_sound m/s O False Speed of sound
BVIRIAL, Bvirial   O False Second virial coefficient
CONDUCTIVITY, L, conductivity W/m/K O False Thermal conductivity
CP0MASS, Cp0mass J/kg/K O False Ideal gas mass specific constant pressure specific heat
CP0MOLAR, Cp0molar J/mol/K O False Ideal gas molar specific constant pressure specific heat
CPMOLAR, Cpmolar J/mol/K O False Molar specific constant pressure specific heat
CVIRIAL, Cvirial   O False Third virial coefficient
CVMASS, Cvmass, O J/kg/K O False Mass specific constant volume specific heat
CVMOLAR, Cvmolar J/mol/K O False Molar specific constant volume specific heat
C, CPMASS, Cpmass J/kg/K O False Mass specific constant pressure specific heat
DALPHA0_DDELTA_CONSTTAU, dalpha0_ddelta_consttau   O False Derivative of ideal Helmholtz energy with delta
DALPHA0_DTAU_CONSTDELTA, dalpha0_dtau_constdelta   O False Derivative of ideal Helmholtz energy with tau
DALPHAR_DDELTA_CONSTTAU, dalphar_ddelta_consttau   O False Derivative of residual Helmholtz energy with delta
DALPHAR_DTAU_CONSTDELTA, dalphar_dtau_constdelta   O False Derivative of residual Helmholtz energy with tau
DBVIRIAL_DT, dBvirial_dT   O False Derivative of second virial coefficient with respect to T
DCVIRIAL_DT, dCvirial_dT   O False Derivative of third virial coefficient with respect to T
DIPOLE_MOMENT, dipole_moment C m O True Dipole moment
FH   O True Flammability hazard
FRACTION_MAX, fraction_max   O True Fraction (mole, mass, volume) maximum value for incompressible solutions
FRACTION_MIN, fraction_min   O True Fraction (mole, mass, volume) minimum value for incompressible solutions
FUNDAMENTAL_DERIVATIVE_OF_GAS_DYNAMICS, fundamental_derivative_of_gas_dynamics   O False Fundamental derivative of gas dynamics
GAS_CONSTANT, gas_constant J/mol/K O True Molar gas constant
GMOLAR, Gmolar J/mol O False Molar specific Gibbs energy
GWP100   O True 100-year global warming potential
GWP20   O True 20-year global warming potential
GWP500   O True 500-year global warming potential
G, GMASS, Gmass J/kg O False Mass specific Gibbs energy
HELMHOLTZMASS, Helmholtzmass J/kg O False Mass specific Helmholtz energy
HELMHOLTZMOLAR, Helmholtzmolar J/mol O False Molar specific Helmholtz energy
HH   O True Health hazard
ISOBARIC_EXPANSION_COEFFICIENT, isobaric_expansion_coefficient 1/K O False Isobaric expansion coefficient
ISOTHERMAL_COMPRESSIBILITY, isothermal_compressibility 1/Pa O False Isothermal compressibility
I, SURFACE_TENSION, surface_tension N/m O False Surface tension
M, MOLARMASS, MOLAR_MASS, MOLEMASS, molar_mass, molarmass, molemass kg/mol O True Molar mass
ODP   O True Ozone depletion potential
PCRIT, P_CRITICAL, Pcrit, p_critical, pcrit Pa O True Pressure at the critical point
PHASE, Phase   O False Phase index as a float
PH   O True Physical hazard
PIP   O False Phase identification parameter
PMAX, P_MAX, P_max, pmax Pa O True Maximum pressure limit
PMIN, P_MIN, P_min, pmin Pa O True Minimum pressure limit
PRANDTL, Prandtl   O False Prandtl number
PTRIPLE, P_TRIPLE, p_triple, ptriple Pa O True Pressure at the triple point (pure only)
P_REDUCING, p_reducing Pa O True Pressure at the reducing point
RHOCRIT, RHOMASS_CRITICAL, rhocrit, rhomass_critical kg/m^3 O True Mass density at critical point
RHOMASS_REDUCING, rhomass_reducing kg/m^3 O True Mass density at reducing point
RHOMOLAR_CRITICAL, rhomolar_critical mol/m^3 O True Molar density at critical point
RHOMOLAR_REDUCING, rhomolar_reducing mol/m^3 O True Molar density at reducing point
SMOLAR_RESIDUAL, Smolar_residual J/mol/K O False Residual molar entropy (sr/R = tau*dar_dtau-ar)
TCRIT, T_CRITICAL, T_critical, Tcrit K O True Temperature at the critical point
TMAX, T_MAX, T_max, Tmax K O True Maximum temperature limit
TMIN, T_MIN, T_min, Tmin K O True Minimum temperature limit
TTRIPLE, T_TRIPLE, T_triple, Ttriple K O True Temperature at the triple point
T_FREEZE, T_freeze K O True Freezing temperature for incompressible solutions
T_REDUCING, T_reducing K O True Temperature at the reducing point
V, VISCOSITY, viscosity Pa s O False Viscosity
Z   O False Compressibility factor