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.

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

  2. Configuration Validation:

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

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

  5. Output Files:

    • The raw results of the computation are saved as a combined .dat file in a dedicated subfolder of output/, whose name encodes the requested ranges of \((T, \mu_B, \mu_Q, \mu_S)\).

  6. Postprocessing via Porter:

    • Output_adapter.py uses the Porter library to convert the combined .dat file into a standardized CSV file, 4DTExS_eos_thermodynamics.csv, together with an accompanying metadata file 4DTExS_metadata_thermodynamics.yaml describing units and structure, both validated against the OpenAPI specifications.

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

  1. Command-line options:

    • The executable accepts an input file (either input_ranges for grid-based scans or input_angles for 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).

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

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

  4. T′-expansion scheme (Lambda2.c, T_effective.c):

    • The function Lambda2() computes the resummation coefficient \(\lambda_2(T)\), optionally smoothed via Lambda2_smooth() using multiple shifted-knot spline fits. The effective temperature \(T'(T,\hat\mu)\) is then evaluated in T_effective.c.

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

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

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

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

  2. Preprocessing:

    • The validated YAML is converted into the input_ranges.txt file consumed by the core C executable.

  3. 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 .dat file.

  4. Postprocessing:

    • The Porter library converts the .dat file into a CSV file along with metadata, ready for downstream analysis or integration into the broader MUSES framework.

  5. Status Reporting:

    • At every stage, a status.yaml file 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: