Merge branch 'maint'

[hoomd-blue.git] / doc / user / compile_guide_linux_generic.dox

/*
Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
(HOOMD-blue) Open Source Software License Copyright 2009-2014 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_compile_guide_linux_generic Generic Instructions

Table of contents:
- \ref sec_build_linux_generic_prereq
- \ref sec_build_linux_generic_compile
- \ref sec_build_linux_generic_mpi
<hr>

\section sec_build_linux_generic_prereq Software Prerequisites

\section software_req_install_linux_python Python

First, check if python is already installed
~~~~
$ python -V
Python 2.7.6
~~~~
Make sure that the version is 2.6 or greater. If you get
~~~~
bash: python: command not found
~~~~
or have a version older than 2.6, you will need to upgrade or install python.
You will also need the python development libraries which some distributions might separate into a separate
python-devel package. The existence of the python development libraries can be tested
by checking the output of
~~~~
$ find /usr/include/python* -name Python.h
/usr/include/python2.7/Python.h
~~~~
The output should be the location of the python development files. If you get
~~~~
find: /usr/include/python*: No such file or directory
~~~~
or no output, then you do not have the python development libraries installed.

On a compute cluster, Python may be installed in a non-standard location and it may be required to set
your environment variables to point to these paths. Depending on your cluster configuration, this
may be achieved with a command such as
~~~~
module load python
~~~~
or similar. Please refer to your cluster documentation or contact the administrator for information on how to use
software modules.

If you don't have Python with development headers installed, you will need to install them.

\subsection python-root Installing Python with a package manager

If you have administrative privileges on your machine, you may simply use your Linux distribution's package
manager to install Python.  The process for installing software differs from linux distribution to
distribution.  In Gentoo (http://www.gentoo.org/)
~~~~
$ sudo emerge python
~~~~
would install python. Look at your linux distribution's documentation to find how to install
packages on your system (i.e. yum, apt-get, up2date, or another).

\subsection python-source Installing Python from source

If you are not the administrator, you can still install python locally.

Get the latest python version from http://www.python.org or directly download python 3.3.
~~~~
$ wget http://www.python.org/ftp/python/3.3.0/Python-3.3.0.tar.bz2
~~~~
Unpack the python archive in a convenient location (you may delete the build directory after installation)
~~~~
$ tar -xvfj Python-3.3.0.tar.bz
~~~~
and build python
~~~~
$ cd Python-3.3.0
$ ./configure --enable-shared --prefix=$HOME/local
$ make -j 12 install
~~~~
This installs python into the `local/` subdirectory of your home directory.
The `-j` option tells make to use the CPU cores available in your system for the build process.

\section software_req_install_linux_boost Boost

First, check if boost is already installed
\code
$ grep BOOST_LIB_VERSION /usr/include/boost/version.hpp
//  BOOST_LIB_VERSION must be defined to be the same as BOOST_VERSION
#define BOOST_LIB_VERSION "1_44"
\endcode
Make sure that the version is 1_39 or newer. If you get
\code
grep: /usr/include/boost/version.hpp: No such file or directory
\endcode
then boost is not installed. You can install boost with your distribution's package
manager.

If your distribution doesn't have a new enough version of boost, or if it is not provided on your cluster,
you can build it by hand. Building boost is a time consuming process, but not complicated if you follow these instructions.

In order to build boost, you need the development package for bzip. If your
distribution provides the pacakge *bzip2-devel*, install it.
If not, or if your cluster installation does not have provide the bzip2 header
files, you need to install the bzip2 sources.
~~~~
$ wget http://www.bzip.org/1.0.6/bzip2-1.0.6.tar.gz
$ tar -xvfz bzip2-1.0.6.tar.bz
$ cd bzip2-1.0.6
$ make install PREFIX=$HOME/local
~~~~

Proceed by downloading `boost_1_52_0.tar.bz2` from http://www.boost.org/. Extract the tarball and
configure boost for building with the following commands.
~~~~
$ tar -xvjf boost_1_52_0.tar.bz2
$ cd boost_1_52_0
~~~~

If you have also installed python from source, the Boost installation scripts may not find
it automatically. In this case, you need to inform the build system about the location of your python
installation.
~~~~
$ cp tools/build/v2/user-config.jam $HOME
~~~~
Now edit the file `user-config.jam` and add a line
~~~~
using python : 3.3 : /home/myuser/local/bin/python3 : /home/myuser/local/include/python3.3m : /home/myuser/local/lib ;
~~~~
at the end of file. Now you can build boost.
~~~~
$ ./bootstrap.sh --prefix=$HOME/local
Building Boost.Build engine with toolset gcc... tools/build/v2/engine/bin.linuxx86_64/b2
Detecting Python version... 3.3
...
~~~~

If it reports a different Python version than the one you have requested in
your \b user-config.jam file, just ignore that message.
The build engine should find the correct Python version nevertheless.
Now, run the command
~~~~
$ ./b2 install -j 11
~~~~
or, if you have installed the bzip2 sources,
~~~~
$ ./b2 install -j 10 -s BZIP2_SOURCE=/path/to/bzip2-1.0.6
~~~~
and wait some time for everything to compile. At the end, you should see a
message saying
~~~~
...updated 963 targets...
~~~~

Boost is now installed.

You can delete the boost_1_52_0 directory now if you wish. It might be worth
saving for a little while until you have compiled HOOMD-blue and know everything
is working so that you won't need to go through all the setup steps again.

Before running cmake, set the following environment variables to the location where you installed boost:
~~~~
$ export BOOST_ROOT=/home/myuser/local
$ cmake ../
... continue with build instructions ...
~~~~

\section software_req_install_linux_compiler Compiler

These instructions test for the installation of gcc. Other C++ compilers can be used
if you wish, though compilations with CUDA enabled are only supported with gcc.

Test if g++ is installed.
~~~~
$ g++ --version
$ g++ (GCC) 4.1.2 (Gentoo 4.1.2)
~~~~
Any version should do. If you get
~~~~
bash: g++: command not found
~~~~
then you will need to install gcc using your distributions package management system.


\section software_req_install_linux_cmake CMake

It is not very likely that your linux distribution includes CMake by default,
but check anyways.
~~~~
 $ cmake --version
cmake version 2.8.7
~~~~
Make sure the version is 2.6.2 or later. If you have an old version or get
~~~~
bash: cmake: command not found
~~~~
then you will need to install CMake. Try your distributions package
manager first. I.e. in Gentoo
~~~~
$ emerge cmake
~~~~

If your distribution does not have a cmake package, or you do not have administrator access
then you can install it into your home directory by hand. First, download
cmake-2.8.12.2-Linux-i386.tar.gz from the Downloads section at http://www.cmake.org.
Unpack the tarball to any location you prefer: this example assumes you are installing it to the
`${HOME}/local`
~~~~
$ mv cmake-2.8.10-Linux-i386.tar.gz ~/local
$ cd ~/local
$ tar -xvzf cmake-2.8.12.2-Linux-i386.tar.gz
~~~~
Then you need to put the bin directory for cmake into your path. If you use bash for a shell you can do
this by editing ~/.bashrc. Look for a line with `PATH=...` and add the cmake directory to the end separated
by a colon. If you can't find the line, create it like so.
~~~~
PATH=$PATH:$HOME/local/cmake-2.8.12.2-Linux-i386/bin
export PATH
~~~~
Restart your bash shell (or open a new one) and try the version check above to test your installation.

\section software_req_install_linux_cuda CUDA

CUDA is probably not available by default with your linux distribution. Gentoo offers a package:
~~~~
$ emerge nvidia-cuda-toolkit
~~~~
but most others do not.

If your distribution doesn't come with a package, Follow
[NVIDIA's instructions](http://docs.nvidia.com/cuda/cuda-getting-started-guide-for-linux/index.html#package-manager-installation)
to install the NVIDIA CUDA repository. Then use your package manager to install cuda. For example:
~~~~
sudo yum install cuda
~~~~

\section software_req_install_linux_git Git

Git is used for version control.

First, see if you already have git installed.
\code
 $ git --version
git version 1.7.6.1
\endcode
If you get
\code
-bash: git: command not found
\endcode
then you will need to install it with your distribution's package manager.

\section sec_build_linux_generic_compile Compile HOOMD-blue

Now that all of the prerequisite software is installed, you are ready to compile HOOMD-blue.

**Get the source:**
There are two ways to get the source code for HOOMD-blue.  You can [download it](http://codeblue.umich.edu/hoomd-blue/download.html)
or you can clone the git repository:
~~~~
$ git clone https://codeblue.umich.edu/git/hoomd-blue
~~~~
By default, the *master* branch will be checked out. This branch includes new features added since the last release.
Use `git checkout name` to switch to a different branch or tag.

Valid names:
- *maint* - includes bugfixes since the last release
- *v1.0.0* - Release version 1.0.0
- *v0.11.3* - Release version 0.11.3
- *etc...*

You can verify that a tagged release is exactly as it appeared to the developers when it was created if you
have GPG installed.
~~~~
$ git cat-file blob 175bf6edfc8ac23c067df1d9bd7b5dd41982be3c | gpg --import
$ git tag -v v1.0.0
~~~~

**Compile and install HOOMD-blue with makefiles:*
~~~~
$ cd hoomd-blue
$ mkdir build
$ cd build
$ cmake ../ -DCMAKE_INSTALL_PREFIX=~/hoomd-install
$ make install -j12
~~~~

If your build fails because of a version mismatch between the Boost python module and your python
installation, you can run cmake with an additional hint to your python installation:
~~~~
$ cmake ../code -DPYTHON_EXECUTABLE=$HOME/local/python3.
~~~~
and run `make install -j12` again.

Now run
~~~~
$ make check -j12
~~~~
to test your build

**Setup your PATH:**
Open `~/.bash_profile` and add the following line to the end
~~~~
export PATH=$PATH:${HOME}/hoomd-install/bin
~~~~
assuming that you set `CMAKE_INSTALL_PREFIX` to `~/hoomd-install` above. If you prefer to install hoomd to a different
location, simply set `CMAKE_INSTALL_PREFIX` to the desired directory in the cmake command.

Either open a new terminal or
~~~~
source ~/.bash_profile
~~~~
for the path setting to take effect.

<hr>

\section sec_build_linux_generic_mpi Compiling with MPI enabled

### Preinstalled MPI

If your cluster administrator provides an installation of MPI, you need to figure out if is in your
`$PATH`. If the command
~~~~
$ which mpicc
/usr/bin/mpicc
~~~~
succeeds, you're all set. HOOMD-blue should detect your MPI compiler automatically.

If this is not the case, set the `MPI_HOME` environment variable to the location of the MPI installation.
~~~~
$ echo ${MPI_HOME}
/home/software/rhel5/openmpi-1.4.2/gcc
~~~~

### Compile your own MPI: MVAPICH2

HOOMD-blue supports the use of CUDA enabled MPI libraries. This offers an extra speed-up
of parallel simulations in some cases. This is likely to be true if the GPUs in one node provide
peer-to-peer communication capability. To find out if this is the case, run the **simpleP2P** test from
the NVIDIA CUDA SDK.

If you choose to compile your own MPI, you can run it out of your home directory.
MVAPICH2 1.8 (and later) supports CUDA integration that enables fast intra-node GPU performance. The minimum
version of MVAPICH2 required for HOOMD is 1.9.

~~~~
$ tar -xvzf mvapich2-1.9.tgz
$ cd mvapich2-1.9
$ ./configure --prefix=${HOME}/local --enable-cuda --with-cuda=${CUDA_ROOT} --enable-shared
$ make -j10
$ make install
~~~~

The following needs to be added to your environment variables in .bash_profile.
~~~~
export LD_LIBRARY_PATH=${HOME}/local/lib:${LD_LIBRARY_PATH}    # if not already there
export MPI_HOME=${HOME}/local

# if using nodes without IB adapters
export MV2_USE_SHARED_MEM=1
export MV2_SMP_SEND_BUF_SIZE=262144
~~~~

### Compile your own MPI: OpenMPI

OpenMPI also supports fast CUDA integration starting with version 1.7.

It can be obtained from the [OpenMPI website](http://www.open-mpi.org/).

Build OpenMPI with

~~~~
$ ./configure --with-cuda=${CUDA_ROOT} --with-cuda-libdir=${CUDA_ROOT}/lib64 --prefix=${HOME}/local --with-hwloc=internal --with-openib=/usr
 $ make install -j12
~~~~

The following needs to be added to your environment variables in .bash_profile.
~~~~
export LD_LIBRARY_PATH=${HOME}/local/lib:${LD_LIBRARY_PATH}    # if not already there
export MPI_HOME=${HOME}/local
~~~~
Then log out and back in before attempting to build boost (so that it can find MPI).

### Build hoomd

Configure and build HOOMD-blue as normal (see \ref sec_build_linux_generic_compile). During the cmake step, MPI should
be detected and enabled. For cuda-aware MPI, additionally supply the **ENABLE_MPI_CUDA=ON** option to cmake.

*/