Table Of Contents

Previous topic

Chroma: Ultra-fast Photon Monte Carlo

Next topic

Ubuntu Installation

This Page


Chroma development tends to live on the bleeding-edge. Installation of Chroma requires a more significant hardware and software investment than other packages, but we think the rewards are worth it!

Hardware Requirements

At a minimum, Chroma requires:

  • An x86 or x86-64 CPU.
  • A NVIDIA GPU that supports CUDA compute capability 2.0 or later.

We highly recommend that you run Chroma with:

  • An x86-64 CPU with at least four cores.
  • 8 GB or more of system RAM.
  • An NVIDIA GPU that supports CUDA compute capability 2.0 or later, and has at least 1 GB of device memory.

Memory requirements on the CPU and GPU scale with the complexity of your model. A detector represented with 60.1 million triangles (corresponding to 20,000 detailed photomultipler tubes) requires 2.2 GB of CUDA device memory, and more than 6 GB of host memory during detector construction. Chroma can take advantage of multiple CPU cores to generate Cherenkov light with GEANT4.


The Chroma interactive renderer includes optional support for the Space Navigator 3D mouse, which makes it 10x more fun to fly through the detector geometry!

OS Specific Prerequisites

First, follow one of the following OS-specific guides to install the system-level prerequisites for Chroma:

Common Installation Guide

We have tried to streamline the Chroma installation process to be portable to many platforms. If you have problems following these instructions, please open an issue.

Step 1: Create virtualenv

Chroma should never be installed into your system Python directories. Instead create a self-contained virtualenv:

virtualenv --system-site-package chroma_env
source chroma_env/bin/activate

You only need to delete the chroma_env directory to completely remove Chroma from your system.

On some newer versions of virtualenv, the python shared library is not installed in the virtual environment. To see if the python shared library is installed, check to see if there is a libpython*.so file in $VIRTUAL_ENV/lib/pythonX.X/config:

ls $VIRTUAL_ENV/lib/pythonX.X/config/

If you don’t see a shared library there, or the directory config does not exist, you can manually symlink the shared library:

mkdir $VIRTUAL_ENV/lib/pythonX.X/config
cd $VIRTUAL_ENV/lib/pythonX.X/config
ln -s [path to shared library] .

where [path to shared library] is usually something like /usr/lib/

Step 2: Install Chroma Dependencies


Some of the packages which Chroma installs monkey patch the script and so will not work if pip uses a cached version of the package. If you are reinstalling chroma, make sure to delete the pip cache folder in ~/.cache/pip.

Chroma depends on several C and C++ libraries that are not typically included in the package managers of many platforms. Using shrinkwrap, we have automated the installation of these libraries into the virtualenv, isolating them from the rest of your system:

# Create configuration file for PyCUDA
echo -e "import os\nvirtual_env = os.environ['VIRTUAL_ENV']\nBOOST_INC_DIR = [os.path.join(virtual_env, 'include')]\nBOOST_LIB_DIR = [os.path.join(virtual_env, 'lib')]\nBOOST_PYTHON_LIBNAME = ['boost_python']" > ~/
# Search this site for shrinkwrap packages used by Chroma

# This will take a LONG time.
# If interrupted, run the command again and it will resume where it left off
pip install chroma-deps

# Refresh environment variables
source $VIRTUAL_ENV/bin/activate

Step 3: Install Chroma

Now we can checkout a copy of Chroma and install it. By default, we will put it into the $VIRTUAL_ENV/src directory, but anywhere is fine:

hg clone
cd chroma
python develop

To see if everything installed successfully run the following command:

chroma-cam @chroma.models.lionsolid

If everything has succeeded, you are ready to move onto the tour!