Building from source#

To build the FastDDM Python package from source:

  1. Install prerequisites

  2. Obtain the source

  3. Configure

  4. Build and install the package

  5. Test the package

To build the documentation from source (optional):

  1. Install prerequisites

  2. Build the documentation

Install prerequisites#

FastDDM requires a number of tools and libraries to build. The options ENABLE_CPP and ENABLE_CUDA each require additional softwares/libraries when enabled.

Tip

Create a virtual environment, one place where you can install dependencies and FastDDM:

$ python3 -m venv fastddm-venv

You will need to activate your environment before configuring FastDDM:

$ source fastddm-venv/bin/activate

General requirements:

  • Python >= 3.8

  • Pip

  • C++14 capable compiler (tested with gcc [Ubuntu], clang [MacOS], and msvc [Windows])

Make sure that Python is available from your PATH. Follow the instructions below to obtain the compiler for your system.

gcc can be installed by running from the terminal:

$ sudo apt update
$ sudo apt install build-essentials

If you are using other Linux distros, look for the appropriate package and package manager. Ensure that the compiler was succesfully installed by running:

$ g++ --version

Warning

If the installation fails, delete the build and fastddm.egg-info directories created by the installer before making a new attempt! This ensures that CMake generates fresh makefiles.

For GPU execution (required when ENABLE_CUDA=ON):

First and foremost, you will need a CUDA-capable GPU. Check your hardware compatibility on the NVIDIA website. Follow the instructions available from the website specific to your OS. Notice that CUDA is not available for MacOS.

To build the documentation:

  • sphinx

  • nbsphinx

  • sphinx-tabs

  • ipython

  • matplotlib

  • furo

To run the unit-tests:

  • pytest

  • pytest-regtest

Obtain the source#

Clone using Git:

$ git clone https://github.com/somexlab/fastddm.git

Release tarballs are also available as GitHub release assets.

Configure#

FastDDM’s cmake configuration accepts a number of options that you can use to customize your installation. For example, you can enable the C++ and/or CUDA core, or select single precision calculation. These options must be set before installation.

  • ENABLE_CPP - When enabled, build the core C++ library (default: OFF).

  • ENABLE_CUDA - When enabled, build the core CUDA library (default: OFF). If ON, ENABLE_CPP will be set to ON automatically.

  • SINGLE_PRECISION - Enable single precision output (default: OFF).

ENABLE_CUDA is available for Linux and Windows only. SINGLE_PRECISION can give advantages on laptops or systems with small RAM size.

Options can be set through the terminal by running the following command:

$ export <variable>=<value>

For example, to set ENABLE_CPP use:

$ export ENABLE_CPP=ON

Build and install the package#

To build and install from source, run the following command in a terminal from within the source directory:

$ pip3 install .

To install also the dependencies for test, run this command instead:

$ pip3 install .[test]

Warning

In some cases, notably on Windows and using Z shell on other systems as well, you need to run alternatively:

$ pip3 install ."[test]"

To install the optional dependencies to build the documentation, use the option doc. If you want to install both, separate the options using a comma, for example:

$ pip3 install .[test,doc]

Test the package#

To test the installation, start python and try importing the package:

import fastddm
fastddm.__version__

To run the unit-tests, run the following command from within the source directory (NOTICE: you need to install the test dependencies):

$ pytest -v

Build the documentation#

To build the documentation, run the following command from within the source directory:

$ sphinx-build -b html docs/source/ docs/build/html