Quickstart

The code can be used locally, in a Docker image, or in the calculation engine. The following sections will explain the first two cases. For the calculation engine, please check the Tutorial.

Local Usage

To download the latest version of the module, type:

git clone https://gitlab.com/nsf-muses/module-cmf/eos-synthesis

Required Libraries

The following libraries are required:

ceres-solver: Ceres is a C++ library for solving large-scale optimization problems.
- Linux: Install using your package manager. For Debian, use:
```
sudo apt-get install libceres-dev
```
- macOS: Install using Homebrew:
```
brew install ceres-solver
```
- Windows: Use Cygwin and follow the steps here.
yaml-cpp: The YAML-cpp library is a YAML parser and emitter for C++.
- Linux: Install using your package manager. For Debian, use:
```
sudo apt-get install libyaml-cpp-dev
```
- macOS: Install using Homebrew:
```
brew install gsl
```
- Windows: Use Cygwin, install CMake, and build yaml-cpp from source:
```
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
```
  After successful compilation, the libyaml-cpp.a file will be created in DESTDIR.
CGAL: CGAL is a software library for computational geometry, which we use for multidimensional interpolation.
- Linux: Install using your package manager. For Debian, use:
```
sudo apt-get install libcgal-dev
```
- macOS: Install using Homebrew:
```
brew install cgal
```
- Windows: Install using vcpkg:
```
vcpkg install cgal
```
Cubature: The Cubature is used for integrations. We adapted it to be a header-only file and it is automatically included in the module.

Python dependencies and additional MUSES libraries such as openapi-core, pyyaml, pandas, MUSES porter, and MUSES comPOSE can be installed by running:

pip install -r requirements.txt

Compilation and Testing

Before compiling the code, run tests to ensure all dependencies are correctly installed:

cd test
bash test_all.sh

If all tests pass, return to the source directory and compile the code:

cd ../src
make

The executable synthesis will be created upon successful compilation.

Running the Module

Set Up Configuration File: Create the config.yaml file using:
```
python3 create_config.py --option1 value1 --option2 value2
```
For available options, refer to the `Open API Specification`_.
Validate Configuration File: Validate and fill in missing variables with default values:
```
python3 validate_config.py
```
Run the C++ Code: Run the executable with:
```
./synthesis
```
If using custom paths, adjust the commands as needed.
Postprocessing: Convert outputs to HDF5 format or other formats:
```
python3 postprocess.py
```

Docker Container

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

docker pull registry.gitlab.com/nsf-muses/eos-synthesis:v0.7.2

Create directories for input and output files:

mkdir -p input output

Run the Docker container with the appropriate commands to generate, validate, and run the configuration as described in the Local Usage section, such as

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