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 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:v0.7.3

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 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=v0.7.3
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 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 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 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/ 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

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

  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 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 and 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 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 installed, including the following packages:

• numpy

• pandas

• pyyaml

• openapi-core

• muses_porter

These libraries can all be easily installed using pip package manager. To install the MUSES Porter library with pip, see the Porter README.

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 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/ directory upon completion.