Building from source

To build fresnel from source:

  1. Install prerequisites:

    micromamba install cmake embree git ninja numpy pybind11 python qhull

    Install additional packages needed to run the unit tests:

    micromamba install pillow pytest

  2. Obtain the source:

    git clone --recursive git@github.com:glotzerlab/fresnel.git

  3. Change to the repository directory:

    cd fresnel

  4. Configure:

    cmake -B build -S . -GNinja

  5. Build the package:

    cd build

    ninja

  6. Run tests:

    python3 -m pytest fresnel

  1. Install the package (optional):

    ninja install

To build the documentation from source (optional):

  1. Install prerequisites:

    micromamba install furo nbsphinx ipython sphinx-copybutton

  2. Build the documentation:

    sphinx-build -b html doc html

The sections below provide details on each of these steps.

Install prerequisites

You will need to install a number of tools and libraries to build fresnel. The options ENABLE_EMBREE and ENABLE_OPTIX each require additional libraries when enabled.

Install the required dependencies:

micromamba install cmake embree git ninja numpy pybind11 python qhull

Install additional packages needed to run the unit tests:

micromamba install pillow pytest

Install additional packages needed to build the documentation:

micromamba install furo nbsphinx ipython sphinx-copybutton

Note

This guide assumes that you use the micromamba package manager. Adjust the commands appropriately for the package manager of your choice.

Warning

When using a conda-forge environment for development, make sure that the environment does not contain clang, gcc, or any other compiler or linker. These interfere with the native compilers on your system and will result in compiler errors when building, linker errors when running, or segmentation faults.

General requirements:

  • C++17 capable compiler

  • CMake

  • NumPy

  • pybind11

  • Python

  • Qhull

  • For CPU execution (required when ENABLE_EMBREE=ON):

    • Intel TBB

    • Intel Embree

  • For GPU execution (required when ENABLE_OPTIX=ON):

    • OptiX >= 6.0, < 7.0

    • CUDA

Optional runtime dependencies:

  • pyside2

To run tests:

  • pillow

  • pytest

To build the documentation:

  • sphinx

  • sphinx_rtd_theme

  • nbsphinx

  • ipython

Obtain the source

Clone using Git:

git clone --recursive git@github.com:glotzerlab/fresnel.git

Release tarballs are also available on the GitHub release pages.

See also

See the git book to learn how to work with Git repositories.

Important

fresnel uses Git submodules. Clone with the --recursive to clone the submodules.

Execute git submodule update --init to fetch the submodules each time you switch branches and the submodules show as modified.

Configure

Use CMake to configure the fresnel build directory:

cd {{ path/to/fresnel/repository }}

cmake -B build -S . -GNinja

Pass -D<option-name>=<value> to cmake to set options on the command line.

Options that find libraries and executables take effect only on a clean invocation of CMake. To set these options, first remove CMakeCache.txt from the build directory and then run cmake with these options on the command line.

  • PYTHON_EXECUTABLE - Specify which python to build against. Example: /usr/bin/python3.

    • Default: python3.X detected on $PATH.

  • <package-name>_DIR - Specify the location of a package.

    • Default: Found on the CMake search path.

Other option changes take effect at any time:

  • ENABLE_EMBREE - When enabled, build the CPU backend using Embree (default: on).

  • BUILD_OPTIX - When enabled, build the GPU backend using OpTiX (default: off).

  • CMAKE_BUILD_TYPE - Sets the build type (case sensitive) Options:

    • Debug - Compiles debug information into the library and executables. Enables asserts to check for programming mistakes. fresnel will run slow when compiled in Debug mode, but problems are easier to identify.

    • RelWithDebInfo - Compiles with optimizations and debug symbols.

    • Release - (default) All compiler optimizations are enabled and asserts are removed. Recommended for production builds.

  • CMAKE_INSTALL_PREFIX - Directory to install fresnel. Defaults to the root path of the found Python executable.

  • PYTHON_SITE_INSTALL_DIR - Directory to install fresnel to relative to CMAKE_INSTALL_PREFIX. Defaults to the site-packages directory used by the found Python executable.

Tip

Pass the following options to CMake to optimize the build for your processor: -DCMAKE_CXX_FLAGS=-march=native -DCMAKE_C_FLAGS=-march=native

Build the package

After configuring, build fresnel with:

cd build

ninja

The build directory now contains a fully functional fresnel package. Execute ninja again any time you modify the code, test scripts, or CMake scripts.

Tip

ninja will automatically execute cmake as needed. You do NOT need to execute cmake yourself every time you build fresnel.

Run tests

Use pytest to execute unit tests:

python3 -m pytest fresnel

Install the package

Execute:

ninja install

to install fresnel into your Python environment.

Warning

This will overwrite any fresnel that you may have installed by other means.

To use the compiled fresnel without modifying your environment, set PYTHONPATH:

export PYTHONPATH={{ path/to/fresnel/repository/build }}

Build the documentation

Run Sphinx to build HTML documentation:

sphinx-build -b html doc html

Open the file html/index.html in your web browser to view the documentation.

Tip

Add the sphinx options -a -n -W -T --keep-going to produce docs with consistent links in the side panel and provide more useful error messages.