REFPROP Tabulation Utility

The Python REFPROP tabulation utility is located under in the bin/ directory in the source code. The name of the utility is cav_tab_tool. This tool is for building necessary liquid, vapor, and saturation input files.

The Python tabulation utility has a functionality for making calls directly to REFPROP 11. This allows for the tool to tabulate as many pressure levels as the user desires. The user specifies the REFPROP material name, the pressure range, temperature range, and the number of data points to use over each range. The user can also pass a flag (--log_p) to uniformly distribute the pressure points in the log-space to ensure that an equal number of points resolve each pressure decade (this is good for large pressure ranges). The tool also supports adaptive temperature spacing (--adaptive_t) that places more points where the data is highly curved and fewer points where the data is nearly linear.

A set of .liq, .vap, and .sat files are generated by the tool, and these are the inputs used by the cavitation_nist module in Stream. Sample calls to the utility for the liquid/vapor files and the saturation files are given below.

There are two modes that the tool can be used in. One is for tabulating properties outside of a two-phase region in the thermodynamic space. The other is for tabulating the saturation curve properties of the liquid and vapor states.

Liquid/Vapor Tabulation

To generate tabulated liquid and vapor files, one should pass the liquidVapor argument to the tabulation tool. The presence of this argument enables a required set of arguments which are described below:

Liquid/Vapor Tabulation Arguments

Argument

Description

t_min

The minimum temperature range value

t_max

The maximum temperature range value

num_t

The number of temperature levels

p_min

The minimum pressure range value

p_max

The maximum pressure range value

num_p

The number of pressure levels

log_p

An optional argument that distributes the pressure levels uniformly across the logarithmic space of the pressure range

adaptive_t

Optional flag to enable adaptive temperature spacing

extend_to_phase_boundary

Optional flag to write a single phase-boundary continuation row when the requested temperature range contains no stable pure-phase state at a pressure level

t_rel_err

Relative error scale for adaptive spacing

t_abs_err

Absolute error scale for adaptive spacing

t_integrated_err

Target normalized integrated error used to stop adaptive refinement

t_min_points

Minimum number of temperature points used by adaptive spacing

t_max_points

Maximum number of temperature points used by adaptive spacing

If the log_p argument is not provided, a linear tabulation in the pressure dimension is performed. The logarithmic spacing enabled by the log_p argument creates a uniform spacing in the logarithmic space. This type of spacing is useful when there is a large variation in the pressure range, as a linear tabulation would result in a low resolution in the low-pressure region of the tabulation. An example command to generate liquid and vapor tabulation files for nitrogen in the temperature range of 65K-300K and pressure range of 50kPa-70MPa is shown below.

<StreamInstallDir>/bin/cav_tab_tool liquidVapor --fluid_name NITROGEN --t_min 65 --t_max 300 --p_min 50000 --p_max 70e6 --log_p --num_p 200 --num_t 200

In the example above, the liquidVapor argument sets the tool into the mode for tabulating .liq and .vap tables. The fluid_name argument must match an available REFPROP FLD file in the REFPROP fluid database. The tabulation levels are done at constant pressure, and so the t_min and t_max arguments are the temperature range over which to tabulate properties. The p_min and p_max arguments are the inclusive bounds of the pressure range over which you want to tabulate data. The log_p argument converts the pressure range into a logarithmic range and distributes points equally in that space and then converts back to pressure levels. This ensures an equal number of pressure levels per decade of pressure. This is sometimes a desirable option. The num_p and num_t arguments are the number of pressure levels to tabulate and the number of temperature levels to tabulate.

For some cryogenic cavitation problems, the requested (P,T) rectangle can cross onto the wrong side of the saturation boundary. A common example is a vapor table with T clipped low enough that no stable pure-vapor state exists above some pressure. In that situation the default behavior is to stop with an error because the requested phase does not exist in the specified temperature range.

If a rectangular table is still needed for cavitation_nist mixture-property lookups, the optional flag --extend_to_phase_boundary can be used. When enabled, the tool writes a single continuation row at pressure levels where the requested phase has no valid temperature window:

  • For subcritical pressures, the continuation row is taken from the saturation boundary for that phase.

  • If a later pressure level still needs continuation after the saturation boundary has terminated at the critical point, the tool reuses the last available continuation row as a fallback.

This option is intended for solver compatibility rather than for creating new thermodynamically exact pure-phase states. It should therefore be used deliberately and documented in the case setup.

An example command for a hydrogen vapor table that needs this continuation behavior is shown below.

<StreamInstallDir>/bin/cav_tab_tool liquidVapor --fluid_name HYDROGEN --t_min 16 --t_max 24 --p_min 20000 --p_max 6.0e6 --log_p --num_p 180 --num_t 160 --adaptive_t --t_rel_err 5e-4 --t_integrated_err 2e-3 --t_min_points 16 --t_max_points 450 --extend_to_phase_boundary

Saturation Tabulation

To generate a tabulated saturation file, one should pass the saturation argument to the tabulation tool. The presence of this argument enables a required set of arguments which are described below:

Saturation Tabulation Arguments

Argument

Description

t_min

The minimum temperature range value

t_max

The maximum temperature range value

num_t

The number of temperature levels

adaptive_t

Optional flag to enable adaptive temperature spacing

t_rel_err

Relative error scale for adaptive spacing

t_abs_err

Absolute error scale for adaptive spacing
t_integrated_err | Target normalized integrated error used
to stop adaptive refinement

t_min_points

Minimum number of temperature points used by adaptive spacing

t_max_points

Maximum number of temperature points used by adaptive spacing

An example command to generate a saturation tabulation file for nitrogen in the temperature range of 65K-300K with 150 tabulation points is shown below.

<StreamInstallDir>/bin/cav_tab_tool saturation --fluid_name NITROGEN --t_min 65 --t_max 300 --num_t 150

In the example above, the saturation argument activates the saturation curve tabulation mode of the script. This mode has fewer arguments than the liquidVapor mode. The temperature range and number of points to include are the only arguments that are necessary. These arguments have the same meanings as they do for the liquidVapor mode of the tabulation tool that was discussed earlier.

Adaptive Temperature Spacing

When --adaptive_t is enabled, the tool refines the temperature grid by repeatedly splitting intervals that contribute the most interpolation error. The interpolation model remains piecewise linear; only the placement of points changes.

The adaptive controls have the following meanings:

t_rel_err

Relative error scale. A larger value is more permissive and usually produces fewer points.

t_abs_err

Absolute error scale. This is useful when a property crosses zero or is very small in magnitude.

t_integrated_err

Dimensionless global error target used to stop refinement. Smaller values add more points; larger values reduce points.

t_min_points

Minimum number of temperature points (safety floor).

t_max_points

Maximum number of temperature points (hard cap).

The integrated error used by the tool is a normalized quantity:

  1. On each interval, evaluate the true property value at the midpoint.

  2. Compare that midpoint value against linear interpolation from interval endpoints.

  3. Normalize the midpoint error by t_abs_err + t_rel_err*scale, where scale is based on local property magnitude.

  4. Use the largest normalized error across tabulated outputs for that interval.

  5. Weight by interval length and sum over the full temperature range.

This produces a single dimensionless metric (the “integrated error”) that reflects both local interpolation quality and how much of the range is affected.

Practical tuning guidance:

  • Start with --t_rel_err 0.02 --t_integrated_err 0.05 --t_min_points 6 --t_max_points 250.

  • If files are too large, increase t_rel_err and/or t_integrated_err, or lower t_max_points.

  • If interpolation quality is insufficient, decrease t_rel_err and/or t_integrated_err, or raise t_max_points.

  • If t_max_points is reached, the tool reports a warning and stops refinement at the cap.

For current cavitation_nist code, saturation interpolation supports non-uniform temperature spacing, so adaptive spacing can be used for .sat files as well as .liq/.vap.

Using Cavitation Tabulation Tool

One must have version 11 of the REFPROP software to use the cavitation tabulation tool. A short tutorial on how to install the dependencies for the cavitation tabulation tool is presented below.

  1. Download the REFPROP 11 software using the NIST downloader. This must be done on a Windows machine. The software will be downloaded into a directory named REFPROP.

  2. Copy the REFPROP directory over to a Linux machine. The software can be put in a directory such as /home/<User>/software/refprop, where <User> would be your username on the machine). Note: do not rename the REFPROP source code directory because that may cause issues. For example, the path should look as follows: /home/<User>/software/refprop/REFPROP

  3. Compile a local version of REFPROP on your Linux machine

    1. Do a recursive clone of the following repository: git clone --recursive https://github.com/usnistgov/REFPROP-cmake.git

    2. Go to the root of the cloned repository: cd REFPROP-cmake

    3. Create a build directory: mkdir build

    4. Change to the build directory: cd build

    5. Run cmake to configure the build: cmake .. -DCMAKE_BUILD_TYPE=Release -DREFPROP_FORTRAN_PATH=/home/<User>/software/refprop/REFPROP/FORTRAN

    6. Build the project: cmake --build .

  4. Once the build is complete, a librefprop.so file should be found in the build directory. This shared library contains all the REFPROP functions that the Python wrapper will call. Move this file to the REFPROP directory created in step 2.

    1. Move the shared library file: mv librefprop.so /home/<User>/software/refprop/REFPROP

  5. Set the environment variable RPPREFIX to point to the REFPROP directory that contains the shared library file.

    1. Add the following line to your .bashrc file: export RPPREFIX=/home/<User>/software/refprop/REFPROP.

    2. Make sure to source your .bashrc file after adding this line: source ~/.bashrc.

  6. Clone the REFPROP wrappers directory into the /home/<User>/software/refprop directory using the following command: git clone https://github.com/usnistgov/REFPROP-wrappers

  7. Create a Python3 environment with the REFPROP interface installed. This will provide a portable and dependable Python environment for running the tabulation tool. Go to your refprop directory and follow the steps below:

    1. Create a virtual environment: python3 -m venv refprop-env

    2. Activate the environment: source refprop-env/bin/activate

    3. Install numpy: pip install numpy

    4. Navigate to the REFPROP wrappers directory: cd /home/<User>/software/refprop/REFPROP-wrappers/wrappers/python/ctypes

    5. Install the python wrapper into the environment: python setup.py install

    6. To leave the virtual environment type: deactivate

One you are in the python environment, you can run the tabulation script and it should execute using calls to the REFPROP library.