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

 This section provides detailed explanations of the functioning of the MUSES module.

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

Overview
^^^^^^^^^

This project runs inside a Docker container and follows a modular design for computational workflows. Below is a breakdown of its key components.

Input Configuration
^^^^^^^^^^^^^^^^^^^^

- **config.yaml** (*green block*): acts as the central configuration file for input mapping and grid parameter settings as `config.yaml`_. Defines key parameters and their ranges:

  - Temperature: :math:`T_{min}`, :math:`T_{max}`, :math:`dT`,
  - Baryon chemical potential: :math:`\mu_{B_{min}}`, :math:`\mu_{B_{max}}`, :math:`d\mu_B`,
  - Mapping parameters for critical points:
    
    - :math:`w`: Size of criticality,
    - :math:`\rho`: Shape of criticality,
    - :math:`\alpha_{12}`: Size and shape,
    - :math:`\mu_{BC}`: Location of the critical point.

.. _config.yaml: https://gitlab.com/nsf-muses/module-ising-eos/ising_eos/-/blob/main/input/config.yaml?ref_type=heads

- **input.dat**: generated by the adapter, it processes parameters from `config.yaml`_ to provide input for ``main.cpp`` in the ``src`` directory.

Core Source Code (`src/`)
^^^^^^^^^^^^^^^^^^^^^^^^^

The `src/` directory contains the main computational modules:

- **RootFinder.cpp**: implements root-finding algorithms using the `Broyden method`_ for updating thermodynamic variables like :math:`T'` and :math:`\mu_B`.

  .. _Broyden method: https://en.wikipedia.org/wiki/Broyden%27s_method

- **FaaDiBrunoIsing.cpp**: implements the Faa di Bruno formula, a generalization of the chain rule, to compute higher-order derivatives. This is used to evaluate derivatives of the composite function:

    .. math::
       P(R(r(T, \mu_B), h(T, \mu_B)), \theta(r(T, \mu_B), h(T, \mu_B)))

  with respect to :math:`T'` and :math:`\mu_B`, up to the 5th order (see `FaaDiBrunoIsing`_), as  discussed in :ref:`physicsoverview`.

    .. _FaaDiBrunoIsing: https://en.wikipedia.org/wiki/Fa%C3%A0_di_Bruno%27s_formula

- **derivatives.cpp**: calculates derivatives of the mapping function between :math:`(r(T, \mu_B), h(T, \mu_B))` with respect to temperature and baryon chemical potential (see `derivatives.cpp`_).

  .. _derivatives.cpp: https://gitlab.com/nsf-muses/module-ising-eos/ising_eos/-/blob/main/src/derivatives.cpp?ref_type=heads

- **library.cpp**: provides general-purpose functions in C++:

  - discretization of 1D functions :math:`f(x)` into vectors,
  - discretization of 2D functions :math:`f(x, y)` into matrices,
  - numerical derivatives of matrices using the central difference method,
  - numerical integration using the trapezoidal rule (see `library.cpp`_).

   .. _library.cpp: https://gitlab.com/nsf-muses/module-ising-eos/ising_eos/-/blob/main/src/library.cpp?ref_type=heads

- **Lattice.cpp**: reads and parameterizes lattice QCD results, including observables like:

  - :math:`P_0(T)`,
  - :math:`\chi_2(T)`,
  - :math:`\kappa_2(T)`,
  - their derivatives up to the 5th order (see `Lattice.cpp`_).

    .. _Lattice.cpp: https://gitlab.com/nsf-muses/module-ising-eos/ising_eos/-/blob/main/src/Lattice.cpp?ref_type=heads

- **main.cpp**: the central processing module that orchestrates calculations:
  
  - reads input from `input.dat`,
  - computes effective temperature :math:`T'(T, \mu_B)` and its derivatives,
  - calculates thermodynamic observables (see `main.cpp`_).

    .. _main.cpp: https://gitlab.com/nsf-muses/module-ising-eos/ising_eos/-/blob/main/src/main.cpp?ref_type=heads

Output Files
^^^^^^^^^^^^^

- **output.dat** (*grey block*): contains raw computed results as a function of :math:`(T,\mu_B)`, including:

  - Pressure (:math:`P`),
  - Baryon number density (:math:`n_B`),
  - Second-order baryon number susceptibility (:math:`\chi^B_2`),
  - Entropy density (:math:`S`),
  - Energy density (:math:`\epsilon`),
  - Speed of sound (:math:`c_s^2`),
  - Specific heat (:math:`c_v`),
  - Trace anomaly (:math:`(P-3\epsilon)/T^4`).

- **output.yaml** (*red block*): reformats raw results into CSV format for integration with other tools or workflows.

Testing Framework (`test/`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The `test/` directory contains scripts to automate testing and validation:

- **Test_Docker_container.sh**: ensures the containerized environment runs correctly by building the Docker container and running the module unit test inside.

- **run_Docker_build.sh**: builds the Docker container with required dependencies such as `numpy`_, `pyyaml`_, `openapi-core`_, and `muses_porter`_.

  .. _numpy: https://numpy.org/
  .. _pyyaml: https://pyyaml.org/
  .. _openapi-core: https://github.com/p1c2u/openapi-core
  .. _muses_porter: https://gitlab.com/nsf-muses/common/-/tree/main/Porter

- **run_execution_test.sh**: module unit test, running the module using a reference input file and comparing results against expected outputs, to ensure proper functioning.

- `**Ref_files/**`: a folder containing all the reference files used for module unit test.

Specifications
^^^^^^^^^^^^^^

- **Specification.yaml**: provides essential metadata defining the specifications of the module, i.e. the input and output files as well as their characteristics (input schemas, ranges of parameter values, etc.), using the standard `OpenAPI`_.

  .. _OpenAPI_: https://www.openapis.org/

Integration with Docker
^^^^^^^^^^^^^^^^^^^^^^^

The entire module is containerized for consistency and reproducibility:
 
  - input, processing, and output are handled in an isolated environment,
  - Docker ensures consistent results across different systems.

Documentation (`docs`)
^^^^^^^^^^^^^^^^^^^^^^^^

The `docs` directory contains the project documentation.

.. Conclusion
.. ^^^^^^^^^^^

.. This modular structure offers:
.. - Clear separation of configuration, computation, and output.
.. - Flexibility to adapt parameters or methods.
.. - Streamlined debugging and validation with test scripts and containerization.