Detailed Running
----------------

Code Structure
~~~~~~~~~~~~~~

The **HRG EoS Module** is designed to calculate thermodynamic quantities and conserved charge susceptibilities for a Hadron Resonance Gas (HRG) Equation of State, with optional van der Waals (VdW) interactions between hadrons.
The module is implemented within a Docker container to ensure portability and consistency.
The workflow involves parsing input parameters, performing core computations, and generating output files for further analysis.
Below is a detailed explanation of the code structure and its components.


1. **Input File**:
      |config|_ is used to specify the ranges for :math:`T`, :math:`\mu_B`, :math:`\mu_Q`, and :math:`\mu_S` (in MeV), as well as user-defined options for:
         - **HRG parameters**: Van der Waals interaction parameters :math:`a` (attractive, in GeV·fm\ :sup:`3`), :math:`b` (baryon excluding-volume, in fm\ :sup:`3`), and :math:`b_m` (meson excluding-volume, in fm\ :sup:`3`). Setting all to zero reduces the model to the Ideal HRG.
         - **Switchers**: Boolean flags selecting which thermodynamic quantities are stored in the output (e.g., pressure :math:`P`, entropy density :math:`s`, baryon/charge/strangeness densities, second-order susceptibilities)

2. **Configuration Validation**:
   the |specs_validator|_ script validates the |config|_ file against the |specs|_. This ensures that all required parameters are provided and conform to the expected structure.

3. **Core Computation**:
   the main script, |wrapper|_, orchestrates the execution of the module. It validates inputs, processes the input configuration, and calls the executable to compute the thermodynamic quantities on the :math:`(T, \mu_B, \mu_S, \mu_Q)` grid.

4. **Output Files**:
   the results of the computation are saved in the `output/` directory. The following files are generated:
      - **HRG_output_thermodynamics.csv**: Contains the calculated thermodynamic quantities and susceptibilities for each grid point, with only the columns corresponding to the enabled switchers.
      - **HRG_metadata_thermodynamics.yaml**: Describes the structure, types and units of the output data.
      - **status.yaml**: Provides the status of the module's execution, including success or error messages.


Core functions
~~~~~~~~~~~~~~

The |cpp_code|_ script contains the core functions for reading input parameters, setting up the thermal model, and computing thermodynamic quantities. Below is an overview of the key functions:

1. ``read_param(const char *param_file)``:
      - Reads the grid parameters from the intermediate input file `User_Input_Parameters.dat`.
      - Parses the ranges and step sizes for :math:`T`, :math:`\mu_B`, :math:`\mu_Q`, and :math:`\mu_S` (in GeV) and stores them in the global ``Parameters`` struct.

2. ``SetVDWInteractionParameters(ThermalModelRealGas* model, double a, double b, double bm)``: sets the van der Waals interaction parameters for the QvdW-HRG model, following the interaction scheme:
      - Baryon-baryon and antibaryon-antibaryon pairs: attraction :math:`a` and repulsion :math:`b`
      - Meson-meson pairs: repulsion :math:`b_m` only
      - Baryon-antibaryon and baryon-meson pairs: no interaction

3. ``PrintHeader(FILE *f, bool HessianMatrix)``:
      - Writes the header line of the output file, listing the column names for all computed quantities.
      - The columns included depend on whether the Hessian matrix calculation is enabled.

4. ``PrintOutput(FILE *f, bool HessianMatrix, int T_pts, double MuB, ...)``:
      - Writes the computed thermodynamic quantities to the output file for a given :math:`(\mu_B, \mu_Q, \mu_S)` point and all :math:`T` values.
      - Handles unit conversions (e.g., GeV to MeV) and formats the output as a whitespace-separated table.

5. ``main(int argc, char* argv[])``: the main function orchestrating the full computation:

      - Parses command-line arguments (input/output file names, VdW parameters, switcher flags) using ``getopt_long``.
      - Reads the grid parameters from the input file via ``read_param()``.
      - Instantiates either a **Ideal HRG** (``ThermalModelIdeal``) or a **QvdW-HRG** (``ThermalModelRealGas``) model depending on whether the VdW parameters are non-zero.
      - Iterates over all :math:`(\mu_B, \mu_Q, \mu_S)` grid points. At each point, loops over all :math:`T` values and:

         - Solves the self-consistent equations for hadron densities via ``CalculateDensities()``.
         - Skips points in the condensation region (where :math:`|\mu_Q| \geq m_\pi`, :math:`|\mu_S| \geq m_{K^0}`, or :math:`|\mu_S + \mu_Q| \geq m_{K^\pm}`), unless meson excluded-volume interactions are enabled.
         - Computes thermodynamic quantities: :math:`p`, :math:`\varepsilon`, :math:`s`, :math:`n_B`, :math:`n_Q`, :math:`n_S`, and optionally the pressure Hessian matrix elements :math:`\chi_2^{B,Q,S}`, :math:`\chi_{11}^{BQ,BS,QS}`, :math:`c_V`, and :math:`c_s^2`.

      - Writes the results to the intermediate output file `Thermo_Output_HRG.dat` via ``PrintOutput()``.


Code Organization
~~~~~~~~~~~~~~~~~~

The module's code is organized into the following directories:

- |api|_: contains the OpenAPI specifications, the input adapter, the output adapter, and the input validation script.

- |build|_: contains the build files generated by CMake and the compiled executable `hrg-eos-thermodynamics`.

- |src|_: contains the core computation script for calculating thermodynamic quantities.

- |input|_: contains the `config.yaml` file and the intermediate `User_Input_Parameters.dat` file generated by the input adapter.

- |output|_: stores the generated output files, including results (`HRG_output_thermodynamics.csv`), metadata (`HRG_metadata_thermodynamics.yaml`), and status (`status.yaml`).

- |test|_: contains reference files and test cases for validating the module's functionality.

..
  -------------------
  | Fixed variables |
  -------------------

.. |wrapper| replace:: **MUSES_Wrapper.py**
.. _wrapper: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/MUSES_Wrapper.py?ref_type=heads

.. |requir| replace:: **requirements.txt**
.. _requir: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/requirements.txt?ref_type=heads

.. |config| replace:: **config.yaml**
.. _config: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/input/config.yaml?ref_type=heads

.. |cpp_code| replace:: **src/HRG_EoS.cpp**
.. _cpp_code: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/src/HRG_EoS.cpp?ref_type=heads

.. |specs_validator| replace:: **OpenAPI_Specifications_validator.py**
.. _specs_validator: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/api/OpenAPI_Specifications_validator.py?ref_type=heads

.. |specs| replace:: OpenAPI specifications
.. _specs: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/api/OpenAPI_Specifications-HRG_vdW.yaml?ref_type=heads

.. |api| replace:: **api/**
.. _api: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/api?ref_type=heads

.. |build| replace:: **build/**
.. _build: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/build?ref_type=heads

.. |src| replace:: **src/**
.. _src: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/src?ref_type=heads

.. |input| replace:: **input/**
.. _input: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/input?ref_type=heads

.. |output| replace:: **output/**
.. _output: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/output?ref_type=heads

.. |test| replace:: **test/**
.. _test: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/test?ref_type=heads