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