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 ```` in the following instructions by the version indicated on the |CE-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-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: 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|_ 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|_ file can be found in the module's |specs|_ 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: .. code-block:: yaml 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= 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 |repo|_ on their local machine, and install the required libraries listed in |requir|_. Start by downloading the |repo|_ on your machine, either by going to the webpage and downloading it manually, or by using the command line:: git clone --depth 1 --branch 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 |cmake_lists|_ 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 |requir|_): - `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 |requir|_, 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 |repo|_. While after downloading the |repo|_ 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 ''''''''''''''''' 1. 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|_ 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. 2. 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: .. code-block:: text 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 .. ------------------- | Fixed variables | ------------------- .. |repo| replace:: HRG EoS module repository .. _repo: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module .. |requir| replace:: **requirements.txt** .. _requir: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/requirements.txt?ref_type=heads .. |config| replace:: **config.yaml** .. _config: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/input/config.yaml?ref_type=heads .. |specs| replace:: OpenAPI specifications .. _specs: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/api/OpenAPI_Specifications-HRG_vdW.yaml?ref_type=heads .. |CE| replace:: CE .. _CE: https://ce.musesframework.io/ .. |CE-registry| replace:: CE modules registry .. _CE-registry: https://ce.musesframework.io/ce/modules/ .. |cmake_lists| replace:: **CMakeLists.txt** .. _cmake_lists: https://gitlab.com/nsf-muses/hadronic-resonance-gas/hrg-eos-module/-/blob/master/CMakeLists.txt?ref_type=heads