Configuration File ================== The ``config.yaml`` file provides the configuration parameters for the Inverter module. Here is a sample configuration reflecting the current format: .. code-block:: yaml 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 (:math:`\mu_S`, :math:`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 :math:`(T,\mu_B,\mu_Q)` or :math:`(T,\mu_B)`. See :doc:`eos` for the exact column layout this implies. - **has_Q**: Whether the input table contains the electric-charge dimension (:math:`\mu_Q`, :math:`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 :math:`c_V` column. When enabled, :math:`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 :math:`c_s^2 < 0` or :math:`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 :math:`|\mu_i|/T > 3.5` for any chemical potential :math:`\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 MeV\ :sup:`3`, 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``. .. math:: [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 :math:`(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 :math:`y_S = n_S / n_B` | +--------+---------------------------------------------------+ | ``yQ`` | Electric charge fraction :math:`y_Q = n_Q / n_B` | +--------+---------------------------------------------------+ Examples: .. code-block:: yaml 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: .. list-table:: :header-rows: 1 :widths: 20 80 * - Name - Description * - ``MeV`` - All quantities in natural MeV units * - ``fm`` - All quantities in fm units * - ``MeV_fm`` - Mixed: :math:`T,\mu` in MeV; densities in fm\ :sup:`-3`; :math:`e,p` in MeV/fm\ :sup:`3` * - ``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 :math:`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 .. math:: \frac{|f_i(x) - t_i|}{\max(|t_i|,\,10^{-10})} < \varepsilon \quad \forall\, i where :math:`t_i` are the target values and :math:`\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).