1. Building OpenFTS

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

1.2. 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 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 Running OpenFTS for running using either the executable or the python package).

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

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