Detailed Running
Code Structure
The 4D-TExS EoS Module computes the equation of state (pressure, densities, susceptibilities, and speed of sound) of QCD matter at finite \((T, \mu_B, \mu_Q, \mu_S)\) using the four-dimensional T′-expansion scheme. The module is implemented within a Docker container to ensure portability and consistency. The workflow involves parsing input parameters, performing core computations in C, and converting the results into standardized output files. Below is a detailed explanation of the code structure and its components.
Input Files:
config.yaml: Specifies the ranges and step sizes for \(T\), \(\mu_B\), \(\mu_Q\), and \(\mu_S\), as well as boolean switchers indicating which thermodynamic quantities to compute and store in the output (pressure, densities, energy density, entropy density, Hessian matrix elements, speed of sound, errors, and normalization).
Configuration Validation:
OpenAPI_Specifications_validator.py validates config.yaml against the OpenAPI specifications defined in OpenAPI_Specifications-4DTExS.yaml. Missing parameters are automatically filled with their default values, and a validated copy of the input file (
valid_config.yaml) is generated.
Preprocessing via Adapter:
Input_adapter_YAML_to_dat.py reads the validated YAML input and converts the requested \((T, \mu_B, \mu_Q, \mu_S)\) ranges into the intermediate text file
input_ranges.txt, which is the format expected by the core C executable. The switcher values are also extracted at this stage and passed downstream to control the output content.
Core Computation:
The main script MUSES_wrapper.py orchestrates the execution of the module: it calls the input adapter, invokes the compiled 4DTExS_EoS executable (built from 4D-TExS.c), and then calls the output adapter to convert the results.
The core executable reads
input_ranges.txt, loads the tabulated lattice QCD susceptibilities at \(\mu=0\) (stored under chis/), and performs the T′-expansion procedure over the requested grid in \((T, \mu_B, \mu_Q, \mu_S)\), optionally computing second-order susceptibilities (via finite differences), mixed \(T\)-\(\mu\) derivatives (via spline interpolation), and the isentropic speed of sound.
Output Files:
The raw results of the computation are saved as a combined
.datfile in a dedicated subfolder of output/, whose name encodes the requested ranges of \((T, \mu_B, \mu_Q, \mu_S)\).
Postprocessing via Porter:
Output_adapter.py uses the Porter library to convert the combined
.datfile into a standardized CSV file,4DTExS_eos_thermodynamics.csv, together with an accompanying metadata file4DTExS_metadata_thermodynamics.yamldescribing units and structure, both validated against the OpenAPI specifications.
Specifications:
Additional configurations and specifications are provided in OpenAPI_Specifications-4DTExS.yaml, which ensures consistency and reproducibility of inputs and outputs across different setups.
Core Function (in 4D-TExS.c)
The 4D-TExS.c file contains the main routine driving the whole computation, relying on several
dedicated source files under src/ for each physical quantity. Below is an overview of the key components:
Command-line options:
The executable accepts an input file (either
input_rangesfor grid-based scans orinput_anglesfor scans along a fixed direction) and optional flags controlling verbosity, file printing, error propagation, dimensional vs. dimensionless output, and calculation of the Hessian matrix (-Hess).
Reading lattice QCD inputs:
Susceptibility data at \(\mu = 0\) (organized in chis/) and pressure/entropy splines are read and interpolated at start-up, defining the maximum available temperature range for the computation.
Angular decomposition (ChiHelpers.c):
For each point \((\mu_B, \mu_Q, \mu_S)\), the corresponding direction \((\theta, \phi)\) and modulus \(\mu\) are computed, and the generalized susceptibilities \(X_2(T,\theta,\phi)\) and \(X_4(T,\theta,\phi)\) are constructed from the lattice inputs.
T′-expansion scheme (Lambda2.c, T_effective.c):
The function
Lambda2()computes the resummation coefficient \(\lambda_2(T)\), optionally smoothed viaLambda2_smooth()using multiple shifted-knot spline fits. The effective temperature \(T'(T,\hat\mu)\) is then evaluated in T_effective.c.
Thermodynamic quantities (X1.c, Second_derivatives.c):
Densities, pressure, entropy, and energy density are computed from \(X_1(T,\hat\mu)\) along the T′-expansion.
Second-order susceptibilities \(\chi_{ij}\) are computed via finite differences in \(\mu_B, \mu_Q, \mu_S\) with a step independent of the user-defined grid spacing, while mixed \(T\)-\(\mu\) and \(T\)-\(T\) derivatives are obtained via spline derivatives of the normalized density and entropy profiles.
Speed of sound (Speed_of_sound.c):
The isentropic speed of sound \(c_s^2\) is computed analytically in the \((T,\hat\mu)\) plane using the thermodynamic relations between \(X_1\), entropy, energy density, and pressure.
Special treatment at \(T=0\):
When the grid includes \(T=0\), thermodynamic quantities are extrapolated from the first three non-zero temperature points using a third-order finite-difference formula exploiting the known boundary conditions (vanishing entropy and charge-density derivatives at \(T=0\)).
Workflow Overview
The module’s workflow can be summarized as follows:
Input Validation:
config.yaml is validated against the OpenAPI specifications; missing parameters are filled with default values, and invalid inputs halt execution with an informative error message.
Preprocessing:
The validated YAML is converted into the
input_ranges.txtfile consumed by the core C executable.
Core Computation:
The 4DTExS_EoS executable computes the requested thermodynamic quantities over the full \((T,\mu_B,\mu_Q,\mu_S)\) grid, using the T′-expansion scheme, and stores them in a combined
.datfile.
Postprocessing:
The Porter library converts the
.datfile into a CSV file along with metadata, ready for downstream analysis or integration into the broader MUSES framework.
Status Reporting:
At every stage, a
status.yamlfile is updated with a status code and message describing the outcome of the execution (success or error).
Code Organization
The module’s code is organized into the following directories:
- api/
Contains the OpenAPI specifications, the input validation script, the input adapter converting YAML to
.dat, and the output adapter converting.datto CSV via Porter.Key files: OpenAPI_Specifications_validator.py, Input_adapter_YAML_to_dat.py, Output_adapter.py, OpenAPI_Specifications-4DTExS.yaml.
- src/
Contains the core C source files implementing the T′-expansion scheme.
Key files: 4D-TExS.c, Lambda2.c, T_effective.c, X1.c, X2.c, Second_derivatives.c, Speed_of_sound.c, Functions.c.
- include/
Contains the header files defining data structures (jackknife sets, splines, thermodynamic output structures) and function prototypes shared across the C source files.
- chis/
Contains tabulated lattice QCD susceptibility data at \(\mu = 0\), used as input to the T′-expansion.
- input/
Contains the user-provided
config.yamlfile.
- output/
Stores the generated output files, including the combined
.datfile, the converted CSV and metadata files, and thestatus.yamlfile.
- test/
Contains reference files and test scripts (Docker build/execution tests) for validating the module’s functionality.