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 * 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 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 :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= export EIGEN3_INCLUDE_DIR= 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. 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=/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. 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: #. Passing the `backend` argument to :ref:`Field Layout`. This should be `SERIAL/OMP/CUDA/HIP`. #. 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: is the path to the root OpenFTS directory $ export PYTHONPATH=/build/python:${PYTHONPATH} $ pytest /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 /examples/ --run_slow If built with `-DBUILD_DOCS`, the documentation can be viewed :: firefox build/docs/sphinx/html/index.html