.. _installation:

Installation
============

C++ Build
---------

Dependencies
~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Library
     - Purpose
   * - `Ceres Solver <http://ceres-solver.org/>`_
     - Non-linear least squares (Gibbs construction, statistical mixture)
   * - `yaml-cpp <https://github.com/jbeder/yaml-cpp>`_
     - YAML configuration parsing
   * - `CGAL <https://www.cgal.org/>`_
     - Multidimensional (Delaunay) interpolation
   * - `Cubature <https://github.com/stevengj/cubature>`_
     - Numerical integration (header-only, bundled with the module)
   * - `GoogleTest <https://github.com/google/googletest>`_
     - Unit tests only

On Debian/Ubuntu:

.. code-block:: bash

   apt-get install g++ make libceres-dev libyaml-cpp-dev libcgal-dev libgtest-dev

On macOS, via Homebrew:

.. code-block:: bash

   brew install ceres-solver gsl cgal

On Windows, use `Cygwin <https://www.cygwin.com/>`_. Ceres can be installed following the
steps `here <http://ceres-solver.org/installation.html#windows>`_; yaml-cpp must be built
from source:

.. code-block:: bash

   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

and CGAL installed via `vcpkg <https://vcpkg.io/en/>`_ (``vcpkg install cgal``).

Building from source
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

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

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

.. code-block:: bash

   cd test
   bash test_all.sh

If all tests pass, compile the code:

.. code-block:: bash

   cd ../src
   make

The compiled binary is ``src/synthesis``.

Docker
------

A pre-built image is available on the MUSES GitLab registry:

.. code-block:: bash

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

Create directories for input and output files:

.. code-block:: bash

   mkdir -p input output

.. code-block:: bash

   docker run -it --rm -v $(pwd)/input:/opt/input -v $(pwd)/output:/opt/output \
       registry.gitlab.com/nsf-muses/eos-synthesis:latest ./synthesis

The ``-v`` options mount your local input and output directories as volumes in the
container. Make sure ``config.yaml`` and the input EoS files are in the input directory
before running, and run the pre/post-processing scripts described in the
:ref:`quickstart` as needed.

To build the image locally from the provided Dockerfile instead:

.. code-block:: bash

   docker build -t eos-synthesis .

Python utilities (optional)
----------------------------

The config generation, validation, and postprocessing scripts require Python:

.. code-block:: bash

   pip install -r requirements.txt

This installs ``openapi-core``, ``pyyaml``, ``pandas``, and the MUSES ``porter`` and
``compose`` libraries used by ``postprocess.py``.