Quickstart
==================

The code can be used locally, in a Docker image, or in the Calculation Engine. The following sections will explain how to run it both manually and in a Docker container.
For the Calculation Engine, please check the `Tutorial <https://musesframework.io/docs/user/tutorial/Readme.html>`_.

Manual build and run
-----------------------

Navigate to directory ``man_build`` and execute the Bash script ``build_debug`` (``build_release``) to build executables in **DEBUG** (**RELEASE**) mode (**DEBUG** mode is very slow). The executables are placed in the folder ``debug`` or ``release``, depending on the build mode.

To execute the program, e.g. ``run_muses.py``, navigate to the ``source`` folder and run:

.. To execute the program, e.g. ``muses``, navigate to the ``release`` folder and run:

.. .. code-block:: bash

..    ./muses <path_to_config.yaml>

.. The ``muses`` program takes an input YAML file with a specific format as a required argument. An example is given in ``input/config.yaml``. From the ``release`` folder, the program can be run with this input file using:

.. .. code-block:: bash

..    ./muses ../input/config.yaml

.. code-block:: bash

   cd ../source && python3 run_muses.py

The output is a ``.csv`` file with the name specified in ``config.yaml`` and is placed in the ``output`` folder.

.. What the ``muses`` program does
.. -------------------------------

.. The ``muses`` program solves the gap equations for a specified thermodynamic phase to calculate the mean-field results (expectation values of the fields) and thermodynamic quantities such as the pressure, particle number densities, etc.

Structure of the code
~~~~~~~~~~~~~~~~~~~~~~~

The module iterates over temperature or a specified chemical potential on a grid specified by the user, solving the gap equations and neutrality constraints self-consistently using multi-dimensional root finding.

Depending on the phase specified in the input file, the starting values are used as an initial guess for the root finder for the first calculated point (``iterate_central``). If ``inherit_starting_values`` is set to ``true`` in the input file, the result of the root finder—if successful—is used as the initial guess for the next point in the phase diagram.

The root finder uses the multiroot routine from the GNU Scientific Library (GSL). All internal calculations are performed in dimensionless units. Thermodynamic quantities for the output file are calculated from the found root (mean-field values of the condensates). After the iteration is completed, the results are transformed back to physical units and stored in the output folder.

Post-processing the output file and input for other MUSES modules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


``run_muses.py`` automatically runs the post-processing script ``clean_pd.py``, which creates the files ``clean.csv``, ``phases_selected.csv`` and ``eos.csv`` from the original output file. It assumes that the original output file exists. It is called as follows:

.. code-block:: bash

   python3 clean_pd.py <folder> <filename> <configuration_keyword>

with the name of the folder created in ``output`` (``<folder>``), the ``<filename>`` of the original output file, and a ``<configuration_keyword>`` that is either ``T_mu`` (for already electrically neutral matter) or ``T_mu_mu_Q`` (if the electric charge chemical potential :math:`\mu_Q` is used as a free variable).

In ``clean.csv``, points where the root finder returned an unsuccessful flag are deleted. In ``phases_selected.csv``, the neutral phase with the higher pressure is selected at every quark chemical potential, strangeness chemical potential, and temperature (when called with the ``T_mu`` flag), or the phase with higher pressure at every quark chemical potential, strangeness chemical potential, temperature, and charge chemical potential (when called with the ``T_mu_mu_Q`` flag), respectively.

``eos.csv`` is a tabulated EoS input file for the MUSES modules **QLIMR**, **leptons**, and **synthesis**. It is calculated from ``phases_selected.csv``.

Docker Container
~~~~~~~~~~~~~~~~

To use the NJL module via Docker, pull the released image:

.. code-block:: bash

    docker pull registry.gitlab.com/nsf-muses/njl:MUSES

One can build the Docker image locally:

.. code-block:: bash

    docker build registry.gitlab.com/nsf-muses/njl:MUSES .

After one changes the ``config.yaml`` to desired, run the following command to access the Docker container:

.. code-block:: bash

    docker run -it --rm -v ./input:/opt/input -v ./output:/opt/output registry.gitlab.com/nsf-muses/njl:MUSES bash

where the ``-v`` option will mount your local input and output directories as volumes to the container. 

Run the following command to validate the config file:

.. code-block:: bash

    cd open-API/ && python3 OpenAPI_validator.py openapi.yaml ../input/config.yaml

If the config file passes the validation, run the following to generate the output:

.. code-block:: bash

    cd ../source/ && python3 run_muses.py

After the outputs are successfully generated, the user can exit the container, and the outputs should be in local ``output`` folder:

.. code-block:: bash

    exit