Quick Start Guide
-----------------

Calculation Engine
~~~~~~~~~~~~~~~~~~

**TODO**

Docker
~~~~~~

The quickest way to run the Chiral EFT module on your machine is using
the Docker container. Make sure that you have
`Docker <https://www.docker.com/>`__ locally installed on your machine.

The recommended way to obtain the Chiral EFT Docker container is to
pull the latest version from the GitLab Container Registry::

   docker pull registry.gitlab.com/nsf-muses/chiral-eft-eos/chiral_eft_eos:v1.0.1

In order to run this container, you must at least have a minimal project
directory containing an ``input/`` and ``output/`` directory and a
`config.yaml
<https://gitlab.com/nsf-muses/chiral-eft-eos/chiral_eft_eos/-/blob/main/input/config.yaml>`__
containing the module configuration. Then simply run
the container::
   
   export DOCKER_IMAGE_NAME=registry.gitlab.com/nsf-muses/chiral-eft-eos/chiral_eft_eos
   export DOCKER_IMAGE_TAG=v1.0.1
   docker run -it --rm --name chiraleft \
      -v "${PWD}/input:/opt/input" \
      -v "${PWD}/output:/opt/output" \
      $DOCKER_IMAGE_NAME:$DOCKER_IMAGE_TAG make run

The output files will appear in the ``output/`` directory upon completion.

You may also choose to build the Docker image and run it on your machine.
In that case, start by cloning the `Chiral EFT
repository <https://gitlab.com/nsf-muses/chiral-eft-eos/chiral_eft_eos>`__
and building the Docker image::

   git clone git@gitlab.com:nsf-muses/chiral-eft-eos/chiral_eft_eos.git
   export DOCKER_IMAGE_NAME=chiraleft
   export DOCKER_IMAGE_TAG=dev
   cd chiral_eft_eos
   docker build -t $DOCKER_IMAGE_NAME:$DOCKER_IMAGE_TAG .

If the `MUSES common container <https://gitlab.com/nsf-muses/common>`__
needs to be updated type::
   
   docker pull registry.gitlab.com/nsf-muses/common/muses-common:latest

To run the container, first make sure that you have created a
`config.yaml
<https://gitlab.com/nsf-muses/chiral-eft-eos/chiral_eft_eos/-/blob/main/input/config.yaml>`__
containing the module configuration in the ``input/`` directory. Then run::

   bash run_docker.sh $DOCKER_IMAGE_NAME $DOCKER_IMAGE_TAG

The output files will appear in the
`output/
<https://gitlab.com/nsf-muses/chiral-eft-eos/chiral_eft_eos/-/blob/main/output>`__
directory upon completion.

Locally (without Docker)
~~~~~~~~~~~~~~~~~~~~~~~~

Dependencies (C++)
^^^^^^^^^^^^^^^^^^

The module can also be compiled and executed locally without using
Docker. To compile the C++ module, the following libraries are
required:

- `yaml-cpp <https://github.com/jbeder/yaml-cpp>`__

   To build from source, make sure you have ``CMAKE`` installed,
   then clone and build the ``yaml-cpp`` project with::

      git clone https://github.com/jbeder/yaml-cpp.git
      cd yaml-cpp
      mkdir build
      cd build
      cmake -DYAML_BUILD_SHARED_LIBS=OFF ..
      make
      make DESTDIR=/desired/path/to/installation install
   
   The file ``libyaml-cpp.a`` will be created upon successful
   compilation in ``DESTDIR``.

   For macOS, use `Homebrew <https://formulae.brew.sh/>`__
   `brew install yaml-cpp`. For Linux, use your package manager, for
   instance, in Debian use `sudo apt-get install libyaml-cpp-dev` or
   install from source using the instructions detailed above.

- `doctest <https://github.com/doctest/doctest>`__

   To build from source, make sure you have ``CMAKE`` installed,
   then clone and build the ``doctest`` project with::

      git clone https://github.com/doctest/doctest.git
      cd doctest
      cmake .
      make DESTDIR=/desired/path/to/installation install
   
   the header file ``doctest.h`` will be created upon successful compilation in
   DESTDIR/PREFIX, the default PREFIX is /usr/local/.

   For macOS, use `Homebrew <https://formulae.brew.sh/>`__
   `brew install doctest`. For Linux, use your package manager, for
   instance, in Debian use `sudo apt-get install doctest-dev` or
   install from source using the instructions detailed above.

Also required is an up-to-date `GNU GCC Compiler <https://gcc.gnu.org/>`__
and `make <https://www.gnu.org/software/make/>`__.

How to Build
^^^^^^^^^^^^

After successful installation of the required libraries, simply write::

   git clone https://gitlab.com/nsf-muses/chiral-eft-eos/chiral_eft_eos
   cd chiral_eft_eos/src
   make

The executable ``chiraleft`` will be created upon successful compilation
and linking. Note that if the libraries are not installed in the default
``PATH``, the
`Makefile <https://gitlab.com/nsf-muses/chiral-eft-eos/chiral_eft_eos/-/blob/main/src/Makefile>`__
will need to be modified, specifically in the ``-I`` flag for includes
in ``CXXFLAGS`` and the ``-L`` flag for libraries in ``LDFLAGS``.

Dependencies (Python)
^^^^^^^^^^^^^^^^^^^^^

In order to run the module locally, the local machine must have an up-to-date
version of `python3 <https://www.python.org/>`__ installed, including the
following packages:

- `numpy <https://numpy.org/>`__
- `scipy <https://scipy.org/>`__
- `pandas <https://pandas.pydata.org/>`__
- `pyyaml <https://pyyaml.org/>`__
- `openapi-core <https://github.com/python-openapi/openapi-core>`__
- `muses_porter <https://gitlab.com/nsf-muses/common/-/tree/main/Porter>`__

These libraries can all be easily installed using ``pip`` package manager.
To install the MUSES Porter library with ``pip``, see the Porter
`README <https://gitlab.com/nsf-muses/common/-/tree/main/Porter/README.md>`__.

How to Run
^^^^^^^^^^

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
<https://gitlab.com/nsf-muses/chiral-eft-eos/chiral_eft_eos/-/blob/main/input/config.yaml>`__
containing the module configuration in the ``input/`` directory. Then run::

   cd chiral_eft_eos/
   bash run_local.sh

The output files will appear in the
`output/ <https://gitlab.com/nsf-muses/chiral-eft-eos/chiral_eft_eos/-/blob/main/output>`__
directory upon completion.