Detailed Running
Code Structure
The BQS 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 a Taylor expansion of the lattice-based susceptibilities. 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, susceptibilities, pressure derivatives, and speed of sound).
BQS_eos_input_coef_new.yaml (default) or BQS_eos_input_coef.yaml (legacy): Provide the Taylor expansion coefficients used to parametrize the lattice-based susceptibilities, following either of the two supported parametrizations (see Parameters).
Configuration Validation:
OpenAPI_Specifications_validator.py validates config.yaml and the chosen coefficient file against the OpenAPI specifications defined in OpenAPI_Specifications-BQS_EoS.yaml. Missing parameters are automatically filled with their default values, and validated copies of the input files (
valid_config.yaml,valid_BQS_eos_input_coef_new.yamlorvalid_BQS_eos_input_coef.yaml) are generated.
Preprocessing via Adapter:
Input_adapter-YAML_to_dat.py reads the validated YAML inputs and converts the requested \((T, \mu_B, \mu_Q, \mu_S)\) ranges, switchers, and coefficient values into intermediate
.dat/text files, the format expected by the core C executable.
Core Computation:
The main script MUSES_Wrapper.py orchestrates the execution of the module: it calls the OpenAPI validator, then the input adapter, invokes the compiled EoS_BQS executable (built from EoS_BQS.c), and finally calls the output adapter to convert the results.
The core executable reads the intermediate input files, loads the Taylor expansion coefficients into the
parMatrixarray, and computes the requested thermodynamic quantities over the full grid in \((T, \mu_B, \mu_Q, \mu_S)\), relying on the coefficient-based susceptibility functions defined in Functions.c.
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)\).A
status.yamlfile is also written to output/, reporting a status code and message describing the outcome of the execution.
Postprocessing via Porter:
Output_adapter.py uses the Porter library to convert the combined
.datfile into a standardized CSV file,BQS_eos_output_thermodynamics.csv, together with an accompanying metadata file,BQS_eos_metadata_thermodynamics.yaml, describing the units and structure of each output quantity (\(T\), \(\mu_B\), \(\mu_S\), \(\mu_Q\), densities, pressure, entropy density, pressure derivatives, and speed of sound).
Specifications:
Additional configurations and specifications are provided in OpenAPI_Specifications-BQS_EoS.yaml, which ensures consistency and reproducibility of inputs and outputs across different setups.
Core Function (in EoS_BQS.c)
The EoS_BQS.c file contains the main routine driving the whole computation, relying on Functions.c and shared declarations in Variables.h and Functions.h. Below is an overview of the key components:
Command-line arguments:
The executable accepts two required arguments: the coefficient input file (either the new or legacy Taylor coefficient parametrization) and the intermediate ranges/switchers file generated by the input adapter.
An optional third flag,
-s(or--susc_zero_mu), may be passed to request the computation and export of susceptibilities—and their first- and second-order temperature derivatives—at zero chemical potential, independently of the requested \((\mu_B,\mu_Q,\mu_S)\) grid.
Reading Taylor expansion coefficients:
The coefficients for each Taylor expansion order and susceptibility channel (e.g. \(\chi_{000}\), \(\chi_{200}\), up to mixed higher orders such as \(\chi_{211}\)) are read from the coefficient file into the
parMatrixarray, and dispatched into dedicated per-channel coefficient arrays (CHI000PAR,CHI200PAR, …,CHI112PAR).
Grid construction:
For each requested combination of \(T\), \(\mu_B\), \(\mu_Q\), and \(\mu_S\), the corresponding grid point is constructed from the ranges and step sizes provided by the user.
Thermodynamic quantities (Functions.c):
The susceptibility functions (
CHI000(),CHI200(),CHI020(), etc.) evaluate the Taylor coefficients at a given temperature viacoeff()/coeffprime(), and are combined to compute the pressure, densities, entropy density, energy density, and second-order susceptibilities at each grid point.
Speed of sound:
The isentropic speed of sound is computed from the pressure, entropy, and density derivatives obtained from the Taylor-expanded susceptibilities.
Output writing:
Results at each grid point are written to the combined
.datfile, following the column structure expected by Output_adapter.py.
Workflow Overview
The module’s workflow can be summarized as follows:
Input Validation:
config.yaml and the coefficient input file are validated against the OpenAPI specifications by OpenAPI_Specifications_validator.py; missing parameters are filled with their default values, and invalid inputs halt execution with an informative error message stored in
status.yaml.
Preprocessing:
The validated YAML inputs are converted into intermediate
.dat/text files consumed by the core C executable.
Core Computation:
The EoS_BQS executable computes the requested thermodynamic quantities over the full \((T,\mu_B,\mu_Q,\mu_S)\) grid, using the Taylor expansion scheme, and stores them in a combined
.datfile.
Postprocessing:
The Porter library converts the
.datfile intoBQS_eos_output_thermodynamics.csvalong withBQS_eos_metadata_thermodynamics.yaml, ready for downstream analysis or integration into the broader MUSES framework.
Status Reporting:
At every stage, the
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 OpenAPI validator, 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-BQS_EoS.yaml.
- src/
Contains the core C source files implementing the Taylor expansion scheme.
Key files: EoS_BQS.c, Functions.c.
- include/
Contains the header files defining shared variables and function prototypes used across the C source files.
Key files: Variables.h, Functions.h.
- input/
Contains the user-provided
config.yamland Taylor coefficient input files.
- output/
Stores the generated output files, including
valid_config.yaml, the validated coefficient file, the combined.datfile,BQS_eos_output_thermodynamics.csv, BQS_eos_metadata_thermodynamics.yaml``, andstatus.yaml.
- test/
Contains reference files (under test/Ref_files/) and test scripts (Docker build/execution tests) for validating the module’s functionality.
- MUSES_Wrapper.py
Orchestrates the whole execution of the module, calling the OpenAPI validator, the input adapter, the EoS_BQS executable, and the output adapter in sequence.