Installation¶
Fresnel binary images are available on Docker Hub and packages on conda-forge. You can also compile fresnel from source.
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, install
$ conda install jupyter matplotlib
You can update fresnel with:
$ conda update fresnel
Docker images¶
Pull the docker image glotzerlab/software to get fresnel along with many other tools commonly used in simulation and analysis workflows. See full usage information on the glotzerlab/software docker hub page.
Singularity:
$ umask 002
$ singularity pull docker://glotzerlab/software
Docker:
$ docker pull glotzerlab/software
Compile from 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.6.0.tar.gz
Or, clone using git:
$ git clone --recursive https://bitbucket.org/glotzer/fresnel.git
Fresnel uses git submodules. Either clone with the --recursive
option, or execute git submodule update --init
to fetch the submodules.
Prerequisites¶
- C++11 capable compiler
- CMake >= 2.8
- Python >= 2.7
- 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 >= 4.0
- CUDA >= 7.5
- To execute tests:
- pytest
- pillow
ENABLE_EMBREE
(defaults ON) and ENABLE_OPTIX
(defaults OFF) are orthogonal settings, either or both may be
enabled.
Optional dependencies¶
- pytest
- Required to execute unit tests.
- pillow
- Required to display rendered output in Jupyter notebooks automatically.
- sphinx
- Required to build the user documentation.
- doxygen
- Requited to build developer documentation.
Compile¶
Configure with cmake and compile with make. Replace ${PREFIX}
your desired installation location.
$ mkdir build
$ cd build
$ cmake ../ -DCMAKE_INSTALL_PREFIX=${PREFIX}/lib/python
$ make install -j10
By default, fresnel builds the Embree (CPU) backend. Pass -DENABLE_OPTIX=ON
to cmake to enable the GPU
accelerated OptiX backend.
Add ${PREFIX}/lib/python
to your PYTHONPATH
to use fresnel.
$ export PYTHONPATH=$PYTHONPATH:${PREFIX}/lib/python
Run tests¶
Fresnel has extensive unit tests to verify correct execution.
$ export PYTHONPATH=/path/to/build
$ cd /path/to/fresnel
$ cd test
$ pytest
Build user documentation¶
Build the user documentation with sphinx:
$ cd /path/to/fresnel
$ cd doc
$ make html
$ open build/html/index.html
Specify search paths¶
OptiX, TBB, Embree, and Python may be installed in a variety of locations. To specify locations
for libraries, use these methods the first time you invoke cmake
in a clean build directory.
Library | Default search path | CMake Custom search path |
---|---|---|
OptiX | /opt/optix |
-DOptiX_INSTALL_DIR=/path/to/optix |
TBB | system | TBB_LINK=/path/to/tbb/lib (env var) |
Embree | system | -Dembree_DIR=/path/to/embree-3.x.y (the directory containing embree-config.cmake) |
Python | $PATH | -DPYTHON_EXECUTABLE=/path/to/bin/python |
Build C++ Documentation¶
To build the developer documentation, execute
doxygen
in the repository root. It will write HTML output in devdoc/html/index.html
.