Installation ============ 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: 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. .. note:: 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: .. toctree:: :maxdepth: 1 ubuntu rhel macosx .. _common-install: 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/ libpython2.7.so 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/libpythonX.X.so. Step 2: Install Chroma Dependencies ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: Some of the packages which Chroma installs monkey patch the setup.py 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']" > ~/.aksetup-defaults.py # Search this site for shrinkwrap packages used by Chroma export PIP_EXTRA_INDEX_URL=https://chroma.bitbucket.io/chroma_pkgs/ # 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:: cd $VIRTUAL_ENV/src hg clone https://bitbucket.org/chroma/chroma cd chroma python setup.py 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 :ref:`tour`!