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

  • HDF5 (optional, for binary field output):

  • CUDA (optional, Nvidia GPU support): nvidia-cuda-toolkit

  • HIP (optional, AMD GPU support): rocm

  • 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

Be sure that you’re reading the documentation that corresponds to the version of the code that you’re building

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

If 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

If you choose to build with OpenMP support (ENABLE_OMP=yes) and/or floating point support (SINGLE_PRECISION_FIELDS=yes), you will need to be sure that that the FFTW3DIR/lib directory contains the OMP and/or floating precision libraries. For example:

$ ls $FFTW3DIR/lib/
cmake         libfftw3f_omp.a     libfftw3f_omp.so.3.6.10  libfftw3.la      libfftw3_omp.so.3       libfftw3.so.3.6.10
libfftw3.a    libfftw3f_omp.la    libfftw3f.so             libfftw3_omp.a   libfftw3_omp.so.3.6.10  pkgconfig
libfftw3f.a   libfftw3f_omp.so    libfftw3f.so.3           libfftw3_omp.la  libfftw3.so
libfftw3f.la  libfftw3f_omp.so.3  libfftw3f.so.3.6.10      libfftw3_omp.so  libfftw3.so.3

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.2.2. Building FFTW

If you choose to build FFTW from scratch on your machine, you will generally follow the instructions at https://fftw.org/fftw3_doc/Installation-on-Unix.html#Installation-on-Unix

To work with OpenFTS, FFTW should be compiled using

./configure --enable-shared --enable-openmp --enable-float --prefix=<path to fftw3>/fftw3
make

Depending on your hardware, the SIMD flags (e.g. –enable-sse) should be included and can lead to a considerable increase in performance.

1.3. Build Options

By default OpenFTS is built to run only in serial on the CPU with double precision. Support for running on Nvidia GPUs (CUDA), AMD GPUs (HIP) and multiple CPUs (OpenMP) is also available. In OpenFTS lingo these are called different “backends”. To enable the CUDA backend, use the ENABLE_CUDA option:

cmake .. -DENABLE_CUDA=yes

Any combination of SERIAL, OMP and CUDA/HIP backends can be enabled. The only restriction is that only either CUDA or HIP are allowed (both are not). For example, to compile a code that can be run using SERIAL, CUDA or OMP

cmake .. -DENABLE_SERIAL=yes -DENABLE_CUDA=yes -DENABLE_OMP=yes

Note

If multiple backends are specified, you can specify the backend you prefer by:

  1. Passing the backend argument to Field Layout. This should be SERIAL/OMP/CUDA/HIP.

  2. Set the FIELDLIB_BACKEND environmenal variable (e.g. export FIELDLIB_BACKEND=CUDA)

If neither of these are specified the code will choose a backend for you.

A complete list of build options are

  • BUILD_TESTING - Enables the compilation of unit tests

  • BUILD_BENCHMARK - Enables the compilation of benchmarks

  • ENABLE_SERIAL - Enable running in serial on CPU. Default: ON

  • ENABLE_OMP - Enable running in parallel on CPU using OpenMP. Default: OFF

  • ENABLE_CUDA - Enable running on Nvidia GPUs using CUDA. Default: OFF

  • ENABLE_HIP - Enable running on AMD GPUs using HIP. Default: OFF

  • ENABLE_HDF5 - Enable output of fields in HDF5 format. 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

  • SPHINX_MULTIVERSION - Build the documentation using sphinx-multiversion. Note that if docs will not be built for uncommitted code. Default: OFF

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