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

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

Warning

Check the compatibility of your compiler with the CUDA Toolkit version you are installing.

Note

The CUDA Toolkit is not available for MacOS. If you are using a Mac, you can skip this step.

If you have several NVCC compilers installed and face issues while building wheels you might have to set the CUDACXX environment variable with the path of the nvcc compiler.

$ export CUDACXX=/path/to/nvcc

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.

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]

Configure

FastDDM’s cmake configuration accepts a number of options that you can use to customize your installation from source:

  • 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 is also enabled automatically.

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

Note

ENABLE_CUDA is available for Linux and Windows only.

Tip

SINGLE_PRECISION can give advantages on laptops or systems with small RAM size.

Options can be set by giving extra arguments to the pip command. To enable any of the options, add --config-settings=cmake.define.<OPTION>=<VALUE>. For example, to enable the C++ core and single precision math, run:

$ pip3 install . --config-settings=cmake.define.ENABLE_CPP=ON --config-settings=cmake.define.SINGLE_PRECISION=ON

To enable the CUDA core, run:

$ pip3 install . --config-settings=cmake.define.ENABLE_CUDA=ON

Tip

To speed up the installation, we recommend to use uv. Install it with:

$ pip3 install uv

Then, use uv instead of pip3 to install the package:

$ uv pip install .

Using the install script

FastDDM provides a convenience script, install.py, to simplify installation and configuration. This script wraps the standard pip (or uv) install process and allows you to easily enable advanced features, extras, and CMake options without lengthy command lines.

Note

The install script is recommended for most users, especially when enabling advanced features or extras.

To enable the C++ core with the install script, the command is:

$ python3 install.py --cpp

Tip

To see all available and up-to-date options, run:

$ python3 install.py --help

(or python install.py --help on Windows).

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:

$ pytest -v

Warning

If you want to run the tests, you need to install the test dependencies.

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