Detailed Running

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

Code Structure

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

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: \(T_{min}\), \(T_{max}\), \(dT\),
- Baryon chemical potential: \(\mu_{B_{min}}\), \(\mu_{B_{max}}\), \(d\mu_B\),
- Mapping parameters for critical points:
  - \(w\): Size of criticality,
  - \(\rho\): Shape of criticality,
  - \(\alpha_{12}\): Size and shape,
  - \(\mu_{BC}\): Location of the critical point.

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

The src/ directory contains the main computational modules:

RootFinder.cpp: implements root-finding algorithms using the Broyden method for updating thermodynamic variables like \(T'\) and \(\mu_B\).
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:

\[P(R(r(T, \mu_B), h(T, \mu_B)), \theta(r(T, \mu_B), h(T, \mu_B)))\]

with respect to \(T'\) and \(\mu_B\), up to the 5th order (see FaaDiBrunoIsing), as discussed in Physics overview.
derivatives.cpp: calculates derivatives of the mapping function between \((r(T, \mu_B), h(T, \mu_B))\) with respect to temperature and baryon chemical potential (see derivatives.cpp).
library.cpp: provides general-purpose functions in C++:
- discretization of 1D functions \(f(x)\) into vectors,
- discretization of 2D functions \(f(x, y)\) into matrices,
- numerical derivatives of matrices using the central difference method,
- numerical integration using the trapezoidal rule (see library.cpp).
Lattice.cpp: reads and parameterizes lattice QCD results, including observables like:
- \(P_0(T)\),
- \(\chi_2(T)\),
- \(\kappa_2(T)\),
- their derivatives up to the 5th order (see Lattice.cpp).
main.cpp: the central processing module that orchestrates calculations:
- reads input from input.dat,
- computes effective temperature \(T'(T, \mu_B)\) and its derivatives,
- calculates thermodynamic observables (see main.cpp).

output.dat (grey block): contains raw computed results as a function of \((T,\mu_B)\), including:
- Pressure (\(P\)),
- Baryon number density (\(n_B\)),
- Second-order baryon number susceptibility (\(\chi^B_2\)),
- Entropy density (\(S\)),
- Energy density (\(\epsilon\)),
- Speed of sound (\(c_s^2\)),
- Specific heat (\(c_v\)),
- Trace anomaly (\((P-3\epsilon)/T^4\)).
output.yaml (red block): reformats raw results into CSV format for integration with other tools or workflows.

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.
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.

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`_.

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.

The docs directory contains the project documentation.