Quickstart

In this section, you will find information on how to quickly run this module after a few simple steps.

In order to use the most up-to-date function version of the 4D-TExS EoS 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 4D-TExS EoS module on the MUSES CE, refer to the user manual’s Quick Start Guide to find instructions and exemples on how to submit jobs and retrieve the run outputs.

4D-TExS EoS module’s characteristics to know when running on CE:

Name: 'eos_texs_4d' is the name of the module in the CE modules registry

Locally

Using Docker

The quickest way to run the 4D-TExS 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 BQS EoS Docker container is to pull the latest version from the GitLab Container Registry:

docker pull registry.gitlab.com/nsf-muses/4d-texs/4D-TExS:{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 and 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 is also provided below.

parameters:
  T_min: 30.0
  T_max: 500.
  dT: 7.5
  mu_B_min: -600.0
  mu_B_max: 600.0
  dmu_B: 50.0
  mu_Q_min: -500.0
  mu_Q_max: 500.0
  dmu_Q: 50.0
  mu_S_min: -400.0
  mu_S_max: 400.0
  dmu_S: 50.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

Once you have defined the parameters of your choice, you can run the container:

export DOCKER_IMAGE_NAME=registry.gitlab.com/nsf-muses/4d-texs/4d-texs
export DOCKER_IMAGE_TAG=<TAG>
docker run -it --rm --name 4DTExS \
   -v "${PWD}/input:/opt/input" \
   -v "${PWD}/output:/opt/output" \
   $DOCKER_IMAGE_NAME:$DOCKER_IMAGE_TAG python src/main.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 4D-TExS EoS repository on their local machine, and install the required libraries listed in requirements.txt.

Start by downloading the 4D-TExS EoS repository on your machine, either by going to the webpage and downloading it, or by using the command line:

git clone --depth 1 --branch <TAG> https://gitlab.com/nsf-muses/4d-texs/4D-TExS.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 the GSL libraries installed to compile and build the core code of the module written in C.

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

numpy
pyyaml
openapi-core
muses_porter

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 4D-TExS/requirements.txt

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

2. Compile and build

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

cd 4D-TExS/
make

The executable 4DTExS_EoS will be created upon successful compilation and linking.

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

2. Alternatively, you can run the source coode directly using the executable 4DTExS_EoS:

./4DTExS_EoS input/input_ranges.dat