Running and Troubleshooting

Docker

The user should first clone the repo to easily obtain the required files:

git clone https://gitlab.com/nsf-muses/module-holographic-eos/muses-numrelholo.git

Then navigate inside the repo:

cd muses-numrelholo

Choosing a version

The commands below use the v1.4.1 release tag. To run a different version, replace v1.4.1 with the desired release tag (the available tags are listed on the repository’s tags page). The helper scripts described below also accept an IMAGE_TAG environment variable for this purpose.

Building and pulling the image

The user may either pull the released image via:

docker pull registry.gitlab.com/nsf-muses/module-holographic-eos/muses-numrelholo:v1.4.1

or locally build the image via docker:

docker build -t registry.gitlab.com/nsf-muses/module-holographic-eos/muses-numrelholo:v1.4.1 .

For convenience, the repository ships a build_docker.sh helper that builds the image with the correct name and platform flags:

bash build_docker.sh

Validating the configuration

The user can modify the input in the file ./input/config.yaml. They need to specify either “polynomial_hyperbolic” or “muses_parametric” as the model type. They can also modify the model parameters. After the user has made the changes to the input, they can validate the input file with the configuration validator. This validator runs on the host (outside Docker) and therefore needs the Python dependencies installed. We recommend a Python virtual environment to avoid conflicts with your local package installation:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Whenever you need to leave the virtual environment, simply type deactivate. With the dependencies installed, validate the input file via:

python3 ./api/validate_config.py

Running the container

Run the Docker container with the appropriate commands to generate, validate, and run the configuration:

docker run -it --rm -v ./input:/home/eos/bh_eos/input -v ./output:/home/eos/bh_eos/output registry.gitlab.com/nsf-muses/module-holographic-eos/muses-numrelholo:v1.4.1 ./bin/muses_numrelholo.exec ./input/config.yaml

the -v option will mount your local input and output directories as volumes to the container. The container will run the executable and output the results to the output directory. Make sure the config.yaml is in the input directory.

Equivalently, the repository ships a run_docker.sh helper that wraps this command (mounting input/ and output/ and selecting the platform):

bash run_docker.sh

It accepts an optional path to a config file, defaulting to ./input/config.yaml.

Apple Silicon (arm64) machines

The muses-common base image is published only for linux/amd64. On Apple Silicon Macs, building or running it natively raises an InvalidBaseImagePlatform warning and may fail with rosetta error: failed to open elf at /lib64/ld-linux-x86-64.so.2. Pass --platform=linux/amd64 to docker build / docker run so Docker runs the image under emulation (ensure “Use Rosetta for x86/amd64 emulation” is enabled in Docker Desktop). The build_docker.sh and run_docker.sh helpers add this flag automatically on arm64 hosts.

Common Problems

Known Numerical Limitations

Among the transport coefficients, the bulk viscosity (\(\zeta/s\)) can produce undefined values in the range \(\mu_B \ge 750\) MeV and \(T \le 90\) MeV. Some terms in the scalar fluctuation equations for the bulk channel, such as \(1/\phi'\) and \(1/\phi''\), can blow up when the derivatives are nearly zero, which happens for particular choices of initial conditions (\(\phi_0\), \(\Phi_1\)). All unphysical transport values (NaN, Inf, or negative) are automatically replaced with NaN in all output tables (phi0Phi1_lines.csv, spinodal_lines.csv, eos.csv, stable_eos.csv). The equation of state and the remaining transport coefficients such as \(\hat{q}\), \(\sigma_B/T\), the drag force, and the Langevin diffusion coefficients are numerically stable across the full phase diagram.

Who to contact for this module

Mauricio Hippert: hippert@cbpf.br

Yumu Yang: yumuy@illinois.edu