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.

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

  2. Configuration Validation:

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

  4. 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 parMatrix array, 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.

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

    • A status.yaml file is also written to output/, reporting a status code and message describing the outcome of the execution.

  6. Postprocessing via Porter:

    • Output_adapter.py uses the Porter library to convert the combined .dat file 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).

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

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

  2. 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 parMatrix array, and dispatched into dedicated per-channel coefficient arrays (CHI000PAR, CHI200PAR, …, CHI112PAR).

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

  4. Thermodynamic quantities (Functions.c):

    • The susceptibility functions (CHI000(), CHI200(), CHI020(), etc.) evaluate the Taylor coefficients at a given temperature via coeff()/coeffprime(), and are combined to compute the pressure, densities, entropy density, energy density, and second-order susceptibilities at each grid point.

  5. Speed of sound:

    • The isentropic speed of sound is computed from the pressure, entropy, and density derivatives obtained from the Taylor-expanded susceptibilities.

  6. Output writing:

    • Results at each grid point are written to the combined .dat file, following the column structure expected by Output_adapter.py.

Workflow Overview

The module’s workflow can be summarized as follows:

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

  2. Preprocessing:

    • The validated YAML inputs are converted into intermediate .dat/text files consumed by the core C executable.

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

  4. Postprocessing:

    • The Porter library converts the .dat file into BQS_eos_output_thermodynamics.csv along with BQS_eos_metadata_thermodynamics.yaml, ready for downstream analysis or integration into the broader MUSES framework.

  5. Status Reporting:

    • At every stage, the 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:

  • api/

    Contains the OpenAPI specifications, the OpenAPI validator, the input adapter converting YAML to .dat, and the output adapter converting .dat to 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.yaml and Taylor coefficient input files.

  • output/

    Stores the generated output files, including valid_config.yaml, the validated coefficient file, the combined .dat file, BQS_eos_output_thermodynamics.csv, BQS_eos_metadata_thermodynamics.yaml``, and status.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.