Building OpenFTS
==================

Dependencies
------------

You will need to have the following installed in your computer in order to build OpenFTS:
  
  * A C++11 compatible compiler: g++
  * CMake: cmake
  * FFTW: fftw3-dev
  * Eigen: libeigen3-dev
  * CUDA (optional, GPU support): nvidia-cuda-toolkit
  * Sphinx (optional, documentation): python3-sphinx, python3-sphinx-rtd-theme, python3-nbsphinx
  * Pytest (optional, integration tests): python3-pytest
  * Python modules (optional, for full functionality): numpy, scipy, matplotlib, mdtraj, scikit-image, pandas, gsd, numba

Build Instructions
-------------------

* Clone using git:: 

    git clone --recursive git@github.com:LequieuLab/OpenFTS.git

.. attention::

  Access to the OpenFTS repository is currently private. Contact `Joshua Lequieu <https://www.lequieulab.org/josh-lequieu.html>`_ for access/licensing.
 
.. note::

   OpenFTS has setup `git submodules` in a way that requires the use of SSH keys to authenticate with github. If you don't have these setup, then the submodules will not get cloned correctly.

.. attention::

   By default git will checkout the `master` branch, but all of OpenFTS documentation corresponds to the `develop` branch. If you stick with the `master` branche, you should be aware that certain features described in these docs might not yet be available. 

* Build using cmake::

    cd OpenFTS
    mkdir build && cd build
    cmake ..
    make -j4

A successful build of OpenFTS will generate an executable in `build/src/OpenFTS_serial_dp.x` and will generate the `openfts` python package in `build/python/` (see :ref:`Running OpenFTS` for running using either the executable or the python package). 

Problems with building?
++++++++++++++++++++++++

A common issue with building the code is that `cmake` cannot find your `FFTW` and `Eigen` installations. If you're on a Linux workstation and you have `FFTW` and `Eigen` installed using `apt-get`, OpenFTS will **hopefully** build without issue. If you are on a Linux cluster or a Mac, you will likely need to **(1)** manually locate your FFTW and EIGEN installations, and **(2)** specify where `cmake` looks for these by setting the `FFTW3DIR` and `EIGEN3_INCLUDE_DIR` environmental variables: ::

    export FFTW3DIR=<insert your path to FFTW here>
    export EIGEN3_INCLUDE_DIR=<insert your path to Eigen here>

In order to determine the correct path to your `FFTW`/`Eigen` installations, try looking for the `fftw3.h` and `signature_of_eigen3_matrix_library` files, respectively: ::

  find / -name 'fftw3.h' # for FFTW3. Note that the FFTW3DIR should be one directory up (i.e. '../') relative to this file
  find / -name 'signature_of_eigen3_matrix_library' # for eigen3

If you are on a cluster that uses Environment Modules the `module show` command can also be useful for finding their locations: ::

  # if your cluster's fftw3 module is fftw3/gcc/3.3.10
  module show fftw3/gcc/3.3.10

Once you thinkIf you're not sure what exactly these varibles should be set to, here's the expected content of these two directories: ::

    $ ls $FFTW3DIR
    bin  include  lib  share

    $ ls $EIGEN3_INCLUDE_DIR/
    Eigen  signature_of_eigen3_matrix_library

Once these environmental variables are set, OpenFTS **should** build without issue. You can test if OpenFTS was built propertly by running the unit tests and integration tests as described below.

Build Options
---------------

By default OpenFTS is built to run in serial on the CPU with double precision. To build with GPU, the `ENABLE_GPU` option can be set via::

    cmake .. -DENABLE_GPU=yes 

Note that this will build an executable called `OpenFTS_gpu_dp.x` . The python package will also be built into the same location as before: `build/python`.



A complete list of build options are
  
  * `BUILD_TESTING` - Enables the compilation of unit tests
  * `BUILD_BENCHMARK` - Enables the compilation of benchmarks
  * `ENABLE_GPU` - Compiles for Nvidia GPUs. Default: `OFF`
  * `SINGLE_PRECISION_FIELDS` - Controls precision used in `fieldlib`. Default: `OFF`
  
    * When set to `ON`, all `Field` objects are created with single precision
    * When set to `OFF`, all `Field` objects are created with double precision

  * `BUILD_PYBIND` - Build with python bindings. Default: `ON`
    
    * To use the python module, update the `PYTHONPATH` environment variable to include `build/python/` and issue `import openfts` from within python.

  * `BUILD_DOCS` - Build the documentation. Default: `ON`


.. note::

  If you have installed a custom version of FFTW3, you can point cmake to this installation by setting the bash env variable `FFTW3DIR`. 

If built with `-DBUILD_TESTING`, units tests can be run using: ::

  $ ctest

You can run the integration tests in the `examples/` directory using `pytest`::
  
  # note: <path> is the path to the root OpenFTS directory
  $ export PYTHONPATH=<path>/build/python:${PYTHONPATH}
  $ pytest <path>/examples/

Some examples take a long time to run and `pytest` ignores them by default. To force all tests to run, add the `--run_slow` option ::
 
  $ pytest <path>/examples/ --run_slow

If built with `-DBUILD_DOCS`, the documentation can be viewed  ::

  firefox build/docs/sphinx/html/index.html