Running and Troubleshooting
---------------------------

Docker
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: bash

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

Then navigate inside the repo:

.. code-block:: bash

   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
<https://gitlab.com/nsf-muses/module-holographic-eos/muses-numrelholo/-/tags>`_).
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:

.. code-block:: bash

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

or locally build the image via docker:

.. code-block:: bash

   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:

.. code-block:: bash

   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:

.. code-block:: bash

   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:

.. code-block:: bash

   python3 ./api/validate_config.py

Running the container
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: bash

   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):

.. code-block:: bash

   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 (:math:`\zeta/s`) can produce
undefined values in the range :math:`\mu_B \ge 750` MeV and :math:`T \le 90` MeV.
Some terms in the scalar fluctuation equations for the bulk channel, such as
:math:`1/\phi'` and :math:`1/\phi''`, can blow up when the derivatives are nearly zero,
which happens for particular choices of initial conditions (:math:`\phi_0`, :math:`\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 :math:`\hat{q}`, :math:`\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