Quickstart

The code can be used locally, in a Docker image, or in the Calculation Engine. The following sections will explain how to run it both manually and in a Docker container. For the Calculation Engine, please check the Tutorial.

Manual build and run

Navigate to directory man_build and execute the Bash script build_debug (build_release) to build executables in DEBUG (RELEASE) mode (DEBUG mode is very slow). The executables are placed in the folder debug or release, depending on the build mode.

To execute the program, e.g. run_muses.py, navigate to the source folder and run:

cd ../source && python3 run_muses.py

The output is a .csv file with the name specified in config.yaml and is placed in the output folder.

Structure of the code

The module iterates over temperature or a specified chemical potential on a grid specified by the user, solving the gap equations and neutrality constraints self-consistently using multi-dimensional root finding.

Depending on the phase specified in the input file, the starting values are used as an initial guess for the root finder for the first calculated point (iterate_central). If inherit_starting_values is set to true in the input file, the result of the root finder—if successful—is used as the initial guess for the next point in the phase diagram.

The root finder uses the multiroot routine from the GNU Scientific Library (GSL). All internal calculations are performed in dimensionless units. Thermodynamic quantities for the output file are calculated from the found root (mean-field values of the condensates). After the iteration is completed, the results are transformed back to physical units and stored in the output folder.

Post-processing the output file and input for other MUSES modules

run_muses.py automatically runs the post-processing script clean_pd.py, which creates the files clean.csv, phases_selected.csv and eos.csv from the original output file. It assumes that the original output file exists. It is called as follows:

python3 clean_pd.py <folder> <filename> <configuration_keyword>

with the name of the folder created in output (<folder>), the <filename> of the original output file, and a <configuration_keyword> that is either T_mu (for already electrically neutral matter) or T_mu_mu_Q (if the electric charge chemical potential \(\mu_Q\) is used as a free variable).

In clean.csv, points where the root finder returned an unsuccessful flag are deleted. In phases_selected.csv, the neutral phase with the higher pressure is selected at every quark chemical potential, strangeness chemical potential, and temperature (when called with the T_mu flag), or the phase with higher pressure at every quark chemical potential, strangeness chemical potential, temperature, and charge chemical potential (when called with the T_mu_mu_Q flag), respectively.

eos.csv is a tabulated EoS input file for the MUSES modules QLIMR, leptons, and synthesis. It is calculated from phases_selected.csv.

Docker Container

To use the NJL module via Docker, pull the released image:

docker pull registry.gitlab.com/nsf-muses/njl:MUSES

One can build the Docker image locally:

docker build registry.gitlab.com/nsf-muses/njl:MUSES .

After one changes the config.yaml to desired, run the following command to access the Docker container:

docker run -it --rm -v ./input:/opt/input -v ./output:/opt/output registry.gitlab.com/nsf-muses/njl:MUSES bash

where the -v option will mount your local input and output directories as volumes to the container.

Run the following command to validate the config file:

cd open-API/ && python3 OpenAPI_validator.py openapi.yaml ../input/config.yaml

If the config file passes the validation, run the following to generate the output:

cd ../source/ && python3 run_muses.py

After the outputs are successfully generated, the user can exit the container, and the outputs should be in local output folder:

exit