installation.tex

\documentclass[titlepage,letterpaper,final]{scrartcl}

\usepackage{index}
\input{pism-macros.tex}

\addtolength\textheight{0.75in}
\addtolength{\oddsidemargin}{-.4in}
\addtolength{\evensidemargin}{-.4in}
\addtolength{\textwidth}{0.9in}

%% uncomment to see locations of index entries
% \proofmodetrue

% this lets us avoid the scrartcl/hyperref conflict...
\let\ifvtex\relax

% hyperref should be the last package we load
\usepackage[pdftex,
colorlinks=true,
plainpages=false, % only if colorlinks=true
linkcolor=blue,   % only if colorlinks=true
citecolor=blue,   % only if colorlinks=true
urlcolor=blue     % only if colorlinks=true
]{hyperref}

% preamble:

\pdfinfo{
/Title (PISM Installation Manual)
/Author (the PISM authors)
/Subject (Downloading and installing PISM, a Parallel Ice-Sheet Model)
/Keywords (PISM ice-sheet modeling installation)
}

\sloppy

\begin{document}

\begin{titlepage}

  \begin{center}
    \vspace*{3.5cm}
    {\huge\usekomafont{title} PISM Installation Manual}
    \vspace{0.5cm}

    {\Large The PISM Authors}
    \vspace{1cm}
  \end{center}

\setcounter{tocdepth}{3}
\small
\tableofcontents
\normalsize

\vspace{0.3in}

  \begin{center}
    \small Support by email: \PISMEMAIL.

    \medskip
    Please see the \emph{PISM User's Manual} for the full list of authors.

    \medskip
    Manual date \today.  Based on PISM \PISMREV.

    \medskip
    \PISMDOWNLOADMSG
 \end{center}

\end{titlepage}

\section{Introduction}

\large
This \emph{Installation Manual} describes how to download the PISM source code and install PISM and the libraries it needs.  Information about PISM, including a \emph{User's Manual}, is on-line at
\bigskip
\begin{center}
  \href{http://www.pism-docs.org}{www.pism-docs.org}
\end{center}
\bigskip
\noindent The fastest path to a fully functional PISM installation is to use a Linux system with a Debian-based package system (e.g.~Ubuntu):  Start by following subsections \ref{sec:deb-libraries-by-hand} about getting Debian packages for prerequisites, then \ref{subsec:prereq-petsc} to install PETSc from source, then \ref{sec:install-cmake} to install PISM itself, and finally install Python packages following section \ref{sec:python}.

\vfill

\large
\begin{center}
\parbox{5.5in}{ \emph{WARNING}:\index{PISM!warning}  PISM is an ongoing project.  Ice sheet modeling is complicated and is generally not mature.  Please don't trust the results of PISM or any other ice sheet model without a fair amount of exploration.

\bigskip
Also, please don't expect all your questions to be answered here.  Write to us with questions at \href{mailto:help@pism-docs.org}{\texttt{help@pism-docs.org}}.}
\normalsize
\end{center}
\normalsize
\vfill

\begin{quote}
\textsl{Copyright (C) 2004--2014 the PISM authors.}
\medskip

\noindent \textsl{This file is part of PISM.  PISM is free software; you can redistribute it and/or modify it under the terms of the GNU General Public
  License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.  PISM is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
  warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.  You should have received a copy of the GNU General Public License\index{GPL (\emph{GNU Public License})} along with PISM. If not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA}
\end{quote}


\section{Libraries and programs needed by PISM}
\label{sec:prerequisites}

\bigskip
\normalspacing
This table lists required dependencies for PISM alphabetically.
\bigskip
\newcommand{\fattablespacing}{\renewcommand{\baselinestretch}{1.5}\tiny\normalsize}

\begin{center}
  \begin{tabular}{lll}
    \toprule
    \multicolumn{2}{c}{\textbf{Required Program or Library}} & \textbf{Comment}\\
    \midrule
    FFTW & \url{http://www.fftw.org/} & version $\ge$ 3.0\\
    GSL &\url{http://www.gnu.org/software/gsl/} & version $\ge$ 1.15\\
    MPI &\url{http://www.mcs.anl.gov/mpi/} & \\
    NetCDF &\url{http://www.unidata.ucar.edu/software/netcdf/} & version $\ge$ 4.1 \\
    PETSc & \url{http://www.mcs.anl.gov/petsc/petsc-as/} & version $\ge$ \PETSCREL \\
    UDUNITS-2 & \url{http://www.unidata.ucar.edu/software/udunits/} & \\
    \bottomrule
  \end{tabular}
\end{center}

\bigskip

Before installing these ``by hand'', check the Debian and Mac OS X sections below for specific how-to.  In particular, if multiple MPI implementations (e.g.~MPICH and Open-MPI) are installed then PETSc can under some situations ``get confused'' and throw MPI-related errors.  Even package systems have been known to allow this confusion.

Optional libraries are needed for certain PISM features, namely cell-area correction and parallel I/O.  These libraries are recommended, but not strictly required: \bigskip

\begin{center}
  \begin{tabular}{lll}
    \toprule
    \multicolumn{2}{c}{\textbf{Recommended Library}} & \textbf{Comment}\\
    \midrule
    PROJ.4 & \url{http://trac.osgeo.org/proj/} & \\
    PnetCDF & \url{http://trac.mcs.anl.gov/projects/parallel-netcdf} & \\
   \bottomrule
  \end{tabular}
\end{center}

\bigskip

Python (\url{http://python.org/}) is needed both in the PETSc installation process and in scripts related to PISM pre- and post-processing, while Git (\url{http://git-scm.com/}) is usually needed to download the PISM code.  Both should be included in any Linux/Unix distribution.

The following Python packages are needed to do all the examples in the \emph{User's Manual} (which run python scripts):
\bigskip

\begin{center}
  \begin{tabular}{lll}
    \toprule
    \multicolumn{2}{c}{\textbf{Recommended Python Package}} & \textbf{Comment}\\
    \midrule
    matplotlib & \url{http://matplotlib.sourceforge.net/} & used in some scripts \\
    netcdf4-python & \url{https://github.com/Unidata/netcdf4-python} & used in \emph{most} scripts \\
    numpy & \url{http://numpy.scipy.org/} & used in \emph{most} scripts \\
   \bottomrule
  \end{tabular}
\end{center}


\section{Installation Cookbook}\label{sec:cookbook}

\subsection{Installing PISM's prerequisites} \label{subsec:prereq}

\subsubsection{Installing prerequisites by packages (Debian)}
\label{sec:deb-libraries-by-hand}

You should be able to use your package manager to get the prerequisites for PISM.
Install the following packages using \texttt{apt-get} or \texttt{synaptic} or similar.
All of these are recommended as they satisfy requirements for building or running PISM.
\begin{center}
  \begin{tabular*}{0.9\linewidth}{p{0.2\linewidth}p{0.7\linewidth}}
    \toprule
    \emph{Package name} & \emph{Comments}\\
    \midrule
    \texttt{cmake} & required to configure PISM \\
    \texttt{libfftw3-dev} & required by PISM \\
    \texttt{g++} & required to build PISM \\
    \texttt{libgsl0-dev} & required by PISM \\
    \texttt{netcdf-bin} & required: \texttt{ncgen} is used during the build process \\
    \texttt{libnetcdf-dev} & required by PISM \\
    \texttt{libudunits2-dev} & required by PISM \\
    \midrule
    \texttt{cdo} & used in some pre-processing scripts \\
    \texttt{cmake-curses-gui} & a text-based easy interface for CMake \\
    \texttt{git} & used to get PISM source code \\
    \texttt{nco} & used in many pre-processing scripts \\
    \texttt{ncview} & view fields in NetCDF files \\
    \texttt{libproj-dev} & used to compute ice area and volume \\
    \texttt{python-dev} & (helps with scripts\dots perhaps not essential) \\
    \texttt{python-pyproj} & used in some pre-processing scripts \\
    \texttt{libx11-dev} & X windows is useful to get graphics through PETSC \\
    \midrule
    \texttt{libblas-dev} & BLAS is required by PETSc \\
    \texttt{liblapack-dev} & LAPACK is required by PETSc \\
    \texttt{openmpi-bin} & MPI is required to run PISM in parallel \\
    \texttt{libopenmpi-dev} & MPI is required to run PISM in parallel \\
    \bottomrule
  \end{tabular*}
\end{center}

Once done, see \ref{subsec:prereq-petsc} to install PETSc from source and then
\ref{sec:install-cmake} for building PISM itself.

\vspace{0.3in}


\subsubsection{Installing prerequisites from source}
\label{subsec:prereq-source}
\renewcommand{\labelenumi}{\textbf{\arabic{enumi}.}~}

From now on, this manual assumes the use of the \texttt{bash} shell.
\medskip

\begin{enumerate}
\item  You will need
  \href{http://www.python.org/}{Python} and \href{http://git-scm.com/}{Git}
  installed. To use
  the (recommended) graphical output of PISM you will need an
  \href{http://www.x.org/}{X Windows server}.

\item Generally the ``header files'' for its prerequisite libraries
  are required for building PISM.  (This means that the
  ``developer's versions'' of the libraries are needed if the libraries are
  downloaded from package repositories like Debian; see section \ref{sec:prerequisites}.)

\item PISM uses \href{http://www.unidata.ucar.edu/software/netcdf/}{NetCDF (=
  \emph{network Common Data Form})}\index{NetCDF} as an input and output
  file format. If it is not already present, install it using the instructions
  at the web-page or using a package management system.

\item PISM uses the \href{http://www.gnu.org/software/gsl/}{GSL (= \emph{GNU
      Scientific Library})}\index{GSL (\emph{GNU Scientific Library})} for
  certain numerical calculations and special functions. If it is not already
  present, install it using the instructions at the web-page or using a package
  management system.

\item PISM uses the \href{http://www.fftw.org/}{FFTW
 (= \emph{Fastest Fourier Transform in the West}) library}\index{FFTW
    (\emph{Fastest Fourier Transform in the West})} for the
  deformation of the solid earth (bed) under ice loads.  Install FFTW version
  3.x or check that it is installed already.

\item You will need a version of \href{http://www.mcs.anl.gov/mpi/}{MPI (=
    \emph{Message Passing Interface})}.\index{MPI (\emph{Message Passing
      Interface})} Your system may have an existing MPI installation, in which
  case the path to the MPI directory will be used when installing PETSc  (see \ref{subsec:prereq-petsc}).
  The goal is to have the PETSc installation use the
  same version of MPI which is called by the \texttt{mpiexec} or \texttt{mpirun}
  executable.

  Once MPI is installed, you will
  want to add the MPI \texttt{bin} directory to your path so that you can
  invoke MPI using the \texttt{mpiexec} or \texttt{mpirun} command. For
  example, you can add it with the statement

\texttt{export PATH=/home/user/mympi/bin:\$PATH}  \qquad (for \texttt{bash} shell)

\noindent or

\texttt{setenv PATH /home/user/mympi/bin:\$PATH}  \qquad (for \texttt{csh} or \texttt{tcsh} shell).

\noindent Such a statement can, of course, appear in your \texttt{.bashrc} (or
\texttt{.profile} or \texttt{.cshrc}) file so that there is no need to retype
it each time you use MPI.

\end{enumerate}


\subsubsection{Installing PETSc from source}
\label{subsec:prereq-petsc}
  
PISM uses \href{http://www.mcs.anl.gov/petsc/}{PETSc (=
    \emph{Portable Extensible Toolkit for Scientific
      Computation})}.\index{PETSc (\emph{Portable Extensible Toolkit for
      Scientific computation})}\footnote{``PETSc''
  is pronounced ``pet-see''.}  Unfortunately, an up-to-date PETSc distribution
  is unlikely to be available in package repositories.  Download the PETSc
  source by grabbing the current gzipped tarball at:
\begin{center}
    \url{http://www.mcs.anl.gov/petsc/}
\end{center}
PISM requires a version of PETSc which is \texttt{\PETSCREL} or later. The
``lite'' form of the tarball is fine if you are willing to depend on an Internet
connection for accessing PETSc documentation.

You should configure and build PETSc as described on the
PETSc installation page, but it might be best to read the following comments on
the PETSc configure and build process first:

\renewcommand{\labelenumi}{(\roman{enumi})}
\begin{enumerate}
\item Untar in your preferred location and enter the new PETSc directory.
  Note PETSc should \emph{not} be configured using root privileges.
  When you run the configure script the following
  options are recommended; note PISM uses shared libraries by
  default:\index{PETSC_ARCH}
\begin{verbatim}
$  export PETSC_DIR=$PWD
$  export PETSC_ARCH=linux-gnu-opt
$  ./config/configure.py --with-shared-libraries --with-debugging=0
\end{verbatim}

You need to define the environment variable \texttt{PETSC_DIR}\index{PETSC_DIR}---one
way is shown here---\emph{before} running the configuration script.  Turning off the
inclusion of debugging code and symbols can give a significant speed improvement,
but some kinds of development will benefit from a \texttt{--with-debugging=1}
configuration option.  Using shared libraries may be unwise on certain clusters,
etc.; check with your system administrator.

\item It is sometimes convenient to have PETSc grab a local copy of
BLAS\index{BLAS (\emph{Basic Linear Algebra Subsystem})} and
LAPACK\index{LAPACK (\emph{Linear Algebra PACKage})} rather than using the
system-wide version. So one may add ``\texttt{--download-f2cblaslapack=1}'' to
the other configure options. Since there is no use of Fortran in PISM, Fortran
can also be disabled using ``\texttt{--with-fortran=0}'' (PETSc~$\le 3.4$),
or ``\texttt{--with-fc=0}'' (PETSc~$\ge 3.5$).

\item If there is an existing MPI\index{MPI (\emph{Message Passing Interface})} installation, for example at \texttt{/home/user/mympi/}, one can point PETSc to it by adding the option ``\texttt{--with-mpi-dir=/home/user/mympi/}''.  The path used in this option must have MPI executables \texttt{mpicxx} and \texttt{mpicc}, and either \texttt{mpiexec} or \texttt{mpirun}, in sub-directory \texttt{bin/} and MPI library files in sub-directory \texttt{lib/}. If you get messages suggesting that PETSc cannot configure using your existing MPI, you might want to try adding the \texttt{--download-mpich=1} (or \texttt{--download-openmpi=1}) option to PETSc's configure command.

\item Configuration of PETSc for a batch system requires special procedures described at the PETSc documentation site.  One starts with a configure option \texttt{--with-batch=1}.  See the ``Installing on machine requiring cross compiler or a job scheduler'' section of the \href{http://www.mcs.anl.gov/petsc/petsc-2/documentation/installation.html}{PETSc installation page}.

\item  Configuring PETSc takes at least a few minutes even when everything goes smoothly.   A value for the environment variable \texttt{PETSC_ARCH} will be reported at the end of the configure process; take note of this value.  One may always reconfigure with additional/new \texttt{PETSC_ARCH} as needed.

\item  After \texttt{configure.py} finishes, you will need to \texttt{make all test} in the PETSc directory and watch the result.  If the X Windows system is functional some example viewers will appear; as noted you will need the X header files for this to work.
\end{enumerate}

\subsection{Installing PISM itself}
\label{sec:install-cmake}
At this point you have configured the environment which PISM needs.

To make sure that the key PETSc and MPI prerequisites work properly together, so that you can run PISM in parallel, you might want to make sure that the correct \texttt{mpiexec} can be found, by setting your \texttt{PATH}.  For instance, if you used the option \texttt{--download-mpich=1} in the PETSc configure, the MPI \texttt{bin} directory will have a path like \texttt{\$PETSC_DIR/\$PETSC_ARCH/bin}.  Thus the following lines might appear in your \texttt{.bashrc} or \texttt{.profile}, if not there already:
\begin{verbatim}
export PETSC_DIR=/home/user/petsc-3.4.0/
export PETSC_ARCH=linux-gnu-opt
export PATH=$PETSC_DIR/$PETSC_ARCH/bin/:$PATH
\end{verbatim}
From now on we will assume that the \texttt{PETSC_ARCH} and \texttt{PETSC_DIR} variables are set.

You are ready to build PISM itself, which is a much quicker procedure, as follows:

\begin{enumerate}
\item Get the latest source\index{PISM!download source code} for PISM using the Git\index{Git} version control system:
\begin{enumerate}
\item \label{getPISMstep} Check the website \url{http://www.pism-docs.org/} for the latest version of PISM.
\item Do
\begin{verbatim}
$  git clone git://github.com/pism/pism.git pism0.6
\end{verbatim}
\item A directory called ``\texttt{pism0.6/}'' will be created.  Note that in the future when you enter that directory,
  \texttt{git pull} will update to the latest revision of PISM.\footnote{Of course, after \texttt{git pull} you will \texttt{make -C build install} to recompile and re-install PISM.}
\end{enumerate}
\item Build PISM:\footnote{Please report any problems you meet at these build stages by sending us the output: \href{mailto:help@pism-docs.org}{help@pism-docs.org}.}
\begin{verbatim}
$  mkdir pism0.6/build
$  cd pism0.6/build
$  PISM_INSTALL_PREFIX=~/pism cmake ..
$  make install
\end{verbatim}
Here \texttt{pism0.6} is the directory containing PISM source code while \texttt{\textasciitilde/pism} is the directory PISM will be installed into. All the temporary files created during the build process will be in \texttt{pism0.6/build} created above.

You might need to add \texttt{CC} and \texttt{CXX} to the \texttt{cmake}
command:
\begin{verbatim}
$  PISM_INSTALL_PREFIX=~/pism CC=mpicc CXX=mpicxx cmake ..
\end{verbatim}
Whether this is necessary or not depends on your MPI setup.

Commands above will configure PISM to be installed in \texttt{\textasciitilde/pism/bin},
\texttt{\textasciitilde/pism/lib/pism} and
\texttt{\textasciitilde/pism/share/doc}, then compile and install all its
executables and scripts.

If your operating system does not support shared libraries\footnote{This might be necessary if you're building on a Cray XT5 or a Sun Opteron Cluster, for example.}, then set \texttt{Pism_LINK_STATICALLY} to ``ON''. This can be done by
either running
\begin{verbatim}
$  cmake -DPism_LINK_STATICALLY:BOOL=ON ..
\end{verbatim}
%$ - match dollar signs to make emacs happy
or by using \texttt{ccmake}:\footnote{Install the \texttt{cmake-curses-gui} package to get \texttt{ccmake} on Ubuntu.} run
\begin{verbatim}
$  ccmake ..
\end{verbatim}
%$ - match dollar signs to make emacs happy
and then change \texttt{Pism_LINK_STATICALLY} (and then press 'c' for ``configure'' then 'g' for ``generate makefiles'').  Then do \texttt{make install}.

Object files created during the build process (located in the \texttt{build}
sub-directory) are not automatically deleted after installing PISM, so do ``\texttt{make
  clean}'' if space is an issue. You can also delete the build
directory altogether if you are not planning on re-compiling PISM.

\item PISM executables can be run most easily by adding the \texttt{bin/}
  sub-directory in your selected install path
  (\texttt{\textasciitilde/pism/bin} in the example above) to your
  \texttt{PATH}. For instance, this command can be done in the \texttt{bash}
  shell or in your \texttt{.bashrc} file:\index{setting the \$PATH to find PISM
    executables}
\begin{verbatim}
export PATH=~/pism/bin:$PATH
\end{verbatim}

\item Now see section \ref{sec:tests} or the \emph{Getting Started} section of the \emph{User's Manual} to continue.
\end{enumerate}

\subsubsection{Installing PISM and prerequisites on a Cray XK6 system}
\label{subsec:cray}

Installing PISM on Cray systems deserves special mention for two reasons:
\begin{itemize}
\item building on a Cray requires static linking
\item Cray uses non-standard locations for libraries and header files
\end{itemize}
This describes a successful PISM installation on a Cray XK6m at ARSC (\url{http://www.arsc.edu/}).

\begin{enumerate}
\item Load appropriate modules. You may need to set module versions; note that
  PISM requires PETSc version $\ge$ \PETSCREL. (Loading all the necessary
  modules allows compilers to find headers and libraries.)
\begin{verbatim}
module swap PrgEnv-pgi PrgEnv-gnu
module load petsc/3.3.00
module swap tpsl/1.2.00 tpsl/1.3.00
module load hdf5-parallel/1.8.8
module load netcdf-hdf5parallel/4.2.0
module load fftw/3.3.0.2
module load parallel-netcdf/1.3.1
\end{verbatim}
\item Cray does not provide modules for GSL, UDUNITS-2, and CMake, but your system administrators can install them for you.
\item Get PISM sources and create a build directory
\begin{verbatim}
git clone git://github.com/pism/pism.git
mkdir pism/build
cd pism/build
\end{verbatim}
\item
Create a text file \texttt{pism_config.cmake} in the build directory you
created. It should contain the following, though with replacement of
\begin{itemize}
\item ``\texttt{/path/to/gsl/}'' with the GSL install location,
\item ``\texttt{/path/to/udunits2/}'' with the UDUNITS-2 install location,
\item ``\texttt{/path/to/libexpat.a}'' with the expat library location
  (if your UDUNITS-2 installation requires it)
\item ``\texttt{\$ENV\{HOME\}/pism/}'' with the desired PISM install directory.
\end{itemize}

\begin{verbatim}
# Compiler
set (CMAKE_C_COMPILER "cc" CACHE STRING "")
set (CMAKE_CXX_COMPILER "CC" CACHE STRING "")

# Disable testing for PISM's prerequisites
set (Pism_LOOK_FOR_LIBRARIES OFF CACHE BOOL "")

# Installation path
set (CMAKE_INSTALL_PREFIX "$ENV{HOME}/pism/" CACHE STRING "")

# General compilation/linking settings
set (Pism_ADD_FPIC OFF CACHE BOOL "")
set (Pism_LINK_STATICALLY ON CACHE BOOL "")

# No Proj.4 on fish.arsc.edu
set (Pism_USE_PROJ4 OFF CACHE BOOL "")
set (Pism_USE_TAO OFF CACHE BOOL "")

# Set the custom GSL location
set (GSL_LIBRARIES
 "/path/to/gsl/lib/libgsl.a;/path/to/gsl/lib/libgslcblas.a"
 CACHE STRING "" FORCE)
set (GSL_INCLUDES "/path/to/gsl/include"
 CACHE STRING "" FORCE)

# Set custom UDUNITS2 location
set (UDUNITS2_LIBRARIES "/path/to/udunits2/lib/libudunits2.a;/path/to/libexpat.s"
 CACHE STRING "" FORCE)
set (UDUNITS2_INCLUDES "/path/to/udunits2/include"
 CACHE STRING "" FORCE)

# NETCDF (a work-around for a Cray bug)
execute_process(COMMAND nc-config --cflags OUTPUT_VARIABLE NETCDF_CFLAGS
 OUTPUT_STRIP_TRAILING_WHITESPACE)
execute_process(COMMAND nc-config --libs OUTPUT_VARIABLE NETCDF_LDFLAGS
 OUTPUT_STRIP_TRAILING_WHITESPACE)

set (CMAKE_CXX_FLAGS "${NETCDF_CFLAGS} ${CMAKE_CXX_FLAGS}"
 CACHE STRING "C++ compiler flags" FORCE)
set (CMAKE_EXE_LINKER_FLAGS "${NETCDF_LDFLAGS} ${CMAKE_EXE_LINKER_FLAGS}"
 CACHE STRING "C++ executable linker flags" FORCE)
\end{verbatim}
\item Configure and build PISM:
\begin{verbatim}
cmake -C pism_config.cmake ..
make install
\end{verbatim}

Notes:
\begin{itemize}
\item Setting \texttt{Pism_LOOK_FOR_LIBRARIES} to ``off'' lets the module
  system manage all necessary compile flags. (This is only necessary on systems
  that install libraries in non-standard locations.)
\item When \texttt{Pism_LOOK_FOR_LIBRARIES} is ``off'', all optional PISM features are enabled by default. This is why we need to explicitly disable \texttt{Proj.4} and \texttt{TAO}.
\item \texttt{Pism_EXTERNAL_LIBS} and \texttt{include_directories} can be used to specify locations of libraries other than GSL, if necessary.
\item Extra compiler flags can be added by setting \texttt{CMAKE_CXX_FLAGS}, extra linker flags -- \mbox{\texttt{CMAKE_EXE_LINKER_FLAGS}}.
\end{itemize}
\end{enumerate}

\subsubsection{Installing PISM and prerequisites on Mac OS X}  \label{subsec:macosx}

This section adds information on installing PISM and its prerequisites on the Mac OS X operating system.

\begin{enumerate}
\item As PISM is distributed as compilable source code only, you will need
  software developer's tools, XCode and the \emph{X window system}, X11. Both
  packages can be installed by either downloading them from
  \href{http://developer.apple.com/tools/xcode/}{Apple Developer Connection} or
  using the Mac OS X installation DVD.
\item The use of \href{http://www.macports.org/}{MacPorts} or
  \href{http://www.finkproject.org/}{Fink} is recommended, as it significantly
  simplifies installing many open-source libraries. Download a package from the
  \href{http://www.macports.org/install.php}{MacPorts homepage} (or
  \href{http://www.finkproject.org/download/index.php}{Fink homepage}), install
  and set the environment:

\begin{verbatim}
export PATH=/opt/local/bin:/opt/local/sbin:$PATH
\end{verbatim}
for MacPorts and
\begin{verbatim}
source /sw/bin/init.sh
\end{verbatim}
for Fink.

\item It is not necessary to install Python, as it is bundled with
  the operating system. Some PISM scripts use SciPy; it can be installed using MacPorts or
  by downloading the \href{http://www.enthought.com/}{Enthought Python Distributions}.

\item  If you are using MacPorts, do
\begin{verbatim}
$  sudo port install netcdf ncview gsl fftw-3 libproj4 git-core cmake
\end{verbatim}
%$ - match dollar signs to make emacs happy

Fink users should use the following command instead (\texttt{ncview} is only available in the unstable branch).
\begin{verbatim}
$  fink install netcdf gsl fftw3 proj git cmake
\end{verbatim}

\item At this point, all the PISM prerequisites except PETSc are installed.
Download the latest PETSc tarball from the
  \href{http://www.mcs.anl.gov/petsc/petsc-as/}{PETSc website}.
Untar, then change to the directory just created.
The next three commands complete the PETSc installation:
\begin{verbatim}
$  export PETSC_DIR=$PWD; export PETSC_ARCH=macosx;
$  ./config/configure.py --with-shared-libraries \
                         --with-fortran=0 --with-debugging=0
$  make all test
\end{verbatim}

\item Now you can build PISM as described in section \ref{sec:install-cmake}.
\end{enumerate}


\subsection{Common build problems and solutions (i.e.~if it still does not work \dots)}
\label{subsec:config}

We recommend using \texttt{ccmake}, the text-based CMake interface to adjust
PISM's build parameters. One can also set CMake cache variables using the
\texttt{-D} command-line option (\texttt{cmake -Dvariable=value}) or by editing
\texttt{CMakeCache.txt} in the build directory.

Here are some issues we know about.
\begin{itemize}
\item Sometimes, if a system has more than one MPI installation CMake finds the
  wrong one. To tell it which one to use, set \texttt{MPI_LIBRARY} and related
  variables by using \texttt{ccmake} or editing \texttt{CMakeCache.txt} in the
  build directory. You can also set environment variables \texttt{CC} and
  \texttt{CXX} to point to MPI wrappers:
\begin{verbatim}
$  CC=mpicc CXX=mpicxx cmake path/to/pism-source
\end{verbatim}

  It is also possible to guide CMake's configuration mechanism by setting
  \texttt{MPI_COMPILER} to the compiler (such as \texttt{mpicc}) corresponding
  to the MPI installation you want to use, setting \texttt{MPI_LIBRARY} to
  \texttt{MPI_LIBRARY-NOTFOUND} and re-running CMake.
\item If you are compiling PISM on a system using a cross-compiler, you will
  need to disable CMake's tests trying to determine if PETSc is installed
  properly. To do this, set \texttt{PETSC_EXECUTABLE_RUNS} to ``yes''.

  To tell CMake where to look for libraries for the target system, see
  \url{http://www.cmake.org/Wiki/CMake_Cross_Compiling} and the paragraph about
  \texttt{CMAKE_FIND_ROOT_PATH} in particular.

  You may find section \ref{subsec:cray} to be useful in a case like this.
\item Note that the PISM build system uses \texttt{ncgen} from the NetCDF
  package to generate \mbox{\texttt{pism_config.nc}}. This means that a working
  NetCDF installation is required on both the ``host'' and the ``target''
  systems when cross-compiling PISM. If CMake finds \texttt{ncgen} for the
  target platform, try setting
  \mbox{\texttt{CMAKE_FIND_ROOT_PATH_MODE_PROGRAM}} to \texttt{NEVER}.
\item Some systems support static libraries only. To build PISM statically and
  tell CMake not to try to link to shared libraries, set
  \texttt{Pism_LINK_STATICALLY} to \texttt{ON} using \texttt{ccmake}.
\item You can set \texttt{Pism_LOOK_FOR_LIBRARIES} to ``\texttt{OFF}''
  to disable all heuristics and set compiler flags by hand. See
  section \ref{subsec:cray} for an example.
\end{itemize}


\section{Quick tests of the installation} \label{sec:tests}
Once you're done with the installation, a few tests can confirm that PISM is functioning correctly.
\begin{enumerate}
\item Try a MPI four process verification run:

\begin{verbatim}
$ mpiexec -n 4 pismv -test G -y 200
\end{verbatim}

  \noindent If you see some output and a final \texttt{Writing model state}
  \texttt{to file 'unnamed.nc'} then PISM completed
  successfully. At the end of this run you get measurements of the difference
  between the numerical result and the exact solution. See the \emph{User's
    Manual} for more on PISM verification.

  The above ``\texttt{-n 4}'' run should work even if there is only one actual
  processor (core) on your machine.  (In that case MPI will just run multiple
  processes on the one processor.)  This run will also produce a NetCDF output
  file \texttt{unnamed.nc}, which can be read and viewed by NetCDF tools.

\item Try an EISMINT II run using the PETSc viewers (under the X window system):

\begin{verbatim}
$ pisms -y 5000 -view_map thk,temppabase,velsurf_mag
\end{verbatim}

  \noindent When using such viewers and \texttt{mpiexec} the additional final
  option \texttt{-display :0} \,is sometimes required to enable MPI to use X,
  like this:

\begin{verbatim}
$ mpiexec -n 2 pisms -y 5000 -view_map thk,temppabase,velsurf_mag -display :0
\end{verbatim}

\noindent Also \texttt{-draw_pause 0.1} or similar may be needed if the figures
are refreshing too fast.

\item Run a basic suite of software tests.  To do this, you need to be in PISM's
build directory, and the cmake flag \texttt{Pism_BUILD_EXTRA_EXECS} should be
\texttt{ON}.  Then do:
\begin{verbatim}
$ make test
\end{verbatim}
The message at the bottom should say ``\texttt{100\% tests passed, 0 tests
failed out of XX}'' or similar.  These tests use NCO and require
Python packages \texttt{numpy} and \texttt{netcdf4-python}.  Feel free to
send the output of \texttt{make test} to
\href{mailto:help@pism-docs.org}{help@pism-docs.org} if any failed tests cannot
be resolved.
\end{enumerate}

\subsubsection*{Next steps}

Start with the \emph{User's Manual}, which has a ``Getting started'' section. A
copy is on-line at the PISM homepage and documentation page
\href{http://www.pism-docs.org/}{\texttt{www.pism-docs.org}}, along with a
source code \emph{Browser} (HTML). Completely up-to-date documentation can be
built from \LaTeX~source in the \texttt{doc/} sub-directory, as described in
the last section.

A final reminder with respect to installation: Let's assume you have checked
out a copy of PISM using Git, as in step \ref{getPISMstep} above. You can
update your copy of PISM to the latest version by running \texttt{git pull} in
the PISM directory and \texttt{make install} in your build directory.


\section{Installing Python packages}
\label{sec:python}

If you're lucky, you might be able to install all the Python packages mentioned
in section \ref{sec:prerequisites} using a package manager. On the other hand,
the Python packages below are not currently available in Debian package
repositories. They are easy to install using Python \texttt{setuptools},
however; these tools are included with recent versions of Python.

\subsubsection*{Python module \texttt{netCDF4}, from package
  \texttt{netcdf4-python}}

You can skip this paragraph if you have
\href{http://www.enthought.com/}{Enthought Python Distributions} installed.

To install \texttt{netcdf4-python} providing the \texttt{netCDF4} module needed
by PISM scripts, download a tarball from the project homepage
\url{http://code.google.com/p/netcdf4-python/}.

\begin{verbatim}
$  wget http://netcdf4-python.googlecode.com/files/netCDF4-NUMBER.tar.gz
$  tar -xvf netCDF4-NUMBER.tar.gz
\end{verbatim}
Enter the directory you just untarred and install:
\begin{verbatim}
$  cd netCDF4-NUMBER/
$  sudo python setup.py install
\end{verbatim}
assuming that NetCDF was installed in the \texttt{/usr/} tree. If you
are using python installed via MacPorts, you can get netdf4-python by doing
\begin{verbatim}
$  sudo port install py-netcdf4
\end{verbatim}

The scripts in directories \texttt{util/}, \texttt{examples/...}, and so on,
which need \texttt{netCDF4}, should now work.

\section{Rebuilding PISM documentation}
\label{sec:docs}

You might want to rebuild the documentation from source, as PISM and its
documentation evolve together. These tools are required: \bigskip
\begin{center}
  \begin{tabular*}{0.9\linewidth}{llp{0.55\linewidth}}
    \toprule
    \LaTeX & \href{http://www.latex-project.org/}{\texttt{www.latex-project.org}} &  needed for rebuilding any of the documentation \\
    \texttt{doxygen}\index{doxygen} & \href{http://www.stack.nl/~dimitri/doxygen/}{\texttt{www.doxygen.org}} &  required to rebuild the \emph{Browser} from source  \\
    \texttt{graphviz}\index{graphviz} & \href{http://www.graphviz.org/}{\texttt{www.graphviz.org}} & required to rebuild the \emph{Browser} from source  \\
    \bottomrule
  \end{tabular*}
\end{center}
\bigskip
\noindent To rebuild PISM documentation, change to the PISM build directory and do
\begin{center}
  \begin{tabular}{p{0.22\linewidth}p{0.75\linewidth}}
    \texttt{make manual} & to build the \emph{User's Manual}, \texttt{manual.pdf}\\
    \texttt{make forcing} & to build the \emph{PISM's Climate Forcing
      Components} document, \texttt{forcing.pdf} \\
    \texttt{make installation} & to build this document, the \emph{Installation Manual}, \texttt{installation.pdf}\\
    \texttt{make browser} & to build the \emph{PISM Source Code Browser},\\
  \end{tabular}
\end{center}
\bigskip

To build documentation on a system without PISM's prerequisite
libraries (such as MPI and PETSc), assuming that PISM sources are in \texttt{~/pism0.6}, do the following:
\begin{verbatim}
$ cd ~/pism0.6
$ mkdir doc-build # create a build directory
$ cd doc-build
$ cmake ../doc
\end{verbatim}
%$
then ``\texttt{make manual}'', ``\texttt{make installation}'' and
others (see above) will work as expected.

\subsection{Building documentation for PISM's Python bindings and inversion tools}
The documentation for PISM's Python bindings uses the documentation-generation tool Sphinx; see \href{http://sphinx-doc.org/}{sphinx-doc.org}.  The bindings make scripting and interactive PISM possible, but many PISM users will not need them.  Installing them is required to use PISM for inversion of surface velocities for basal shear stress and ice hardness.  Building their documentation is strongly-recommended before use.

Sphinx can be installed via \texttt{apt-get} or \texttt{macports}.
See \url{http://sphinx-doc.org/latest/install.html} for more details.  For example, do
\begin{verbatim}
  sudo apt-get install sphinx-common
\end{verbatim}

The bindings documentation also requires the Sphinx extension called \texttt{sphinxcontrib.bibtex}, which may come with some Sphinx packages (but not with Debian packages at this time).  Without it you will see this error when you try to build the bindings documentation:
\begin{verbatim}
  Extension error:
  Could not import extension sphinxcontrib.bibtex (exception: No module named bibtex)
\end{verbatim}
To install it see \url{http://sphinxcontrib-bibtex.readthedocs.org}.

Note that if you install Sphinx using macports,
you will install a version that depends on your python
version, and its executables will have names that
depend on the python version, e.g. \texttt{sphinx-build-2.7}
rather than \texttt{sphinx-build} for Python 2.7.  You will want to
set up aliases so that the standard names work as well. To do this,
\begin{verbatim}
  sudo port select sphinx py27-sphinx
\end{verbatim}
(replacing \texttt{py27-sphinx} with \texttt{py26-sphinx} for Python 2.6, etc.)
If you opt not to do this, you can tell CMake the
name of your sphinx executable using
\begin{verbatim}
  cmake -DSPHINX_EXECUTABLE=sphinx-build-2.7 ...
\end{verbatim}
for example.

Now you can build the documentation.  In the PISM build directory, do
\begin{verbatim}
  make pismpython_docs
\end{verbatim}
If you get an error like
\begin{verbatim}
  make: *** No rule to make target `pismpython_docs'.  Stop.
\end{verbatim}
then re-run \texttt{cmake ..} or  \texttt{ccmake ..}, making sure that Sphinx is installed
(see above); the  \texttt{pismpython_docs} make target will then be present.

The main page for the documentation is then in
 \texttt{doc/pismpython/html/index.html} inside your build directory. The
documentation build can take some time while it
builds a large number of small images from
\LaTeX formulas.

\end{document}