Configuration File

The config.yaml file provides the configuration parameters for the Inverter module. Here is a sample configuration reflecting the current format:

n_threads: 1
default_eos: table

input:
  path: ../EoS/Houston/
  format: hdf5
  has_S: true
  has_Q: true
  units: MeV
  only_stable: true
  has_heat_capacity: false
  has_phase_index: false
  interpolation: auto

output:
  format: hdf5
  units: MeV
  add_eos_index: true
  add_metadata: true
  on_inversion_failure: nan
  prohibit_acausal_cs2: false
  restrict_mu_T_ratios: false
  enforce_output_envelope: false
  envelope_bandwidth: 0.05

grid:
  mode: explicit
  units: fm
  output_grid: [s, nB, nS, nQ]
  s:
    min: 0.01
    max: 100.0
    inner: 0.0
    points: 20
    scale: log
  nB:
    min: -1.0
    max: 1.0
    inner: 0.0
    points: 11
    scale: linear
  nS:
    min: 0.001
    max: 0.01
    inner: 0.0001
    points: 1
    scale: linear
  nQ:
    min: 0.0
    max: 1.0
    inner: 0.001
    points: 1
    scale: log

seeds:
  per_phase: 100
  total: 0

solver:
  tolerance: 1.0e-6
  max_steps: 1000

backup_eos:
  enabled: true
  models:
    - tanh_conformal
    - conformal
    - conformal_diagonal
    - cd_modified
  tanh_conformal:
    center_T: 250.0
    width_T: 100.0

Below is a description of all available parameters.

General Settings

  • n_threads: Number of threads used for parallel execution with OpenMP. If set to 0, the code uses all available threads.

  • default_eos: EoS model to use as the primary source. Currently only table is supported.

Input Settings

The input section controls the primary EoS table read by the inverter.

  • path: Path to the directory containing the input EoS table file(s).

  • format: Format of the input EoS file. Allowed values are hdf5 (or h5), csv, dat, and txt.

  • has_S: Whether the input table contains the strangeness dimension (\(\mu_S\), \(n_S\), and the strangeness-related susceptibilities). Default: true. Set to false when the table doesn’t carry those columns at all — e.g. a strangeness-neutral table reduced to \((T,\mu_B,\mu_Q)\) or \((T,\mu_B)\). See Equation of State for the exact column layout this implies.

  • has_Q: Whether the input table contains the electric-charge dimension (\(\mu_Q\), \(n_Q\), and the charge-related susceptibilities). Default: true. Independent of has_S — any combination of the two is supported.

  • units: Unit system of the input table. Allowed values are MeV, fm, MeV_fm, GeV, and adim. See Unit Systems for details.

  • only_stable: If true, restrict the inversion to the thermodynamically stable region of the EoS.

  • has_heat_capacity: Set to true if the input table contains the heat capacity \(c_V\) column. When enabled, \(c_V\) is written to the output table.

  • has_phase_index: Set to true if the input table contains a phase index column. When enabled, the phase index is written to the output table.

  • interpolation: Interpolation method used for the input table. This setting is optional; if omitted, auto is used.

    • auto: The code selects the best available method for the table dimension and format.

    • bilinear: Regular-grid bilinear (or multilinear in higher dimensions) interpolation. Requires a structured Cartesian grid.

    • delaunay: Delaunay triangulation–based interpolation. Works with unstructured grids and is the only option for 2D tables with non-rectangular domains.

Output Settings

The output section controls the output table written by the inverter.

  • format: Output file format. Allowed values are hdf5 (or h5) and csv.

  • units: Unit system for the output table. Allowed values are MeV, fm, MeV_fm, GeV, and adim.

  • add_eos_index: If true, write an integer column (eos_type) indicating which EoS model was used at each grid point.

  • add_metadata: If true, embed metadata (axis info, config snapshot) into the output file.

  • on_inversion_failure: Behavior when the root-finder fails to converge at a grid point.

    • nan: Fill thermodynamic fields with NaN; keep the point in the output.

    • exclude: Drop the failed point from the output entirely.

  • prohibit_acausal_cs2: If true, reject solutions with \(c_s^2 < 0\) or \(c_s^2 > 1\). The first condition flags thermodynamic instability; the second enforces causality (no superluminal signal propagation).

  • restrict_mu_T_ratios: If true, reject solutions where \(|\mu_i|/T > 3.5\) for any chemical potential \(\mu_i \in \{\mu_B, \mu_S, \mu_Q\}\).

  • enforce_output_envelope: If true, reject stable-phase table solutions whose output-space coordinates fall outside the envelope derived from the raw table. This prevents the interpolator from returning unphysical values near the table boundary. Default: false.

  • envelope_bandwidth: Half-width (in units of the primary output axis, typically entropy density) used when building the output-space envelope. At each axis point the envelope bounds are computed over all table rows within this distance. A value of 0 uses exact per-level bounds (no smoothing). Default: 0.0.

Grid Settings

The grid section defines the inversion target coordinates and the structure of the output grid.

  • units: Unit system that the min/max/inner bounds below are specified in. Independent of input.units and output.units — it governs only how the grid bounds themselves are converted to the solver’s internal units. Allowed values are MeV, fm, MeV_fm, GeV, and adim (see Unit Systems). This setting is optional; if omitted, fm is used, meaning the bounds are taken as literal values with no conversion. Set it to e.g. MeV to type grid bounds in natural units instead (a density bound is then interpreted as MeV3, per the power conventions in Unit Systems).

  • mode: Grid construction method.

    • explicit: Grid points are defined by per-axis min, max, points, and scale parameters. The full table is written to a single dataset.

    • decade: Grid points are generated logarithmically per decade. Each decade sub-table is written as a separate HDF5 group named by exponent, e.g. table_p-3_p-1_n-4_p-4.

      \[[10^{-3},10^{-2}],\ [10^{-2},10^{-1}],\ [10^{-1},1],\ [1,10],\ [10,100], \ldots\]

  • output_grid: Ordered list of axis names defining the inversion target variables. The inverter solves for \((T, \mu_B, \mu_S, \mu_Q)\) at each grid point defined by these coordinates. The grid can have any dimensionality from 1D to 4D.

    Supported axis names:

    Name

    Quantity

    s

    Entropy density (thermal axis)

    e

    Energy density (thermal axis)

    nB

    Baryon number density

    nS

    Strangeness density

    nQ

    Electric charge density

    yS

    Strangeness fraction \(y_S = n_S / n_B\)

    yQ

    Electric charge fraction \(y_Q = n_Q / n_B\)

    Examples:

    output_grid: [s, nB, nS, nQ]    # standard 4D entropy-density grid
output_grid: [e, nB, yS, yQ]    # energy-density grid with charge fractions
output_grid: [nB, yQ]           # 2D baryon-charge grid

Per-Axis Grid Parameters

Each axis listed in output_grid requires a sub-section with the following fields:

  • min: Minimum value of the axis (in input units).

  • max: Maximum value of the axis (in input units).

  • inner: Inner boundary used by logarithmic grids to avoid zero. Ignored when min >= 0 and scale: linear. For axes that include negative values with log scale, set inner to the absolute-value boundary near zero.

  • points: Number of grid points on this axis.

  • scale: Grid spacing type: linear or log.

Unit Systems

Both input and output support the following unit systems:

Name

Description

MeV

All quantities in natural MeV units

fm

All quantities in fm units

MeV_fm

Mixed: \(T,\mu\) in MeV; densities in fm-3; \(e,p\) in MeV/fm3

GeV

All quantities in natural GeV units

adim

Dimensionless

Seeds Settings

The seeds section controls how many initial guesses are drawn from the input table to initialize the root-finder at each grid point. This section is optional; omitting it applies the defaults shown below.

  • per_phase: Maximum number of seeds sampled per phase branch of the input table. The seeds are the \(k\) nearest-neighbor table points (in output space) to the current inversion target. Default: 100.

  • total: Global cap on the total number of seeds across all phases. Set to 0 to disable the global cap (use per_phase only). Default: 0.

Solver Settings

The solver section controls the root-finder used for the inversion. This section is optional; omitting it applies the defaults shown below.

  • tolerance: Convergence tolerance for the root-finder. The solver accepts a solution when the relative residual satisfies

    \[\frac{|f_i(x) - t_i|}{\max(|t_i|,\,10^{-10})} < \varepsilon \quad \forall\, i\]

    where \(t_i\) are the target values and \(\varepsilon\) is this tolerance. Default: 1.0e-6.

  • max_steps: Maximum number of Newton iterations per solve attempt. Default: 1000.

Backup EoS Settings

The backup_eos section configures fallback EoS models used when the primary table inversion fails (e.g. the target point lies outside the table domain or the solver does not converge). Backup models are tried in the order listed until one converges.

  • enabled: Enable or disable backup EoS fallback.

  • models: Ordered list of backup model names to try. Available models: tanh_conformal, conformal, conformal_diagonal, cd_modified.

The tanh_conformal model requires additional parameters under a tanh_conformal sub-key:

  • center_T: Center temperature of the hyperbolic-tangent transition function (in MeV).

  • width_T: Width of the transition function (in MeV).