Update list-maintainers to output redmine syntax

[hoomd-blue.git] / doc / user / installation_guide.doc

/*
Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
(HOOMD-blue) Open Source Software License Copyright 2008-2011 Ames Laboratory
Iowa State University and The Regents of the University of Michigan All rights
reserved.

HOOMD-blue may contain modifications ("Contributions") provided, and to which
copyright is held, by various Contributors who have granted The Regents of the
University of Michigan the right to modify and/or distribute such Contributions.

You may redistribute, use, and create derivate works of HOOMD-blue, in source
and binary forms, provided you abide by the following conditions:

* Redistributions of source code must retain the above copyright notice, this
list of conditions, and the following disclaimer both in the code and
prominently in any materials provided with the distribution.

* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions, and the following disclaimer in the documentation and/or
other materials provided with the distribution.

* All publications and presentations based on HOOMD-blue, including any reports
or published results obtained, in whole or in part, with HOOMD-blue, will
acknowledge its use according to the terms posted at the time of submission on:
http://codeblue.umich.edu/hoomd-blue/citations.html

* Any electronic documents citing HOOMD-Blue will link to the HOOMD-Blue website:
http://codeblue.umich.edu/hoomd-blue/

* Apart from the above required attributions, neither the name of the copyright
holder nor the names of HOOMD-blue's contributors may be used to endorse or
promote products derived from this software without specific prior written
permission.

Disclaimer

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND/OR ANY
WARRANTIES THAT THIS SOFTWARE IS FREE OF INFRINGEMENT ARE DISCLAIMED.

IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

/*! \page page_install_guide Installation Guide

\b Contents:
 - \ref sec_system_req
 - \ref sec_install_hoomd_linux
   - \ref sec_install_hoomd_linux_gentoo
   - \ref sec_install_hoomd_linux_redhat
   - \ref sec_install_hoomd_linux_ubuntu
   - \ref sec_install_hoomd_linux_homedir
 - \ref sec_install_hoomd_mac
 - \ref sec_gpu_options
 
<hr>

\section sec_system_req System requirements
 - \b OS: 
    - Linux - \b Recommended
        - Ubuntu 10.04
        - Fedora 13
        - Gentoo
        - RHEL/CentOS 5.5
    - Mac OS X
        - 10.6.x Snow Leopard
 - \b CPU: Any x86_64 processor
 - \b RAM: At least as much system RAM as there is video memory total on all GPUs. For example, a host with four 4GB
           Tesla GPUs connected to it should have at least 16 GB of RAM.
 - \b GPU: (optional) A <a href=" http://www.nvidia.com/object/cuda_home.html">CUDA capable GPU</a> is required to run hoomd with
    GPU acceleration. Without one, hoomd will run on the CPU.
 -  GPU \b Driver software (install only on systems with NVIDIA GPUs -- needed to enable GPUs for use with hoomd):
   - Linux - NVIDIA Drivers version 270.41.19 or newer (http://www.nvidia.com)
   - Mac OS X NVIDIA CUDA Drivers version 4.0 or newer ( http://www.nvidia.com/object/mac-driver-archive.html )

     
VMD 1.9 or newer (http://www.ks.uiuc.edu/Research/vmd/) is not a requirement to run HOOMD-blue, but you may find it
extremely useful in visualizing simulation results. VMD 1.9 includes native support for reading HOOMD-blue XML files.

\section sec_install_hoomd_linux Installing HOOMD-blue in Linux

\subsection sec_install_hoomd_linux_gentoo Gentoo Linux

HOOMD-blue is currently available via the sunrise overlay for Gentoo. To enable the overlay for use on your
system, see http://overlays.gentoo.org/proj/sunrise .

 -# (if you have a NVIDIA GPU) <b>Install</b> the nvidia-drivers.
    \code
emerge nvidia-drivers
    \endcode
    You may need to perform some configuration: http://www.gentoo.org/doc/en/nvidia-guide.xml
    <br><br>
 -# <b>Unmask</b> the latest version of hoomd (this only needs to be performed once).
    \code
echo "sci-chemistry/hoomd ~amd64" >> /etc/portage/package.keywords
    \endcode
 -# <b>Install</b> or <b>upgrade</b> hoomd.
        \code
emerge hoomd
        \endcode
 
 \subsection sec_install_hoomd_linux_redhat CentOS/RHEL/Fedora

 -# (if you have a NVIDIA GPU) <b>Download</b> the latest drivers for your GPU from http://www.nvidia.com . 
    <br><b>To install</b>, open a terminal, cd to the directory where you downloaded the file and then run
    \code
sudo bash NVIDIA-Linux-*.run
    \endcode
    Follow the on screen prompts to complete the installation.
    <br><br>
 -# <b>Download</b> and <b>import</b> the GPG public key to validate HOOMD-blue RPMs with the following
        terminal commands.
        \code
 wget http://codeblue.umich.edu/hoomd-blue/downloads/RPM-GPG-KEY-joaander
 sudo rpm --import RPM-GPG-KEY-joaander
        \endcode
        This step only needs to be performed once.
        <br><br>
 -# <b>Download</b> the HOOMD-blue RPM package matching your linux distribution from http://codeblue.umich.edu/hoomd-blue/download.html
 <br><br>
 -# To <b>install</b> or <b>upgrade</b> double click on the downloaded file, or
    open a terminal, cd to the directory where you downloaded the
    file and run
        \code
sudo yum localinstall hoomd-blue-0.9.2*.rpm
    \endcode
    
If sudo is not configured on your system, su to root and execute the above commands without sudo.

 \subsection sec_install_hoomd_linux_ubuntu Ubuntu

 -# (if you have a NVIDIA GPU) <b>Download</b> the latest drivers for your GPU from http://www.nvidia.com . 
    <br><b>To install</b>, open a terminal, cd to the directory where you downloaded the file and then run
    \code
sudo bash NVIDIA-Linux-*.run
    \endcode
    Follow the on screen prompts to complete the installation.
    <br><br>
 -# <b>Download</b> the HOOMD-blue deb package matching your linux distribution from http://codeblue.umich.edu/hoomd-blue/download.html
 <br><br>
 -# To <b>install</b> or <b>upgrade</b> double click on the downloaded file,
    or open a terminal, cd to the directory where you downloaded the
    file and run
        \code
sudo dpkg -i hoomd-blue-0.9.2*.deb
sudo apt-get -f install
    \endcode
    
 \subsection sec_install_hoomd_linux_homedir Home directory installation
 -# If you do not have administrator access or otherwise desire to install hoomd into your home directory,
 it is recommended that you compile hoomd from source. See \ref page_compile_guide for detailed
 information.

The standard benchmark scripts serve as a good test of your installation. To run one of them, open a
terminal and run:
\code
 cd /usr/share/hoomd/benchmarks
 hoomd lj_liquid_bmark.hoomd
 # ... watch the simulation run ...
\endcode

Check out the \ref page_quick_start to start learning how to use hoomd.

<hr>

\section sec_install_hoomd_mac Installing HOOMD-blue in Mac OS X

 -# (if you have a NVIDIA GPU) <b>Download</b> the CUDA Drivers from http://www.nvidia.com/object/mac-driver-archive.html . 
    <br><b>To install</b>, open Finder, navigate to the directory where you downloaded the file and double-click on it.
    Follow the on screen prompts to complete the installation.
    <br><br>
 -# <b>Download</b> the HOOMD-blue dmg package from http://codeblue.umich.edu/hoomd-blue/download.html
    <br><br>
 -# <b>Double click</b> on the downloaded dmg file and drag the HOOMD-blue application to the desired location on
    your hard drive to install it. The following instructions assume you install HOOMD-blue in /Applications
    <br><br>
 -# <b>Launch</b> HOOMD-blue by double clicking on the application. You may also drag it to your dock
        and launch it from there. This will launch the HOOMD-blue python interpreter. (A launcher GUI is being considered for development
    in the future).
    <br><br>
 -# Perform the following steps to prepare HOOMD-blue for use from the command line. <b>Open</b> a terminal window and
    execute
    \code
 open ~/.bash_profile
    \endcode
    To open your ~/.bash_profile file.  Add this line to the end:
    \code
 alias hoomd="/Applications/HOOMD-blue.app/Contents/MacOS/hoomd"
    \endcode
    <i>Adjust</i> the name of the directory to <b>match the one you installed</b>.
    The alias will only take effect in newly opened terminal windows.

The standard benchmark scripts serve as a good test of your installation. To run one of them, open a
terminal and run:
\code
 cd /Applications/HOOMD-blue.app/Contents/share/hoomd/benchmarks/
 hoomd lj_liquid_bmark.hoomd
 # ... watch the simulation run ...
\endcode
As before, <i>adjust</i> the name of the directory to <b>match the one you installed</b>. Run ls to see a list
of other benchmarks you can run.

Check out the \ref page_quick_start to start learning how to use hoomd.

<hr>
\section sec_gpu_options Supported GPUs

A GPU is needed to take full advantage of hoomd's performance capabilities. 
See http://codeblue.umich.edu/hoomd-blue/benchmarks.html for representative performance numbers.

There are a number of ways to configure a computer system with GPUs.

<h2>Workstation solutions</h2>

<h3>Upgrade an existing desktop system</h3>
If a desktop computer meets the necessary system requirements, a GPU can be added to it. Neither this document nor the
hoomd developers can determine if your system meets those requirements. Consult an IT professional for advice, if
needed. The manufacturer's product page should list the requirements for a particular GPU. One word of caution:
pre-built systems from many vendors are often engineered with very little extra space or power, and fast GPUs which are
both large and power-hungry will either not fit or fail to operate. A self-powered 
<a href="http://www.nvidia.com/object/product_quadroplex_2200_d2_us.html">Quadro Plex 2200 D2</a> might be an option
for a desktop with such limitations, but it may also be less expensive to simply buy a new desktop equipped with GeForce
GPUs.

For GPU-ready desktops, there are many GPUs that are supported by HOOMD-blue 0.9.x.

The following are consumer level GPUs designed for gaming.
- <a href="http://www.nvidia.com/object/product-geforce-gtx-580-us.html">GeForce GTX 580</a> - \b Recommended for performance desktops
- <a href="http://www.nvidia.com/object/product-geforce-gtx-570-us.html">GeForce GTX 570</a>
- <a href="http://www.nvidia.com/object/product-geforce-gtx-560ti-us.html">GeForce GTX 560 Ti</a>
- <a href="http://www.nvidia.com/object/product_geforce_gtx_480_us.html">GeForce GTX 480</a>
- <a href="http://www.nvidia.com/object/product_geforce_gtx_470_us.html">GeForce GTX 470</a>
- <a href="http://www.nvidia.com/object/product-geforce-gtx-465-us.html">GeForce GTX 465</a>
- <a href="http://www.nvidia.com/object/product-geforce-gtx-460-us.html">GeForce GTX 460</a> - \b Recommended for low power / quiet desktops
- <a href="http://www.geforce.com/#/Hardware/GPUs/geforce-gtx-550ti">GeForce GTX 550 Ti</a>
- <a href="http://www.nvidia.com/object/product-geforce-gts-450-us.html">GeForce GTS 450</a>
- <a href="http://www.nvidia.com/object/product-geforce-gt-440-us.html">GeForce GT 440</a>
- <a href="http://www.nvidia.com/object/product-geforce-gt-430-us.html">GeForce GT 430</a>
- <a href="http://www.nvidia.com/object/product_geforce_gtx_295_us.html">GeForce GTX 295</a>
- <a href="http://www.nvidia.com/object/product_geforce_gtx_285_us.html">GeForce GTX 285</a>
- <a href="http://www.nvidia.com/object/product_geforce_gtx_285_for_mac_us.html">GeForce GTX 285 for Mac</a>
- <a href="http://www.nvidia.com/object/product_geforce_gtx_280_us.html">GeForce GTX 280</a>
- <a href="http://www.nvidia.com/object/product_geforce_gtx_275_us.html">GeForce GTX 275</a>
- <a href="http://www.nvidia.com/object/product_geforce_gtx_260_us.html">GeForce GTX 260</a>
- <a href="http://www.nvidia.com/object/product_geforce_gts_250_us.html">GeForce GTS 250</a>
- <a href="http://www.nvidia.com/object/product_geforce_gt_240_us.html">GeForce GT 240</a>
- <a href="http://www.nvidia.com/object/product_geforce_gt_220_us.html">GeForce GT 220</a>
- <a href="http://www.nvidia.com/object/product_geforce_210_us.html">GeForce GT 210</a>
- \b Note: Factory over-clocked models are \b not supported.

Tesla CXXXX GPUs are professional level compute cards with more memory than their consumer-level counterparts.
Also, Tesla C20X0 cards are capable of four times more double precision FLOPS than GTX 480.
- <a href="http://www.nvidia.com/object/product_tesla_C2050_C2070_us.html">Tesla C2070</a>
- <a href="http://www.nvidia.com/object/product_tesla_C2050_C2070_us.html">Tesla C2050</a> - \b Recommended
- <a href="http://www.nvidia.com/object/product_tesla_c1060_us.html">Tesla C1060</a>

Quadro GPUs are professional level graphics workstation cards.
- <a href="http://www.nvidia.com/object/product-quadro-6000-us.html">Quadro 6000</a>
- <a href="http://www.nvidia.com/object/product-quadro-5000-us.html">Quadro 5000</a>
- <a href="http://www.nvidia.com/object/product-quadro-4000-us.html">Quadro 4000</a>
- <a href="http://www.nvidia.com/object/product-quadro-4000-mac-us.html">Quadro 4000 for Mac</a>
- <a href="http://www.nvidia.com/object/product_quadro_fx_5800_us.html">Quadro FX 5800</a>
- <a href="http://www.nvidia.com/object/product_quadro_fx_4800_us.html">Quadro FX 4800</a>
- <a href="http://www.nvidia.com/object/product_quadro_fx_4800_for_mac_us.html">Quadro FX 4800 for Mac</a>
- <a href="http://www.nvidia.com/object/product_quadro_fx_380lp_us.html">Quadro FX 380 LP</a>

<h3>Purchase a new workstation</h3>
Pre-built workstations can be purchased from a number of vendors with any of the above GeForce and Quadro GPUs. Be sure
to check out vendors that offer custom gaming rigs. Some offer high performance configurations with up to 3 GPUs.

A limited set of vendors sells workstations with Tesla GPUs pre-installed: see http://www.nvidia.com/object/tesla_wtb.html

A custom-built workstation is also an option for \em expert system builders and IT professionals.
NVIDIA has published a set of recommendations as a starting point: http://www.nvidia.com/object/tesla_build_your_own.html

<h2>Data center installations</h2>

Data centers demand rack mount hardware. There are several GPU computing systems supported by HOOMD. These are 1U
rack mount enclosures containing 4 GPUs, a power supply and cooling fans. Two PCIe interface cards connect the GPU computing
system to one or two host nodes.
- <a href="http://www.nvidia.com/object/product-tesla-S2050-us.html">Tesla S2050</a> - \b Recommended
- <a href="http://www.nvidia.com/object/product_tesla_s1070_us.html">Tesla S1070</a>

A number of rack mount enclosures and host nodes also accept Tesla MXXX cards.
- <a href="http://www.nvidia.com/object/preconfigured-clusters.html">Tesla M2090</a>
- <a href="http://www.nvidia.com/object/product_tesla_M2050_M2070_us.html">Tesla M2070</a>
- <a href="http://www.nvidia.com/object/product_tesla_M2050_M2070_us.html">Tesla M2050</a> - \b Recommended
- <a href="http://www.nvidia.com/object/product_tesla_m1060_us.html">Tesla M1060</a>

Quadro GPUs are also available in rack mount configurations. They are marketed and built more for high performance
visualization systems, but are supported by HOOMD-blue.
- <a href="http://www.nvidia.com/object/product_quadroplex_2200_d2_us.html">Quadro Plex 2200 D2</a>
- <a href="http://www.nvidia.com/object/product_quadroplex_2200_s4_us.html">Quadro Plex 2200 S4</a>

See http://www.nvidia.com/object/preconfigured_clusters.html for even more data center options.

<h2>Laptops</h2>

There are many laptop GPUs capable of running hoomd. Due to power, heat, and stability concerns, the hoomd developers
do not support laptops as a platform for long running hoomd simulations.

<h2>Future GPUs</h2>
GPUs newer than this document may also be supported. HOOMD-blue 0.9.x is tested and supported on the Fermi (GF100)
and Tesla (G200) generations. All GPUs from these generations are supported.

*/