Appendix: tabulated_data Utility

The tabulated_data utility generates tabulated equation-of-state and optional transport files in the EoSTables/<table_name>/ layout used by tabular-EoS cases.

The utility is installed as tabulated_data in the solver bin directory. The viewer is installed as tabulated_data_viewer and the environment setup helper as setup_tabulated_data_env.

To launch the GUI from an installed tree:

tabulated_data_viewer

If the local tabulator environment does not exist yet, you can create/update it explicitly first:

tabulated_data_viewer --setup-env

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

python tools/tabulated_data/tabulated_data_viewer.py

To create or update the local Python environment used by the tabulator tools:

setup_tabulated_data_env

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

setup_tabulated_data_env --with-cantera

The tabulated_data CLI and tabulated_data_viewer will also auto-bootstrap that local environment when their required Python packages are missing. 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

What Is Being Fit

All source modes produce the same table representation: a table directory containing corrections to a simple baseline equation of state. 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{correct} = \rho_\mathrm{source} - \left(\frac{P}{R T + b P} + r_1 P\right)\]

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

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 utility samples pressure and temperature on log(P) and log(T) axes by default. The runtime supports two EoS correction readers, selected by the info.desc file. kd files are referenced with file densityCorrect and file energyCorrect; the evaluator decides whether to pass P/T or log(P)/log(T) by looking for logP and logT in the filename. fixedTable files are referenced with file densityCorrectFixed and file energyCorrectFixed. The fixed-interval evaluator does not read an axis flag from the filename; it always evaluates with log(P) and log(T), so fixed-table data must be generated on logarithmic pressure and temperature axes.

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.

What The Utility Produces

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

EoSTables/<table_name>/

The directory contains:

• info.desc (table metadata + file references)

• omega.fit

• EoS correction surfaces: - kd-tree format: densityCorrect_*.kd, energyCorrect_*.kd - fixed-table format: densityCorrect_*.fixedTable, energyCorrect_*.fixedTable

• Optional fields: - entropy_*.kd - viscosity_*.kd - conductivity_*.kd

• Optional temperature limits: - TlimitHi.fit - TlimitLo.fit

The exact set of files depends on source mode and output flags.

Using Generated Tables In A Case

For a tabulated-EoS case setup, the generated EoSTables/<table_name>/ directory is only one part of the setup. The corresponding species entry in the .mdl file must also reference that table with eos=Table(name="<table_name>"). If you do not pass --table_name in refprop mode, the utility generates a descriptive directory name such as heos_water_full_bauto. Pass a short explicit name, such as --table_name N2, when that is the name you want to appear in the .mdl file.

Recommended workflow:

1. Generate one table per tabulated species.

2. Keep the resulting EoSTables/ directory next to case.vars or under $CHEMISTRY_DATABASE/data_base/EoSTables.

3. Patch or check the species entries in the .mdl file so each tabulated species uses eos=Table(name="<table_name>"). The --update_mdl and --mdl_species options can do this while the table is generated.

The minimum case-side requirements are:

• Load the tabularEoS module:

  loadModule: tabularEoS
  

• Use a real-fluid chemistry model:

  chemistry_model: HeN2
  eos_type: fluid
  

• Point each tabulated species entry in HeN2.mdl at its table:

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

• Use the tabulated-EoS transport selector:

  transport_model: tabularEoS
  

  The current generic tabularEoS module expects this selector when it is loaded. Generate viscosity and conductivity tables for the species used by the case.

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

The tabulated_data CLI can patch an existing .mdl file for you while writing a table:

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

Run the command once per tabulated species. For the generic loadModule: tabularEoS workflow, do not use --no_transport; the runtime module also reads the viscosity and conductivity tables selected by transport_model: tabularEoS.

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 viscosity and conductivity in the generic workflow. Species diffusion still follows diffusion_model; with diffusion_model: default this falls back to laminarSchmidt.

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

Invocation

General CLI form:

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

Source modes:

Choosing A Source Mode

Mode	Use When	Dependency	First Command Shape
cantera	You have a Cantera YAML mechanism and want a pure-species table.	Python Cantera package.	tabulated_data cantera chem.yaml --species O2 ...
fit_table	You already have a fitTable file containing density and enthalpy.	NumPy only.	tabulated_data fit_table oxygen.fitTable ...
refprop	You want pure-fluid data from CoolProp HEOS or an installed REFPROP backend.	CoolProp Python package, plus REFPROP if --backend REFPROP is used.	tabulated_data refprop --backend HEOS --fluid Water ...

Required Inputs By Mode

Required Inputs

Mode	Required Inputs	Notes
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.
refprop	--fluid, --pmin, --pmax, --tmin, --tmax	Requires CoolProp Python package. Backend defaults to HEOS; choose --backend REFPROP when REFPROP is installed.

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 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.

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 table outputs.

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.

Fit table input format:

m n
nT
T_1 T_2 ... T_nT
nP
P_1 P_2 ... P_nP
rho(P1,T1) rho(P1,T2) ... rho(P1,TnT) rho(P2,T1) ... rho(PnP,TnT)
h(P1,T1)   h(P1,T2)   ... h(P1,TnT)   h(P2,T1)   ... h(PnP,TnT)

The file is whitespace-tokenized as numbers only; do not put comments inside the data block. 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], and enthalpy is [J/kg]. Temperature and pressure axes must be strictly increasing and positive. The density and enthalpy values are pressure-major arrays with shape (nP, nT).

Minimal numeric example:

28.0 1.0
2
300.0 600.0
2
100000.0 200000.0
1000.0 1100.0 1200.0 1300.0
201000.0 202000.0 203000.0 204000.0

Compatibility notes:

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

refprop Mode

Purpose: sample pure-fluid properties with CoolProp backends and generate tabulated outputs.

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.
--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.

• 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").

Output Selection And Referencing

--output_mode controls file generation:

• kd: writes kd-tree fields.

• fixed: writes fixed-table fields.

• both: writes both kd and fixed outputs.

Notes:

• info.desc is the runtime contract. For EoS corrections it references either file densityCorrect ... / file energyCorrect ... for kd-tree files, or file densityCorrectFixed ... / file energyCorrectFixed ... for fixed-table files.

• For kd-tree EoS files, the filename indicates whether pressure and temperature are evaluated directly or through log(P) / log(T). The current writer uses names such as densityCorrect_logP_logT.kd.

• Fixed-table EoS evaluation always uses log(P) and log(T) inputs, so the writer only emits fixed EoS tables on logarithmic axes.

• fixedTable files are usable table inputs, not viewer-only artifacts. They are selected only when info.desc uses the densityCorrectFixed and energyCorrectFixed keys. With --output_mode both --info_mode kd, fixed files are written but not selected by info.desc.

• 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.

• fixed output is log-axis only. Keep the default --log_p and --log_t settings when writing fixed tables.

--info_mode controls what info.desc points to when --output_mode both is used.

Examples

Cantera species tabulation:

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

fitTable conversion:

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

REFPROP/HEOS-style 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

Small two-species case setup:

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

Then check that case.vars contains the tabular-EoS setup:

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

and that HeN2.mdl references the generated table names:

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

Dependencies And Troubleshooting

• cantera mode requires Cantera Python package.

• refprop mode requires CoolProp Python package.

• 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.

For the latest option set, run:

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