Quickstart

In this section, you will find information on how to quickly run the HRG EoS Module after a few simple steps, either on the MUSES Calculation Engine (CE) or locally using Docker.

In order to use the most up-to-date version of the HRG module, replace <TAG> in the following instructions by the version indicated on the CE modules registry webpage.

On the Calculation Engine (CE)

In order to run the HRG EoS module on the MUSES CE, refer to the user manual’s Quick Start Guide to find instructions and examples on how to submit jobs and retrieve the run outputs via Python scripts.

HRG EoS module’s characteristics to know when running on CE via Python scripts:

Name: eos_hrg is the name of the module in the CE modules registry

In addition, MUSES now has a Graphical User Interface (GUI) that allows users to run modules on the CE without the need for Python scripts. To run the HRG EoS module through the GUI, refer to the MUSES GUI Tutorial for instructions and examples.

Locally

Using Docker

The quickest way to run the HRG EoS module on your machine is by using the Docker container. First, make sure that you have Docker locally installed on your machine.

1. Pull Docker image

The recommended way to obtain the HRG EoS Docker container is to pull the latest version from the GitLab Container Registry:

docker pull registry.gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module:<TAG>

2. Run the module from the container

In order to run this container, you must at least have a minimal project directory, with an input/ folder containing a config.yaml file that is used to define the module’s parameters for the run, and an output/ folder. More information about the content of the config.yaml file can be found in the module’s OpenAPI specifications and can be changed based on the user’s requirements. A code block for how the config.yaml file should look like for the HRG EoS module to compute a table of thermodynamic quantities at varying temperatures and chemical potentials is provided below:

HRG_parameters:
   a: 0.329
   b: 3.42
   bm: 0.1
   interacting-pions: true
parameters:
   T_min: 0.0
   T_max: 150.0
   dT: 75.0
   mu_B_min: 0.0
   mu_B_max: 300.0
   dmu_B: 300.0
   mu_Q_min: 0.0
   mu_Q_max: 100.0
   dmu_Q: 100.0
   mu_S_min: 0.0
   mu_S_max: 200.0
   dmu_S: 200.0
switchers:
   get_P: true
   get_E_dens: true
   get_s_dens: true
   get_B_dens: true
   get_Q_dens: true
   get_S_dens: true
   get_PressHessianMatrix: true

Once you have defined the parameters of your choice, you can run the container, by executing the wrapper inside while connecting the input/ and output/ folders inside the container to your own input/ and output/ local folders:

export DOCKER_IMAGE_NAME=registry.gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module
export DOCKER_IMAGE_TAG=<TAG>
docker run -it --rm --name HRG \
   --platform linux/amd64 \
   --user "$(id -u):$(id -g)" \
   -v "${PWD}/input:/opt/input" \
   -v "${PWD}/output:/opt/output" \
   $DOCKER_IMAGE_NAME:$DOCKER_IMAGE_TAG \
   python3 MUSES_Wrapper.py input/config.yaml

The output files will appear in the output/ directory upon completion.

Without Docker

In order to run the module without Docker, one has to copy the HRG EoS module repository on their local machine, and install the required libraries listed in requirements.txt.

Start by downloading the HRG EoS module repository on your machine, either by going to the webpage and downloading it manually, or by using the command line:

git clone --depth 1 --branch <TAG> https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module.git

1. Install required packages

In order to run the module locally, the local machine must have an up-to-date version of the GCC compiler, as well as an installation of OpenMP (typically provided via the libgomp package on Linux distributions), which is required by CMakeLists.txt to build the core executable.

If you are willing to run the module locally, you also need an up-to-date version of python3 installed, including the following packages (listed in requirements.txt):

numpy
pyyaml
jsonschema
openapi-core
muses_porter (v0.2.0)

Note: we do recommend the use of a Python virtual environment to avoid potential conflicts with your local package installation. To create and activate a virtual environment, execute the following commands:
```
python3 -m venv .venv
source .venv/bin/activate
```
Whenever you need to deactivate the virtual environment, simply type deactivate.

These libraries can all be easily installed using the pip package manager. Moreover, one can proceed by calling directly requirements.txt, using:

pip install --user -r hrg-eos-module/requirements.txt

If the installation of the Porter fails by this method, see more detailed instructions in the Porter README.

2. Download the Thermal-FIST submodule

In order to compile the core code of the module, you need to have the Thermal-FIST package downloaded on your machine, which is defined as a Git submodule included in the HRG EoS module repository.

While after downloading the HRG EoS module repository you should have a folder named Thermal-FIST/ in the main directory, this folder is empty until you run the submodule.sh script:

./submodule.sh

which will initialize the submodule and check it out to the correct version (v1.6).

3. Compile and build

After successful installation of the required libraries and submodule, you need to compile and build the core code of the module:

cd build
cmake ..
make hrg-eos-thermodynamics -j
cd ..; mv build/hrg-eos-thermodynamics .

The executable hrg-eos-thermodynamics will be created upon successful compilation and linking.

4. Run the module

Once all of the dependencies are successfully installed, and the project has been compiled, all that’s left to do is run the module.

First make sure that you have created a config.yaml file containing the module configuration in the input/ directory. Then run:

python3 MUSES_Wrapper.py input/config.yaml

The output files will appear in the output/ directory upon completion.

Alternatively, you can run the source code directly using the executable hrg-eos-thermodynamics:
```
./hrg-eos-thermodynamics input/input_ranges.dat output/HRG_table.txt
```

where the file input_ranges.dat should have the following format:

T       0.0     0.150  0.075
mu_B    0.0     0.300  0.300
mu_Q    0.0     0.100  0.100
mu_S    0.0     0.200  0.200

To consult the list of flags to set the van der Waals parameters, switchers and other options, run the executable with the --help flag:

./hrg-eos-thermodynamics --help