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

Requirements
-----------------

* Global requirements:

  * **gcc compiler** (tested with 7.4.0)
  * **cmake** (version 3.0 or higher)

* For the **python frontend**:

  * **python3**, with numpy and scipy:
    The library was tested with python3.4 and newer.
  * **python3-config**:
    This program should be included in the python 3 developer package of your Linux distribution, or is shipped with other python distributions such as ana/mini-conda).
  * **pybind11**: Code for this is included in the library.

* For the **SparseSinkhorn** algorithm module:

  * **eigen3** library headers:
    These can be installed via package manager on most distributions, e.g. via package libeigen3-dev on Ubuntu.

* For the **ShortCut** algorithm module (this part is currently not documented):

  * CPLEX or lemon linear programming solver libraries


Via pip
-------------

The easiest way for installation of the python frontend is via the Python package installer (pip).
This will currently only give you access to the SparseSinkhorn solver.

* Run the following command in the terminal::

    <python3 executable> -m pip install MultiScaleOT

  Here <python3 executable> has to be replaced by the python3 executable.

Compilation from source
------------------------

* Open a terminal in a suitable (empty) folder.
* Checkout the git repository from github::

    git clone https://github.com/bernhard-schmitzer/MultiScaleOT
  
  Alternatively the code can be downloaded with a browser and unpacked manually.
    
* Move into the library main directory, create build directory and move into this::

    cd MultiScaleOT
    mkdir build
    cd build

* Use cmake and make to build the library::

    cmake ../src -DPYTHON_EXECUTABLE=<python3 executable>
    make install

  Here <python3 executable> has to be replaced by the python3 executable.

* By default this builds the SparseSinkhorn algorithm module and the pybind11 front end. Configuration of the ShortCut algorithm module with CPLEX or the lemon library is currently not documented. If you want to learn more about this, feel free to contact me.

  * The python module is placed in *MultiScaleOT/python*. This can be imported as usual.
  * Some additional static libraries are placed in *MultiScaleOT/bin*,
  * some headers in *MultiScaleOT/include*,
  * and some pure C++ examples in *MultiScaleOT/examples*.

.. _installation-google-colab:

Google colab
-------------------

It is possible to install and test the library on `Google colab <https://colab.research.google.com/>`_. For this, run the following commands in the python notebook:

* Install **eigen3** library headers::

    !apt install libeigen3-dev

* Install **MultiScaleOT** via pip::

    !pip install MultiScaleOT

After this you should be able to test some of the :doc:`examples <auto_examples/index>`.

..
    use_cplex
    CPLEX_LIBRARY: Location of CPLEX binaries for linking
    CPLEX_INCLUDE_DIRECTORY: Location for CPLEX headers for compilation

..
    use_lemon
    LEMON_LIBRARY "" CACHE FILEPATH "Location of LEMON binaries for linking")
    LEMON_INCLUDE_DIRECTORY "" CACHE PATH "Location of LEMON headers for compilation")