Documentation updates

4 files changed, 262 insertions, 0 deletions

diff --git a/doc/source/install/macosx.rst b/doc/source/install/macosx.rst
new file mode 100644
index 0000000..8b02b77
--- /dev/null
+++ b/doc/source/install/macosx.rst
@@ -0,0 +1,42 @@
+Mac OS X Installation
+=====================
+
+Most Mac systems lack the GPU required to run Chroma, with the notable exception of the current 15" MacBook Pro (both Retina and Standard) models, which use an NVIDIA GeForce GT 650M GPU.  These instructions have been tested on OS X 10.8, which ships with the above systems.
+
+.. warning: We have only tested Chroma on the 15" MacBook Pro with Retina display and 1 GB of GPU memory.  Models with 512 MB of video memory may have difficulty running Chroma depending on how much video memory is used by the driver and GUI.
+
+Step 1: Install Xcode
+^^^^^^^^^^^^^^^^^^^^^
+
+Xcode can be `installed from the Mac App Store <http://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12>`_.  Once installed, it is important to start Xcode and accept the license agreement.  Once started, open the Preferences window and go to the Downloads pane.  There should be a "Command Line Tools" component listed.  Click the "Install" button next to it if it is not already listed as "Installed."
+
+Step 2: Install XQuartz
+^^^^^^^^^^^^^^^^^^^^^^^
+
+XQuartz is the OS X port of the X.Org X Window system, and is a prerequisite for some packages used by Chroma.  It is much more up to date than the X11.app that has been shipped with OS X in the past.  Download XQuartz from `here <http://xquartz.macosforge.org/landing/>`_ and install it.
+
+Step 3: Install CUDA
+^^^^^^^^^^^^^^^^^^^^
+
+CUDA on OS X requires a special driver.  It can be downloaded from the `CUDA Downloads Page <https://developer.nvidia.com/cuda-downloads>`_.  The package also includes the CUDA compiler and sample programs, installed to /Developer/NVIDIA/CUDA-5.0.
+
+Once installed, you can ensure the CUDA compiler and libraries are in your path by adding the following lines to your bash login script ($HOME/.bashrc)::
+
+  export PATH=/Developer/NVIDIA/CUDA-5.0/bin:$PATH
+  export DYLD_LIBRARY_PATH=/Developer/NVIDIA/CUDA-5.0/lib/:$DYLD_LIBRARY_PATH
+
+
+Step 4: Install MacPorts
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are several packaging systems that simplify the installation of Open Source software on the Mac.  We have tested and recommend `MacPorts <http://www.macports.org/>`_, but other systems like `Fink <http://www.finkproject.org>`_ and `Homebrew <http://mxcl.github.com/homebrew/>`_ should also work if you install the same packages.  We will assume MacPorts below.
+
+Follow the `MacPorts installation instructions <http://www.macports.org/install.php>`_.  Once installed, open a terminal and run the following command::
+
+    sudo port install py27-matplotlib mercurial py27-game py27-virtualenv Xft2 xpm
+    sudo port select virtualenv virtualenv27
+
+Step 5: Continue to Common Installation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The rest of the installation process is described in :ref:`common-install`.
\ No newline at end of file
diff --git a/doc/source/install/overview.rst b/doc/source/install/overview.rst
new file mode 100644
index 0000000..554675d
--- /dev/null
+++ b/doc/source/install/overview.rst
@@ -0,0 +1,106 @@
+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 <http://www.3dconnexion.com/products/spacenavigator.html>`_, 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
+<http://bitbucket.org/chroma/chroma/issues?status=new&status=open>`_.
+
+
+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.
+
+
+Step 2: Install Chroma Dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Chroma depends on several C and C++ libraries that are not typically included
+in the package managers of many platforms.  Using `shrinkwrap
+<http://shrinkwrap.rtfd.org>`_, 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=http://mtrr.org/chroma_pkgs/
+
+  # On RHEL/Centos/Scientific Linux ONLY, uncomment and run the following commands
+  # pip install -U numpy
+  # easy_install pygame
+
+  # 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://
+  hg clone https://bitbucket.org/chroma/chroma
+  cd chroma
+  python setup.py develop
+
+If everything has succeeded, you are ready to move onto the :ref:`tour`!
\ No newline at end of file
diff --git a/doc/source/install/rhel.rst b/doc/source/install/rhel.rst
new file mode 100644
index 0000000..644202d
--- /dev/null
+++ b/doc/source/install/rhel.rst
@@ -0,0 +1,64 @@
+RHEL/Centos/Scientific Linux 6 Installation
+===========================================
+
+Chroma only supports RHEL-derived distributions if they are based on version 6 or later.  The packages included with RHEL 5 are too old to run Chroma.
+
+Step 1: Install packages with Yum package manager
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As the root user, run the following commands::
+
+    yum groupinstall "Development tools"
+    yum install python-matplotlib python-devel uuid-devel lapack-devel atlas-devel \
+        mercurial git subversion mesa-libGLU-devel freeglut-devel SDL-devel gtk2-devel \
+        libXpm-devel libXft-devel libXext-devel libXlibX11-devel expat-devel bzip2-devel \
+        libXt-devel
+    easy_install virtualenv
+
+
+Step 2: Disable the Nouveau Graphics Driver
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+CUDA requires the use of the official NVIDIA graphics driver, rather
+than the open source Nouveau driver that is included with RHEL. 
+
+Edit /etc/grub.conf and add ``rdblacklist=nouveau`` to the end of the kernel line::
+
+    kernel /vmlinuz-2.6.32-279.11.1.el6.x86_64 ... rdblacklist=nouveau
+
+Create the file /etc/modprobe.d/blacklist-nouveau.conf with the line::
+
+    blacklist nouveau
+
+Step 3: Install the CUDA Driver and Toolkit
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The NVIDIA driver can be installed by going to the `CUDA Downloads
+<https://developer.nvidia.com/cuda-downloads>`_ and downloading the package
+corresponding to your operating system.This single package includes a current
+NVIDIA driver, the CUDA compiler toolkit, and sample programs.
+
+Drop to a console terminal by pressing `CTRL+ALT+F1` and then enter::
+
+    su -
+    init 3
+
+Login again at the prompt and enter the following commands::
+
+    su -
+    cd /home/user/Downloads
+    chmod +x cuda_5.0.35_linux_64_ubuntu11.10-1.run
+    .cuda_5.0.35_linux_64_ubuntu11.10-1.run
+
+During the installation you can pick all the default options.
+
+Once installed, you can ensure the CUDA compiler and libraries are in your path by adding the following lines to your bash login script (usually $HOME/.bashrc)::
+
+  export PATH=/usr/local/cuda/bin:$PATH
+  export LD_LIBRARY_PATH=/usr/local/cuda/lib64/:$LD_LIBRARY_PATH
+
+.. warning:: Non-bash shells will need to be adjusted appropriately.  If you are using a 32-bit distribution, then lib64/ should be changed to lib/.
+
+Step 4: Continue to Common Installation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The rest of the installation process is described in :ref:`common-install`.
\ No newline at end of file
diff --git a/doc/source/install/ubuntu.rst b/doc/source/install/ubuntu.rst
new file mode 100644
index 0000000..ffd7260
--- /dev/null
+++ b/doc/source/install/ubuntu.rst
@@ -0,0 +1,50 @@
+Ubuntu Installation
+===================
+
+Step 1: ``apt-get`` packages with Ubuntu package manager
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We need to install several system packages::
+
+    sudo apt-get install python-pygame python-matplotlib python-virtualenv \
+        build-essential xorg-dev python-dev libglu1-mesa-dev  freeglut3-dev \
+        uuid-dev liblapack-dev mercurial git subversion libatlas-base-dev \
+        libbz2-dev
+
+Step 2: CUDA Toolkit and Driver
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CUDA requires the use of the official NVIDIA graphics driver, rather than the
+open source Nouveau driver that is included with Ubuntu.  The NVIDIA driver
+can be installed by going to the `CUDA Downloads <https://developer.nvidia.com
+/cuda-downloads>`_ and downloading the package corresponding to your Ubuntu
+version. This single package includes a current NVIDIA driver, the CUDA
+compiler toolkit, and sample programs.
+
+.. note:: Although NVIDIA only lists support up to Ubuntu 11.10 in CUDA 5, we have found the package to also work with Ubuntu 12.04 LTS.
+
+To install the NVIDIA drivers, you will need to switch to a text console (Ctrl-Alt-F1) and shut down the X server::
+
+  # This next will kill everything running on your graphical desktop!
+
+  # On Ubuntu 12.04: sudo service lightdm stop 
+  sudo service gdm stop 
+
+  chmod +x cuda_5.0.35_linux_64_ubuntu11.10-1.run
+  sudo ./cuda_5.0.35_linux_64_ubuntu11.10-1.run
+  # Accept the license and pick the defaults
+
+  # On Ubuntu 12.04: sudo service lightdm start
+  sudo service gdm start
+
+Once installed, you can ensure the CUDA compiler and libraries are in your path by adding the following lines to your bash login script (usually $HOME/.bashrc)::
+
+  export PATH=/usr/local/cuda/bin:$PATH
+  export LD_LIBRARY_PATH=/usr/local/cuda/lib64/:$LD_LIBRARY_PATH
+
+.. warning:: Non-bash shells will need to be adjusted appropriately.  If you are using a 32-bit distribution, then lib64/ should be changed to lib/.
+
+Step 3: Continue to Common Installation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The rest of the installation process is described in :ref:`common-install`.
\ No newline at end of file