Detailed Running

This section provides a detailed description of how the MUSES module operates.

Code Structure

Overview

This project runs inside a Docker container and follows a modular design for its computational workflow. The main components of the code are organized into configuration handling, numerical utilities, physics modules, and execution drivers.

Input Configuration

config.yaml (green block): serves as the central configuration file for input mapping and grid parameter settings, as described in config.yaml. It defines the main input parameters and their ranges, including
- temperature: \(T_{\min}\), \(T_{\max}\), \(dT\),
- baryon chemical potential: \(\mu_{B,\min}\), \(\mu_{B,\max}\), \(d\mu_B\),
- mapping parameters for the critical point:
  - \(w\): controls the size of the critical region,
  - \(\rho\): controls the shape of the critical region,
  - \(\alpha_{12}\): controls the orientation of the mapping,
  - \(\mu_{BC}\): sets the location of the critical point.

input.dat: generated by the adapter, this file converts the parameters from config.yaml into the format required by the C++ backend.

Core Source Code (`src/`)

The src/ directory contains the main computational components of the module. Based on the current code structure, the files can be grouped as follows.

Execution Drivers

main.cpp: the main C++ driver of the EoS calculation. It coordinates the overall workflow, calls the numerical and physics routines, and writes the backend thermodynamic and transition-line data.
main.py: the Python execution wrapper for the module. It is responsible for the high-level orchestration of the containerized workflow, including input validation, preprocessing, backend execution, parsing of backend output, and formatting of the user-facing CSV files.

Input Parsing and Parameter Handling

read_param.cpp: reads and parses the processed input parameters required by the C++ backend. This file bridges the external configuration and the internal numerical routines.

Grid Construction

adaptivegrid.cpp: constructs the computational grid in the \((T,\mu_B)\) plane. In particular, it supports adaptive or zoomed grid refinement near the critical region, allowing higher resolution where the thermodynamic observables vary rapidly.

Lattice and Baseline Thermodynamics

Lattice.cpp: reads and parameterizes lattice QCD results, including the baseline thermodynamic quantities used in the \(T^\prime\)-expansion scheme, such as
- \(P_0(T)\),
- \(\chi_2^B(T)\),
- \(\kappa_2^B(T)\),
together with their derivatives as needed by the numerical workflow.

Ising Mapping and Critical Contributions

FaaDiBrunoIsing.cpp: implements Faà di Bruno’s formula, which extends the chain rule to higher-order derivatives. This is used to evaluate derivatives of the mapped Ising thermodynamic functions with respect to the QCD variables.

In particular, it is used for composite expressions of the form

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

and related quantities appearing in the Ising-to-QCD mapping, as discussed in Physics overview.

Root Finding and Nonlinear Solvers

rootfinder.cpp: implements the numerical root-finding procedures needed to solve the nonlinear equations appearing in the mapping and thermodynamic reconstruction. These routines are used, for example, when determining effective quantities such as \(T^\prime\).

Numerical Utilities

library.cpp: provides general-purpose numerical utilities used throughout the code, including
- discretization of one-dimensional functions into vectors,
- discretization of two-dimensional functions into matrices,
- interpolation and helper routines,
- numerical differentiation by finite differences.
integral.cpp: contains the numerical integration routines used in the EoS construction, such as trapezoidal or related quadrature methods required for reconstructing pressure and other integrated observables.

Thermodynamic Reconstruction

thermodynamics.cpp: computes the thermodynamic observables of the full equation of state from the reconstructed baryon density and related susceptibilities. This includes quantities such as
- pressure \(P\),
- baryon number density \(n_B\),
- entropy density \(s\),
- energy density \(\epsilon\),
- speed of sound \(c_s^2\),
- and other derived observables.

In practice, this file contains the physics-level reconstruction of the final EoS once the lattice background, Ising contribution, and numerical derivatives have been assembled.

How the Source Files Work Together

At a high level, the workflow of the src/ directory proceeds as follows:

The user provides a config.yaml file.
The Python layer processes the configuration and prepares the backend input.
read_param.cpp reads the processed parameters.
adaptivegrid.cpp builds the thermodynamic grid.
Lattice.cpp provides the non-critical lattice/HRG background input.
FaaDiBrunoIsing.cpp and rootfinder.cpp are used to evaluate the mapped critical contribution and its derivatives.
integral.cpp and library.cpp provide the required numerical operations.
thermodynamics.cpp reconstructs the final thermodynamic observables.
main.cpp coordinates the complete C++ workflow and writes backend thermodynamic tables together with the transition-line data.
main.py handles the full module execution, parses the backend files, and exports the final CSV outputs used by the surrounding MUSES workflow.

Output Files

The processed results are written to the output directory as CSV files. The exact file names may carry a parameter-dependent suffix, but the current user-facing outputs follow the patterns below.

``Thermo_*.csv``: contains thermodynamic observables evaluated on the \((T,\mu_B)\) grid. Depending on the selected switchers, the file may include quantities such as
- temperature \(T\),
- baryon chemical potential \(\mu_B\),
- pressure \(P\),
- baryon number density \(n_B\),
- entropy density \(s\),
- energy density \(\epsilon\),
- speed of sound \(c_s^2\),
- specific heat \(c_v\),
- baryon susceptibilities \(\chi_2^B\), \(\chi_3^B\), and \(\chi_4^B\),
- higher temperature derivatives such as d2dT2,
- and related derived observables.
``transition_line.csv``: contains the transition line written separately from the thermodynamic grid output, typically as \((\mu_B, T_c(\mu_B))\) pairs.

The Python wrapper is responsible for collecting the backend outputs and formatting these user-facing CSV files.

Testing Framework (`test/`)

The test/ directory contains scripts for automated testing and validation:

Test_Docker_container.sh: checks that the containerized environment runs correctly by building the Docker image and executing the module unit test inside the container.
run_Docker_build.sh: builds the Docker container together with the required dependencies, including numpy, pyyaml, openapi-core, and muses_porter.
run_execution_test.sh: performs a module unit test by running the module with a reference input file and comparing the results against expected outputs.
Ref_files/: contains the reference files used by the module unit tests.

Specifications

Specification.yaml: provides the formal specification of the module, including the definitions of input and output files, input schemas, valid parameter ranges, and related metadata, using the OpenAPI standard.

Integration with Docker

The entire module is containerized to ensure consistency and reproducibility.

Input, processing, and output are handled in an isolated environment.
Docker helps ensure consistent execution across different systems.

Documentation (`docs`)

The docs directory contains the project documentation.

This modular structure provides

a clear separation between configuration, computation, and output,
flexibility in adapting parameters and methods,
streamlined debugging and validation through automated tests and containerization.