Appendix: tabulated_data Utility

The tabulated_data utility generates tabulated equation-of-state data, and when the selected source supports it, tabulated viscosity and conductivity data. The output is an EoSTables/<table_name>/ directory that can be used by tabular-EoS cases.

Use this utility when a species in a real-fluid or tabular-EoS case should use property tables instead of an analytic ideal-gas or real-fluid equation of state. Most users should start with refprop mode, which can use CoolProp’s HEOS backend without a REFPROP installation, or an installed REFPROP backend when that is available. The utility can also:

• sample a pure species from a Cantera mechanism;

• import an existing pressure-temperature fitTable containing density and enthalpy when no CoolProp/REFPROP or Cantera source is available.

Note: Do not use this utility for the cavitation-NIST .liq, .vap, and .sat table workflow. That workflow uses cav_tab_tool.

Basic workflow:

1. Choose a source mode. For most pure fluids, use refprop mode with --backend HEOS or --backend REFPROP.

2. Generate one table directory per tabulated species.

3. Place the resulting EoSTables/ directory in the directory containing case.vars or in the run directory used to launch Stream.

4. Set each tabulated species in the .mdl file to eos=Table(name="<table_name>").

5. Load and select the tabular-EoS runtime path in case.vars.

Quick Stream Setup

For a generic tabulated-EoS case, generate one table per tabulated species and make the table name match the eos=Table(name="...") name used in the chemistry model file. Explicit --table_name values make this easier to read and maintain.

For example, to prepare helium and nitrogen tables for HeN2.mdl:

tabulated_data refprop --backend HEOS --fluid Helium --table_name He \
  --pmin 1.0e5 --pmax 2.0e6 --tmin 20 --tmax 400 \
  --update_mdl HeN2.mdl --mdl_species He

tabulated_data refprop --backend HEOS --fluid Nitrogen --table_name N2 \
  --pmin 1.0e5 --pmax 2.0e6 --tmin 20 --tmax 400 \
  --update_mdl HeN2.mdl --mdl_species N2

The --update_mdl and --mdl_species options are optional, but they are the least error-prone way to keep the generated table name and the .mdl species entry synchronized.

Then check that your run control file (*.vars) contains the tabular-EoS setup:

loadModule: tabularEoS
eos_type: fluid
chemistry_model: HeN2
transport_model: tabularEoS

and that HeN2.mdl references the generated table names:

species = {
  He: <..., eos=Table(name="He"), ...> ;
  N2: <..., eos=Table(name="N2"), ...> ;
} ;

Keep the generated EoSTables/ directory in the directory containing case.vars or in the run directory used to launch Stream.

Do not load realFluid at the same time as tabularEoS for this workflow. The tabularEoS module already registers the real-fluid EOS implementation.

For the generic loadModule: tabularEoS workflow, the same runtime module also owns the optional tabular viscosity and conductivity readers selected by transport_model: tabularEoS. This is an implementation detail of the current runtime module: in this context, “tabular transport” means viscosity and thermal conductivity only. Use a source mode that writes those two tables, such as refprop or cantera without --no_transport. The fit_table source imports density and enthalpy from the input file; by default it writes EoS correction tables only. Use --constant_viscosity and --constant_conductivity for constant transport tables, or --fit_transport_from_table when the input file also contains appended viscosity and conductivity grids. Use refprop/cantera for source-derived viscosity and conductivity.

Species diffusion coefficients are not part of the supported EoSTables format, and adding extra diffusion files to the table directory will not make Stream read them. Species diffusion is controlled by diffusion_model. For the common transport_model: tabularEoS setup, either leave diffusion_model at default or set diffusion_model: laminarSchmidt explicitly; both routes use tabulated laminar viscosity with laminarSchmidtNumber. Use other diffusion_model values only when the case is intentionally using separate diffusion-data sources, such as diffusion_model: chemkin with Chemkin-format transport data.

Some upstream documentation describes this as mixing tabular transport with transportDB. In Stream, this is a file-level fallback inside transport_model: tabularEoS, not a different transport_model setting. If a chemistry model contains both eos=Table(name="...") species and ordinary non-table species, the tabularEoS transport reader uses EoSTables viscosity and conductivity for the table species and searches the run-directory transport/ folder for transportDB-style *_vis.dat and *_con.dat files for the non-table species. It still does not read diffusion coefficients from EoSTables.

Compared to the transportDB workflow:

• tabularEoS uses EoSTables/<table_name>/ and per-species eos=Table(name="...") entries in the .mdl file.

• transportDB uses a transport/ folder and does not require eos=Table(...) in the .mdl file.

• transport_model: tabularEoS replaces the active viscosity/conductivity model in the generic workflow. Keep this setting when using table species. For non-table species in the same model, the tabularEoS reader can use local transportDB-style transport/*_vis.dat and transport/*_con.dat files.

• Species diffusion still follows diffusion_model; with diffusion_model: default this falls back to laminarSchmidt and does not read diffusion-coefficient files from EoSTables.

• transport_model: module in flamelet or other module-driven cases is a separate mechanism and should not be confused with generic transport_model: tabularEoS.

What The Utility Produces

For a given source mode and set of options, the utility writes:

EoSTables/<table_name>/

The directory always contains:

• info.desc (table metadata and file references)

• omega.fit

• EoS correction surfaces:

  • kd-tree format: densityCorrect_*.kd, energyCorrect_*.kd

  • fixed-table format, when requested: densityCorrect_*.fixedTable, energyCorrect_*.fixedTable

Depending on source mode and flags, the directory can also contain:

• viscosity_*.kd

• conductivity_*.kd

• entropy_*.kd

• TlimitHi.fit

• TlimitLo.fit

Generated tables are only appropriate over the pressure and temperature range sampled by the command. Choose --pmin, --pmax, --tmin, and --tmax so they cover the expected states in the simulation.

Source Modes And Outputs

Mode	Use When	Generated By Default	Optional Or Not Generated
refprop	You want pure-fluid properties from CoolProp HEOS or an installed REFPROP backend.	EoS corrections, viscosity, conductivity, omega.fit, and automatic T-limit fits.	--include_entropy adds entropy. --no_transport omits viscosity and conductivity.
cantera	You have a Cantera YAML mechanism and want a pure-species table.	EoS corrections, viscosity, conductivity, and omega.fit.	--include_entropy adds entropy. --no_transport omits viscosity and conductivity.
fit_table	Advanced import path for an existing fitTable file containing density and enthalpy.	EoS corrections and omega.fit.	--constant_viscosity and --constant_conductivity add constant transport tables. --fit_transport_from_table reads appended transport grids. Entropy and source-derived T-limit fits are not generated.

Invocation

General CLI form:

tabulated_data [--log_level {DEBUG,INFO,WARNING,ERROR}] {refprop,cantera,fit_table} ...

Source modes:

Choosing A Source Mode

Mode	Use When	Can Generate	First Command Shape
refprop	You want pure-fluid data from CoolProp HEOS or an installed REFPROP backend.	EoS corrections; viscosity/conductivity unless --no_transport is used; optional entropy and T-limit fits.	tabulated_data refprop --backend HEOS --fluid Water ...
cantera	You have a Cantera YAML mechanism and want a pure-species table.	EoS corrections; viscosity/conductivity unless --no_transport is used; optional entropy.	tabulated_data cantera mechanism.yaml --species O2 ...
fit_table	You already have a fitTable file containing density and enthalpy and no property-package source is available.	EoS corrections. Add constant transport flags or --fit_transport_from_table when the case needs complete tabular-EoS transport files.	tabulated_data fit_table oxygen.fitTable ...

Dependencies are listed under Dependencies And Troubleshooting.

Required Inputs By Mode

Required Inputs

Mode	Required Inputs	Notes
refprop	--fluid, --pmin, --pmax, --tmin, --tmax	Requires CoolProp Python package. Backend defaults to HEOS; choose --backend REFPROP when REFPROP is installed.
cantera	mechanism, --species, --pmin, --pmax, --tmin, --tmax	Requires Python Cantera package.
fit_table	fit_table positional input file	Pressure/temperature bounds are optional and default to fit file limits.

Examples

CoolProp HEOS pure-fluid table:

tabulated_data refprop --backend HEOS --fluid Water \
  --pmin 1.0e5 --pmax 2.0e7 --tmin 280 --tmax 600 \
  --liquid_bias --output_mode kd

Cantera species tabulation:

tabulated_data cantera mechanism.yaml --species O2 \
  --pmin 1.0e5 --pmax 5.0e6 --tmin 250 --tmax 3000 \
  --table_name O2_table --output_mode both --info_mode kd

Common Flags

These options are available for all source modes unless noted otherwise.

Common Flags

Flag	Default	Description
--output_root	EoSTables	Root output directory.
--output_mode {kd,fixed,both}	kd	Write kd files, fixed tables, or both.
--info_mode {kd,fixed}	kd	When --output_mode both is used, selects which set info.desc references.
--omega_mode {constant,fitfile,auto}	mode-dependent	constant writes constant omega.fit; fitfile copies a user file; auto uses source-provided fit data.
--omega_constant	1.0	Constant omega value when --omega_mode constant.
--omega_fit_file	none	Existing fit file to copy when --omega_mode fitfile.
--omega_intervals	128	Interval count for generated omega fit.
--tlimit_hi_fit	none	Optional explicit high-T limit fit file to copy as TlimitHi.fit.
--tlimit_lo_fit	none	Optional explicit low-T limit fit file to copy as TlimitLo.fit.
--update_mdl	none	Optional existing .mdl file to patch after table generation.
--mdl_species	none	Species entry inside --update_mdl that should be switched to eos=Table(name="<table_name>").
--depth_x, --depth_y	5, 5	Base grid depth in each axis (cells = \(2^{depth}\)).
--num_p, --num_t	none	Explicit pressure/temperature cell counts; overrides depth for that axis.
--adaptive_grid	off	Enables adaptive depth selection within specified min/max depths.
--min_depth_x, --min_depth_y	2, 2	Minimum adaptive depths.
--adapt_l1_tol	1e-5	Adaptive mean relative error target.
--adapt_l8_tol	1e-4	Adaptive max relative error target.
--adapt_ref_floor	1e-12	Small floor in adaptive relative error denominator.
--adapt_max_iters	32	Maximum adaptive refinement iterations.
--log_p / --linear_p	--log_p	Pressure axis scaling for fitting grid.
--log_t / --linear_t	--log_t	Temperature axis scaling for fitting grid.
--baseline_mode	mode-dependent	Baseline correction model (zero/ideal/auto depending on source mode).
--R, --b, --r1, --n, --hf	0	Baseline coefficients used when --baseline_mode zero.

Notes:

• --adaptive_grid cannot be combined with --num_p or --num_t.

• kd output requires power-of-two pressure and temperature cell counts. The depth options produce power-of-two counts automatically. If you use --num_p or --num_t with --output_mode kd or both, choose values such as 16, 32, or 64.

• fixed output requires the default logarithmic pressure and temperature axes. Do not combine --output_mode fixed or both with --linear_p or --linear_t.

• --omega_mode auto requires the source adapter to provide omega fit data. This is currently provided by the refprop source path.

• --mdl_species is required when --update_mdl is used.

refprop Mode

Purpose: sample pure-fluid properties with CoolProp backends and generate tabulated outputs. Use --backend HEOS for the built-in CoolProp backend. Use --backend REFPROP only when REFPROP is installed and available to CoolProp.

Additional flags:

refprop Mode Flags

Flag	Default	Description
--fluid	required	Fluid name (for example Water, Nitrogen).
--backend {REFPROP,HEOS}	HEOS	CoolProp backend prefix.
--table_name	auto-generated	Output table directory name. The default includes backend, fluid, sampling mode, and baseline mode, for example heos_water_full_bauto.
--pmin, --pmax	required	Pressure bounds [Pa].
--tmin, --tmax	required	Temperature bounds [K].
--no_transport	off	Skip viscosity/conductivity table generation.
--include_entropy	off	Also write entropy table.
--liquid_bias	off	Bias sampling toward liquid side near saturation.
--vapor_bias	off	Bias sampling toward vapor side near saturation.
--bias_factor	mode-dependent	Custom bias multiplier for saturation pressure mapping.
--noextrapolate	off	Forces bias factor to 1.0.
--reference_temperature	298.15	Reference temperature [K] used with the reference enthalpy/entropy options.
--reference_pressure	101325	Reference pressure [Pa] used with the reference enthalpy/entropy options.
--reference_enthalpy	none	Target molar enthalpy [J/kmol] at the reference state, matching .mdl href units.
--reference_entropy	none	Target molar entropy [J/(kmol K)] at the reference state, matching .mdl sref units.
--auto_tlimits / --no_auto_tlimits	auto on	Enable or disable generated TlimitHi/Lo fits.
--tlimit_intervals	128	Interval count for generated T-limit fits.

refprop-specific behavior:

• --baseline_mode auto is available in this mode and is the default.

• --liquid_bias and --vapor_bias are mutually exclusive.

• The reference enthalpy and entropy options are only needed when a tabulated REFPROP/CoolProp species participates in reactions with species whose thermodynamic references come from the chemistry model file. Provide --reference_enthalpy and --reference_entropy together. The utility converts those molar reference values to mass-specific offsets and applies them before writing energyCorrect and optional entropy tables.

• Default --omega_mode in this mode is auto.

• Pass an explicit --table_name when you want a short stable .mdl reference such as eos=Table(name="N2").

• For --backend REFPROP, make the REFPROP installation visible to CoolProp. On Linux this is typically done by setting COOLPROP_REFPROP_ROOT to the directory containing librefprop.so, FLUIDS/, and MIXTURES/ before running tabulated_data.

cantera Mode

Purpose: sample a pure species from a Cantera mechanism and produce tabulated correction fields.

Additional flags:

cantera Mode Flags

Flag	Default	Description
mechanism (positional)	required	Cantera YAML mechanism path.
--phase	none	Optional phase name in mechanism.
--species	required	Species name to tabulate as pure fluid.
--table_name	species name	Output table directory name.
--pmin, --pmax	required	Pressure bounds [Pa].
--tmin, --tmax	required	Temperature bounds [K].
--no_transport	off	Skip viscosity/conductivity table generation.
--include_entropy	off	Also write entropy table.

Baseline behavior:

• Default --baseline_mode ideal computes baseline terms from sampled Cantera state.

fit_table Mode

Purpose: ingest fitTable input and generate EoS correction table outputs. This mode is useful when property data already exists as a pressure-temperature grid of density and enthalpy, but no Cantera or REFPROP/CoolProp source is available for the species. The input file itself is an EoS import path only. When the generic Stream tabularEoS module also needs transport tables, either provide --constant_viscosity and --constant_conductivity or append viscosity and conductivity grids to the input file and pass --fit_transport_from_table. The generated viscosity and conductivity kd files are written into the same EoSTables table directory. Keep transport_model: tabularEoS for this workflow. If the same chemistry model also contains non-table species, provide their viscosity and conductivity using local transportDB-style files in transport/.

Additional flags:

fit_table Mode Flags

Flag	Default	Description
fit_table (positional)	required	Path to a fit-table input file.
--table_name	file stem	Output table directory name.
--pmin, --pmax	source limits	Optional resampling pressure bounds [Pa] within the source table limits.
--tmin, --tmax	source limits	Optional resampling temperature bounds [K] within the source table limits.
--fit_eval_mode {hermite,linear}	hermite	hermite uses the fit-table Hermite interpolation path; linear uses separable linear interpolation.
--constant_viscosity	none	Optional constant viscosity [Pa*s]. Must be paired with --constant_conductivity.
--constant_conductivity	none	Optional constant thermal conductivity [W/(m*K)]. Must be paired with --constant_viscosity.
--fit_transport_from_table	off	Read two additional pressure-major blocks after enthalpy: viscosity [Pa*s], then thermal conductivity [W/(m*K)].

Compatibility notes:

• fit_table mode reads density and enthalpy and writes densityCorrect and energyCorrect tables.

• For a normal loadModule: tabularEoS case, provide viscosity and conductivity entries in the same EoSTables table manifest. Use refprop or cantera for property-derived transport, or the fit_table constant transport flags or appended transport grids for prescribed values. Keep transport_model: tabularEoS; do not switch the case to transport_model: transportDB or transport_model: const_viscosity to supply the table species’ transport properties.

• fit_table does not define species diffusion coefficients. Set diffusion_model separately; laminarSchmidt is the intended simple choice for these generated tabular-EoS fixtures.

• --adaptive_grid is supported in fit_table mode only when --fit_eval_mode hermite.

• See Advanced fitTable Input Format for the input file grammar.

Output Selection And Referencing

--output_mode controls file generation:

• kd: default and recommended for normal Stream cases.

• fixed: writes fixed-interval EoS tables for cases that specifically need that format.

• both: writes both kd and fixed outputs in the same table directory.

Notes:

• The writer records the selected files in info.desc. Users normally should not edit info.desc by hand.

• fixed output is limited to density/energy EoS corrections and requires logarithmic pressure and temperature axes.

• fixed mode writes density/energy fixed tables only. Optional entropy and transport outputs require kd or both.

• With refprop and cantera defaults, viscosity and conductivity are generated. Use --no_transport before choosing --output_mode fixed, or choose --output_mode both --info_mode fixed when you want fixed EoS corrections but still want kd transport files in the directory.

• kd output requires power-of-two cell counts. The depth controls are the simplest way to get that. fixed output can use non-power-of-two explicit cell counts.

• When --output_mode both is used, --info_mode selects whether info.desc points the runtime to the kd or fixed EoS correction files.

For ordinary tabulated-EoS cases, use the default --output_mode kd.

Table Format Details

All source modes produce the same EoS table representation: a table directory containing residual corrections to a simple baseline equation of state. The densityCorrect and energyCorrect files do not store raw density or raw internal energy. They store the amount that must be added to the baseline model to recover the sampled source property. The baseline coefficients are written to info.desc as m, R, b, r1, n, and hf.

For each sampled pressure/temperature state, the utility writes:

\[\rho_\mathrm{corr}(P,T) = \rho_\mathrm{source} - \left(\frac{P}{R T + b P} + r_1 P\right)\]

\[e_\mathrm{corr}(P,T) = e_\mathrm{source} - (n R T + h_f)\]

At run time, the table reader evaluates the baseline model from the coefficients in info.desc and adds the corresponding correction surface. In other words, the tabulated files provide only the pressure-temperature residual terms needed to recover the source density and internal energy. Some older descriptions include an additional temperature-only energy correction term. The tables generated by this utility write the pressure-temperature energyCorrect surface directly, so no separate temperature-only correction is generated by this tool.

The fit_table source reads density and enthalpy from the input file, but the generated table stores an internal-energy correction. The conversion is e = h - P/rho before the baseline correction is formed.

The optional viscosity and conductivity files are different: they store the sampled transport property values directly, not residual corrections.

The utility spaces pressure and temperature on logarithmic axes by default. That is the recommended setting for most real-fluid tables because useful pressure and temperature ranges often span large intervals. Keep the default --log_p and --log_t settings unless there is a specific reason to fit on linear axes.

For normal case setup, leave --output_mode at its default kd. Use fixed only when you specifically need the fixed-interval EoS table format. Fixed-table output is restricted to logarithmic pressure and temperature axes; if linear axes are needed, use kd output.

The correction fields are converted to bicubic Bezier patches. kd output stores those patches behind the kd-tree lookup format. fixedTable output stores the same patch data on a regular fixed-interval grid.

Advanced fitTable Input Format

Most users should generate tables directly from refprop mode. The fit_table source mode is an import path for existing numeric property tables. By default, the input file contains only density and enthalpy. If --fit_transport_from_table is supplied, two additional pressure-major blocks must follow enthalpy: viscosity, then thermal conductivity. The file is a whitespace-tokenized numeric format. Blank lines are allowed, and # starts a comment that runs to the end of the line:

tabulated_data fit_table oxygen.fitTable \
  --table_name oxygen_tab --fit_eval_mode hermite \
  --adaptive_grid --min_depth_x 2 --min_depth_y 2 --depth_x 6 --depth_y 6

# Molecular weight [kg/kmol], baseline coefficient n
m n

# Temperature axis [K]
nT
T_1 T_2 ... T_nT

# Pressure axis [Pa]
nP
P_1 P_2 ... P_nP

# Density [kg/m3], pressure-major
rho(P1,T1) rho(P1,T2) ... rho(P1,TnT) rho(P2,T1) ... rho(PnP,TnT)

# Enthalpy [J/kg], pressure-major
h(P1,T1)   h(P1,T2)   ... h(P1,TnT)   h(P2,T1)   ... h(PnP,TnT)

With --fit_transport_from_table, append these two blocks:

# Viscosity [Pa*s], pressure-major
mu(P1,T1)  mu(P1,T2)  ... mu(P1,TnT)  mu(P2,T1)  ... mu(PnP,TnT)

# Thermal conductivity [W/(m*K)], pressure-major
k(P1,T1)   k(P1,T2)   ... k(P1,TnT)   k(P2,T1)   ... k(PnP,TnT)

m is molecular weight [kg/kmol], n is the baseline coefficient in e = n R T + hf, temperature is [K], pressure is [Pa], density is [kg/m3], enthalpy is [J/kg], viscosity is [Pa*s], and thermal conductivity is [W/(m*K)]. Temperature and pressure axes must be strictly increasing and positive. The density, enthalpy, viscosity, and conductivity values are pressure-major arrays with shape (nP, nT). Transport values must be finite and positive when present.

Minimal numeric example:

# m, n
28.0 1.0

# two temperature samples
2
300.0 600.0

# two pressure samples
2
100000.0 200000.0

# rho(P1,T1), rho(P1,T2), rho(P2,T1), rho(P2,T2)
1000.0 1100.0
1200.0 1300.0

# h(P1,T1), h(P1,T2), h(P2,T1), h(P2,T2)
201000.0 202000.0
203000.0 204000.0

Dependencies And Troubleshooting

The utility is installed as tabulated_data in the solver bin directory.

• cantera mode requires the Python Cantera package.

• refprop mode requires the CoolProp Python package. The default --backend HEOS path uses CoolProp’s HEOS backend. Use --backend REFPROP only when a local REFPROP installation is available and visible to CoolProp. For example:

  export COOLPROP_REFPROP_ROOT=/path/to/REFPROP
  

  where the directory contains librefprop.so, FLUIDS/, and MIXTURES/.

• fit_table mode uses the numeric input file directly and does not require Cantera or CoolProp.

• If --omega_mode fitfile is used, --omega_fit_file must be provided.

• If explicitly-provided --tlimit_hi_fit or --tlimit_lo_fit paths are invalid, the utility exits with an error.

The tabulated_data CLI will auto-bootstrap the local Python environment when required packages are missing. You can also create or update that environment explicitly:

setup_tabulated_data_env

For cantera mode support, install the optional Cantera package into that same environment:

setup_tabulated_data_env --with-cantera

You can also request explicit setup inline when launching the CLI:

tabulated_data --setup-env refprop --fluid Water \
  --pmin 1.0e5 --pmax 2.0e7 --tmin 280 --tmax 600

For the latest option set, run:

tabulated_data -h
tabulated_data refprop -h
tabulated_data cantera -h
tabulated_data fit_table -h

Optional Viewer

The command-line tool is the primary documented path for reproducible table generation. A secondary viewer, tabulated_data_viewer, is also installed for users who want a GUI-like way to inspect generated tables or generate REFPROP tables interactively.

To launch the viewer from an installed tree:

tabulated_data_viewer

If the local tabulator environment does not exist yet, create or update it before launching:

tabulated_data_viewer --setup-env

From the repository root during development, the equivalent launcher is:

python tools/tabulated_data/tabulated_data_viewer.py

The viewer can browse table directories containing info.desc, show metadata and field previews, and save/load generation presets. It is optional; all table generation workflows described above can be run directly through tabulated_data.