Output
------

YAML output file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The user can name this file in the YAML node "yaml_output_file" of the
input file. This file is stored in the repo home directory and shows
info of the format of the output files.

EoS output files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The user can specify the folder name where they want to store the EoS
output files in the yaml node "output_path" of the input file. By
default, the folder is named "output".

Inside the folder, there are several different output files.

phi0Phi1_lines.csv: This table is directly calculated from the initial
conditions given by phi0 Phi1 values.

eos.csv: This table is interpolated based on the output file
phi0Phi1_lines.csv and thus has a uniform grid in :math:`T` and
:math:`\mu_B`. It has all the phases: stable, unstable, and meta phases.

stable_eos.csv: This table is obtained by performing a Maxwell
construction on the output file eos.csv, and thus only has the stable phase.

transition_line.csv: This table records the first-order transition line and
relevant thermodynamics given by the EoS. The calculation is not precise
enough yet, and the first-order transition line does not go all the way to the
critical point.

spinodal_lines.csv: This table records the spinodal lines and relevant
thermodynamics.

Transport and energy loss output
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When ``transport_coefficient: true`` is set in ``transport_options``, transport quantities
are appended as extra columns to ``phi0Phi1_lines.csv``, ``spinodal_lines.csv``,
``eos.csv``, and (after Maxwell construction) ``stable_eos.csv``. No separate transport
file is generated.
Points where transport values are unphysical (NaN or negative intermediate results) are
output as ``NaN`` in all tables.

Column metadata files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Every output table is written together with a companion metadata file named
``<table>_metadata.yaml`` (for example, ``eos.csv`` is accompanied by
``eos_metadata.yaml``). The metadata file lists the columns of the table **in
the order in which they appear in the data file**, and for each column gives
its description, data type, and units:

.. code-block:: yaml

   T:
     description: temperature
     type: number
     x-unit: MeV
   mu_B:
     description: baryon chemical potential
     type: number
     x-unit: MeV
   # ... one entry per column, in column order

This is the metadata layout used by the MUSES `Porter
<https://gitlab.com/nsf-muses/common/-/tree/main/Porter>`_ library, so a
"muses-synthesis" table (comma-separated, no header row) can be loaded
directly with:

.. code-block:: python

   from muses_porter import Porter

   porter = Porter()
   porter.import_table(
       "output/eos.csv",
       extension="CSV",
       filename_metadata="output/eos_metadata.yaml",
       delimiter=",",
   )

The metadata files are generated for both the "muses-synthesis" and the
"legacy" output formats.

Output file format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If one selects the table format to be "muses-synthesis" (the default format), the
equation of state tables follow the following format:

+----------------------------------------------------+------------------+
| **Variable**                                       | **Unit**         |
+====================================================+==================+
| Temperature (T)                                    | MeV              |
+----------------------------------------------------+------------------+
| Baryon chemical potential (:math:`\mu_B`)          | MeV              |
+----------------------------------------------------+------------------+
| Strange chemical potential (:math:`\mu_S`)         | MeV              |
+----------------------------------------------------+------------------+
| Electric charge chemical potential (:math:`\mu_Q`) | MeV              |
+----------------------------------------------------+------------------+
| Baryon density (:math:`n_B`)                       | MeV\ :sup:`3`    |
+----------------------------------------------------+------------------+
| Strange density (:math:`n_S`)                      | MeV\ :sup:`3`    |
+----------------------------------------------------+------------------+
| Electric charge density (:math:`n_Q`)              | MeV\ :sup:`3`    |
+----------------------------------------------------+------------------+
| Energy density (:math:`\varepsilon`)               | MeV\ :sup:`4`    |
+----------------------------------------------------+------------------+
| Pressure (:math:`P`)                               | MeV\ :sup:`4`    |
+----------------------------------------------------+------------------+
| Entropy density (:math:`s`)                        | MeV\ :sup:`3`    |
+----------------------------------------------------+------------------+

Since the model currently only allows one charge, columns related to Q and S
charges will be set to 0. If one specifies muses_extra_columns, those columns
will be appended at last.

phi0Phi1_lines, transition_line, and spinodal_lines are not equation of state
tables, so they will not follow the same format. When ``transport_coefficient: true``,
transport columns (qhat, sigma_B, zeta, and per-velocity drag/kappa columns) are appended
after the standard columns in phi0Phi1_lines and spinodal_lines. The format for each file
is listed below:

For phi0Phi1_lines and spinodal_lines:

+----------------------------------------------------+------------------+
| **Variable**                                       | **Unit**         |
+====================================================+==================+
| Temperature (T)                                    | MeV              |
+----------------------------------------------------+------------------+
| Baryon chemical potential (:math:`\mu_B`)          | MeV              |
+----------------------------------------------------+------------------+
| Entropy density (:math:`s`)                        | MeV\ :sup:`3`    |
+----------------------------------------------------+------------------+
| Baryon density (:math:`n_B`)                       | MeV\ :sup:`3`    |
+----------------------------------------------------+------------------+
| Energy density (:math:`\varepsilon`)               | MeV\ :sup:`4`    |
+----------------------------------------------------+------------------+
| Pressure (:math:`P`)                               | MeV\ :sup:`4`    |
+----------------------------------------------------+------------------+
| Trace Anomaly (:math:`I`)                          | MeV\ :sup:`4`    |
+----------------------------------------------------+------------------+
| Phase                                              | N/A              |
+----------------------------------------------------+------------------+
| Baryon susceptibility (:math:`chi_2`)              | N/A              |
+----------------------------------------------------+------------------+
| (:math:`\frac{\partial s}{\partial T}`)            | N/A              |
+----------------------------------------------------+------------------+
| (:math:`\frac{\partial n_B}{\partial \mu_B}`)      | N/A              |
+----------------------------------------------------+------------------+
| (:math:`\frac{\partial s}{\partial \mu_B}`)        | N/A              |
+----------------------------------------------------+------------------+
| (:math:`\phi_0`)                                   | N/A              |
+----------------------------------------------------+------------------+
| (:math:`\Phi_1`)                                   | N/A              |
+----------------------------------------------------+------------------+
| precision                                          | N/A              |
+----------------------------------------------------+------------------+

For transition_line:

+----------------------------------------------------+------------------+
| **Variable**                                       | **Unit**         |
+====================================================+==================+
| Baryon chemical potential (:math:`\mu_B`)          | MeV              |
+----------------------------------------------------+------------------+
| Temperature (T)                                    | MeV              |
+----------------------------------------------------+------------------+
| Pressure (:math:`P`)                               | MeV\ :sup:`4`    |
+----------------------------------------------------+------------------+
| Latent heat (:math:`L`)                            | MeV\ :sup:`4`    |
+----------------------------------------------------+------------------+

When ``transport_coefficient: true``, the following columns are appended to the
EoS output (``eos.csv`` and ``stable_eos.csv``). One set of drag and Langevin columns
is added per velocity value specified in ``transport_options``:

+------------------------------------------------------------+------------------+
| **Variable**                                               | **Unit**         |
+============================================================+==================+
| Jet quenching parameter (:math:`\hat{q}`)                  | N/A              |
+------------------------------------------------------------+------------------+
| Baryon conductivity (:math:`\sigma_B/T`)                   | N/A              |
+------------------------------------------------------------+------------------+
| Bulk viscosity (:math:`\zeta/s`)                           | N/A              |
+------------------------------------------------------------+------------------+
| Drag force (:math:`F_\mathrm{drag}`) per velocity          | N/A              |
+------------------------------------------------------------+------------------+
| Langevin coefficient (:math:`\kappa_\perp`) per velocity   | N/A              |
+------------------------------------------------------------+------------------+
| Langevin coefficient (:math:`\kappa_\parallel`) per velocity| N/A             |
+------------------------------------------------------------+------------------+