Equation of State ================= The input EoS table is defined over a subset of the thermodynamic variables :math:`(T, \mu_B, \mu_S, \mu_Q)`. :math:`T` and :math:`\mu_B` (and their conjugate :math:`s`, :math:`n_B`) are always required, but the strangeness and electric-charge dimensions are each independently optional: a table can be provided in the full 4D BSQ form, or with either or both of the strangeness (:math:`\mu_S, n_S`) and charge (:math:`\mu_Q, n_Q`) dimensions, along with their associated susceptibilities, left out entirely. This is controlled by two flags in the ``input`` section of the configuration file (``has_S`` and ``has_Q``). Set ``has_S: false`` and/or ``has_Q: false`` when the physics being tabulated doesn't track that conserved charge as an independent degree of freedom (e.g. a strangeness-neutral, isospin-symmetric nuclear-matter table reduces cleanly to a 2D table in :math:`(T, \mu_B)` with ``has_S: false, has_Q: false``). This is a separate concern from how many of the table's columns actually *vary*: a full 4D table (``has_S: true, has_Q: true``) can still be gridded over, say, only :math:`(T, \mu_B)`, with :math:`\mu_S` and :math:`\mu_Q` held fixed (e.g. at the values enforced by a strangeness-neutrality condition) — all 10 basic columns are then still present in the file, just with two of them constant. ``has_S``/``has_Q`` are specifically about whether those columns exist in the file **at all**, not about how many axes vary; that's controlled independently by the actual data and by ``grid.output_grid`` (see :doc:`config`). Each row represents one point in the table and must contain at least the columns listed below, **in the fixed order shown** — the table reader assigns columns by position, not by a header name, so the physical meaning of each column is determined entirely by its column index together with the ``has_S``/``has_Q`` flags (see `Column order`_ below). The unit system is set via ``input.units`` in the configuration file; the table below lists the natural-unit interpretation used internally. Required columns ---------------- +----------------------------------------------------+---------------------------------+------------------+ | **Variable** | **Natural unit** | **Condition** | +====================================================+=================================+==================+ | Temperature (:math:`T`) | MeV (power 1) | always | +----------------------------------------------------+---------------------------------+------------------+ | Baryon chemical potential (:math:`\mu_B`) | MeV (power 1) | always | +----------------------------------------------------+---------------------------------+------------------+ | Strange chemical potential (:math:`\mu_S`) | MeV (power 1) | ``has_S: true`` | +----------------------------------------------------+---------------------------------+------------------+ | Electric charge chemical potential (:math:`\mu_Q`) | MeV (power 1) | ``has_Q: true`` | +----------------------------------------------------+---------------------------------+------------------+ | Baryon density (:math:`n_B`) | MeV\ :sup:`3` (power 3) | always | +----------------------------------------------------+---------------------------------+------------------+ | Strange density (:math:`n_S`) | MeV\ :sup:`3` (power 3) | ``has_S: true`` | +----------------------------------------------------+---------------------------------+------------------+ | Electric charge density (:math:`n_Q`) | MeV\ :sup:`3` (power 3) | ``has_Q: true`` | +----------------------------------------------------+---------------------------------+------------------+ | Energy density (:math:`\varepsilon`) | MeV\ :sup:`4` (power 4) | always | +----------------------------------------------------+---------------------------------+------------------+ | Pressure (:math:`P`) | MeV\ :sup:`4` (power 4) | always | +----------------------------------------------------+---------------------------------+------------------+ | Entropy density (:math:`s`) | MeV\ :sup:`3` (power 3) | always | +----------------------------------------------------+---------------------------------+------------------+ For ``has_S: true, has_Q: true`` (the default), this is the usual 10-column BSQ layout: :math:`T, \mu_B, \mu_S, \mu_Q, n_B, n_S, n_Q, \varepsilon, P, s`. For ``has_S: false, has_Q: false``, it reduces to the 6-column layout :math:`T, \mu_B, n_B, \varepsilon, P, s`. Mixed cases (one flag true, one false) drop only the corresponding potential/density pair, keeping the rest in the same relative order. Optional columns ---------------- The following columns are read when present in the input table. They are enabled via flags in the ``input`` section of the configuration file. +----------------------------------------------------+---------------------------------+----------------------------------+ | **Variable** | **Natural unit** | **Config flag** | +====================================================+=================================+==================================+ | Heat capacity (:math:`c_V`) | MeV\ :sup:`3` (power 3) | ``has_heat_capacity: true`` | +----------------------------------------------------+---------------------------------+----------------------------------+ | Phase index | (dimensionless) | ``has_phase_index: true`` | +----------------------------------------------------+---------------------------------+----------------------------------+ The phase index column must contain one of the following integer values for every row: +-----------+-------------------+ | **Value** | **Phase branch** | +===========+===================+ | ``0`` | stable | +-----------+-------------------+ | ``1`` | metastable | +-----------+-------------------+ | ``-1`` | unstable | +-----------+-------------------+ Any other value causes the table reader to fail. When ``input.only_stable`` is ``true`` (the default), only rows with phase index ``0`` are kept; otherwise the table is split into one branch per phase index found in the column. Susceptibility columns (written to output automatically when present in the input). Each requires its own potential(s) to also be present, so these are gated on ``has_S``/``has_Q`` in addition to the table actually carrying susceptibility data: +----------------------------------------------------+-------------------------+-------------------------+ | **Variable** | **Natural unit** | **Also requires** | +====================================================+=========================+=========================+ | Baryon susceptibility (:math:`\chi_{BB}`) | MeV\ :sup:`2` (power 2) | — | +----------------------------------------------------+-------------------------+-------------------------+ | Strange susceptibility (:math:`\chi_{SS}`) | MeV\ :sup:`2` (power 2) | ``has_S: true`` | +----------------------------------------------------+-------------------------+-------------------------+ | Electric charge susceptibility (:math:`\chi_{QQ}`) | MeV\ :sup:`2` (power 2) | ``has_Q: true`` | +----------------------------------------------------+-------------------------+-------------------------+ | Mixed susceptibility (:math:`\chi_{BS}`) | MeV\ :sup:`2` (power 2) | ``has_S: true`` | +----------------------------------------------------+-------------------------+-------------------------+ | Mixed susceptibility (:math:`\chi_{BQ}`) | MeV\ :sup:`2` (power 2) | ``has_Q: true`` | +----------------------------------------------------+-------------------------+-------------------------+ | Mixed susceptibility (:math:`\chi_{SQ}`) | MeV\ :sup:`2` (power 2) | ``has_S`` and ``has_Q`` | +----------------------------------------------------+-------------------------+-------------------------+ | Mixed susceptibility (:math:`\chi_{TB}`) | MeV\ :sup:`2` (power 2) | — | +----------------------------------------------------+-------------------------+-------------------------+ | Mixed susceptibility (:math:`\chi_{TS}`) | MeV\ :sup:`2` (power 2) | ``has_S: true`` | +----------------------------------------------------+-------------------------+-------------------------+ | Mixed susceptibility (:math:`\chi_{TQ}`) | MeV\ :sup:`2` (power 2) | ``has_Q: true`` | +----------------------------------------------------+-------------------------+-------------------------+ | Temperature susceptibility (:math:`\chi_{TT}`) | MeV\ :sup:`2` (power 2) | — | +----------------------------------------------------+-------------------------+-------------------------+ | Adiabatic speed of sound (:math:`c_s^2`) | (dimensionless) | — | +----------------------------------------------------+-------------------------+-------------------------+ Column order ------------ The table reader assigns every column by position, filtered only by the flags above — it never reads a header name to identify a column, so a header row (if present) is tolerated only because it fails to parse as numbers and is silently skipped, not because its text is used. The full, fixed column order is: .. code-block:: text T, muB, [muS], [muQ], nB, [nS], [nQ], e, p, s, chiBB, [chiSS], [chiQQ], [chiBS], [chiBQ], [chiSQ], chiTB, [chiTS], [chiTQ], chiTT, cs2, cV, phase where columns in brackets are included only when the corresponding flag (``has_S``/``has_Q``, and ``chiSQ`` needs both) is ``true`` — they are omitted from the file entirely otherwise, not left blank. The trailing ``cV`` and ``phase`` columns are themselves controlled by ``has_heat_capacity`` and ``has_phase_index`` as described above. Because identity is purely positional, getting this order wrong does not raise an error — it silently mislabels every column from the first mismatch onward, so double-check it carefully against your ``has_S``/``has_Q``/``has_heat_capacity``/``has_phase_index`` settings when preparing a custom table. Supported file formats ---------------------- The input table format is set via ``input.format`` in the configuration file. Supported values are: - ``hdf5`` or ``h5``: HDF5 file with a flat ``/data`` dataset (shape ``[N_points, N_cols]``), columns in the same fixed order as above. - ``csv``: Comma-separated values file. A header row is not parsed for column names; include one for readability if you like (it will be skipped), but column identity is always positional. - ``dat`` or ``txt``: Whitespace-delimited flat text file (``thermo.dat``).