Installation¶

Fresnel binaries are available in the glotzerlab-software Docker/Singularity images and in packages on conda-forge. You can also compile fresnel from source.

Binaries¶

Anaconda package¶

Fresnel is available on conda-forge. To install, first download and install miniconda. Then add the conda-forge channel and install fresnel:

$ conda config --add channels conda-forge
$ conda install fresnel

jupyter and matplotlib are required to execute the fresnel example notebooks:

$ conda install jupyter matplotlib

Note

The fresnel package on conda-forge does not support GPUs

Singularity / Docker images¶

See the glotzerlab-software documentation for container usage information and cluster specific instructions.

Compile from source¶

Obtain the source¶

Download source releases directly from the web: https://glotzerlab.engin.umich.edu/downloads/fresnel:

$ curl -O https://glotzerlab.engin.umich.edu/downloads/fresnel/fresnel-v0.13.1.tar.gz

Or, clone using git:

$ git clone --recursive  https://github.com/glotzerlab/fresnel

Fresnel uses git submodules. Either clone with the --recursive option, or execute git submodule update --init to fetch the submodules.

Configure a virtual environment¶

When using a shared Python installation, create a virtual environment where you can install fresnel:

$ python3 -m venv /path/to/virtual/environment --system-site-packages

Activate the environment before configuring and before executing fresnel scripts:

$ source /path/to/virtual/environment/bin/activate

Tell CMake to search in the virtual environment first:

$ export CMAKE_PREFIX_PATH=/path/to/virtual/environment

Note

Other types of virtual environments (such as conda) may work, but are not thoroughly tested.

Install Prerequisites¶

fresnel requires:

C++14 capable compiler
CMake >= 3.8
pybind11 >= 2.2
Python >= 3.6
numpy
Qhull >= 2015.2
For CPU execution (required when ENABLE_EMBREE=ON):
- Intel TBB >= 4.3.20150611
- Intel Embree >= 3.0.0
For GPU execution (required when ENABLE_OPTIX=ON):
- OptiX == 6.0
- CUDA >= 10

ENABLE_EMBREE (defaults ON) and ENABLE_OPTIX (defaults OFF) are orthogonal settings, either or both may be enabled.

Additional packages may be needed:

pyside2
- Required t.o enable interactive widgets. (runtime)
pillow
- Required to display rendered output in Jupyter notebooks automatically. (runtime)
- Required to execute unit tests.
pytest
- Required to execute unit tests.
sphinx, sphinx_rtd_theme, and nbspinx
- Required to build the user documentation.
doxygen
- Requited to build developer documentation.

Install these tools with your system or virtual environment package manager. fresnel developers have had success with pacman (arch linux), apt-get (ubuntu), Homebrew (macOS), and MacPorts (macOS):

$ your-package-manager install cmake doxygen embree pybind11 python python-pillow python-pytest python-sphinx python-sphinx_rtd_theme python-nbsphinx intell-tbb qhull

Typical HPC cluster environments provide python, numpy, and cmake via a module system:

$ module load gcc python cmake

Note

Packages may be named differently, check your system’s package list. Install any -dev packages as needed.

Tip

You can install numpy and other python packages into your virtual environment:

python3 -m pip install numpy

Compile¶

Configure with cmake and compile with make:

$ cd /path/to/fresnel
$ mkdir build
$ cd build
$ cmake ../
$ make install -j10

By default, fresnel builds the Embree (CPU) backend. Pass -DENABLE_OPTIX=ON to cmake to enable the GPU accelerated OptiX backend.

Run tests¶

To run tests, execute pytest in the build directory or in an environment where fresnel is installed to run all tests.

$ pytest --pyargs fresnel

Build user documentation¶

Build the user documentation with sphinx:

$ cd /path/to/fresnel
$ cd doc
$ make html
$ open build/html/index.html

Build C++ Documentation¶

To build the developer documentation, execute doxygen in the repository root. It will write HTML output in devdoc/html/index.html.