\documentclass[11pt]{report}

\usepackage{epsf,amsmath,amsfonts}
\usepackage{graphicx}
\usepackage{hyperref}

\usepackage{color}

\begin{document}

\title{Instructions to Build MPAS}
\author{MPAS Development Team}

\maketitle
\tableofcontents

%-----------------------------------------------------------------------

\chapter{Summary}

This document is meant to provide instructions on how to build MPAS. It includes required libraries, some example commands on how to build both them and MPAS.

%-----------------------------------------------------------------------

\chapter{Requirements}

This section lists requirements before building MPAS. It is meant to be a list of general requirements, i.e. not core specific.

The required libraries currently are:
\begin{itemize}
	\item NETCDF
	\item PNETCDF
	\item PIO (parallel io)
\end{itemize}

The optional libraries are:
\begin{itemize}
	\item PAPI
	\item Zoltan
\end{itemize}

\chapter{Library compilation}

This section will detail where to find, and how to build the libraries required for MPAS.

\section{NETCDF}

\subsection{Download}
NETCDF can be downloaded using the following link: \\
\url{http://www.unidata.ucar.edu/downloads/netcdf/index.jsp} \\

Any version should be able to be used but tested versions include 3.6.2, 3.6.3, and 4.1.3.

\subsection{Compile}
In order to build NETCDF environment variables may need to be set up, depending on your compiler. These are listed in the table below.
\begin{tabular}{| c | c |}
	\hline
	Variable & Value name \\
	\hline
	CC & C Compiler \\
	\hline
	CXX & C++ Compiler \\
	\hline
	FC & Fortran Compiler \\
	\hline
	F77 & Fortran 77 Compiler \\
	\hline
	F90 & Fortran 90 Compiler \\
	\hline
\end{tabular}

One has to navigate into the directory that NETCDF was extracted into, and the following steps can be followed.

\begin{verbatim}
./configure --prefix=/path/to/install/into
make
make check
make install
\end{verbatim}

In the configure line, the prefix variable can be set to define the path you want the libraries located after make install is completed. The default path is /usr/local.


\section{PNETCDF}

\subsection{Download}
PNETCDF (Parallel NETCDF) can be downloaded using the following link: \\
\url{http://trac.mcs.anl.gov/projects/parallel-netcdf/wiki/Download} \\

Versions that have been tested are 1.2.0 and newer.

\subsection{Compile}

To make compiling PNETCDF easier, several environment variable can be defined. A list of these can be found below:

\begin{tabular}{| c | c |}
	\hline
	Variable & Value name \\
	\hline
	CC & C Compiler \\
	\hline
	CXX & C++ Compiler \\
	\hline
	FC & Fortran Compiler \\
	\hline
	MPICC & MPI C Compiler \\
	\hline
	MPIFC & MPI Fortran Compiler \\
	\hline
	MPIF77 & MPI Fortran 77 Compiler \\
	\hline
	MPIF90 & MPI Fortran 90 Compiler \\
	\hline
\end{tabular}

After these variables are defined, on simply has to navigate into the directory that PNETCDF was extracted into, and use the following steps.
\begin{verbatim}
./configure --prefix=/path/to/install/into
make
make install
\end{verbatim}

Again in the configure line, the prefix variable can be set to define the path you want the libraries located after make install is completed. The default path is /usr/local.

\section{PIO}

\subsection{Download}

PIO (parallel io) can be downloaded using the following link: \\
\url{http://code.google.com/p/parallelio/downloads/list} \\

Versions 1.2.6 and newer have been tested.

\subsection{Compile}

In order to compile PIO, several environment variables need to be defined. A list of these can be found below.

\begin{tabular}{| c | c |}
	\hline
	Variable & Value name \\
	\hline
	CC & C Compiler \\
	\hline
	CXX & C++ Compiler \\
	\hline
	FC & Fortran Compiler \\
	\hline
	MPICC & MPI C Compiler \\
	\hline
	MPIFC & MPI Fortran Compiler \\
	\hline
	MPIF77 & MPI Fortran 77 Compiler \\
	\hline
	MPIF90 & MPI Fortran 90 Compiler \\
	\hline
	NETCDF\_PATH & Path to where NETCDF was installed \\
	\hline
	PNETCDF\_PATH & Path to where PNETCDF was installed \\
	\hline
\end{tabular}


Assuming PIO was extracted into a pio\_root directory, one simply has to navigate into pio\_root/pio after the variables are defined. Once inside this directory, the following steps can be used:
\begin{verbatim}
./configure
make
\end{verbatim}

PIO doesn't support the prefix, or make install options. So after make is executed, the PIO libraries and include files are located in pio\_root/pio.

\chapter{MPAS Compilation}

After all the libraries are compiled, MPAS can be compiled. Any variables defined on the make line for MPAS can also be defined as environment variables. It's up to the user what their preference is.
An example of how to compile MPAS in general can be seen below.

\begin{verbatim}
make target CORE=core NETCDF=netcdf_path PNETCDF=pnetcdf_path PIO=pio_path
\end{verbatim}

Where in this example, target defines a compiler set within the MPAS makefile, core defines the target core to compile, netcdf\_path should be equivalent to the prefix used during netcdf compilation, pnetcdf\_path should be equivalent to the prefix used during pnetcdf compilation, and pio\_path should be the path to pio\_root/pio from the pio compilation section.

Example targets include, but can change at any time:
\begin{itemize}
	\item gfortran
	\item intel
	\item pgi
	\item g95
	\item xlf
	\item ftn
\end{itemize}

To get a full list of targets (although this might include other potential non-targets) the user can execute the following command from the root MPAS directory.
\begin{verbatim}
grep ":$" Makefile
\end{verbatim}

Example cores include, but can change at any time:
\begin{itemize}
	\item ocean
	\item sw (shallow-water core)
	\item hyd\_atmos
	\item nhyd\_atmos
\end{itemize}

To get a full list of available cores, the use can execute the following command from the root MPAS directory.
\begin{verbatim}
ls src/ | grep ``core_''
\end{verbatim}

Assuming make succeeded, a new executable named core\_model.exe should exist in the directory, which can be used to run MPAS.

\chapter{Appendix - Machine/Compiler Specific Issues}

\section{gFortran issues}
Some versions of gfortran don't support lines longer than 77 characters. In order to fix this issue, the FFLAGS environment variable should include the -ffree-line-length-0 flag. This should be done throughout all library compilations, to be safe. The issue has only been noticed when compiling PIO however.

\section{PGI Issue with Ocean Core}
The PGI compiler does not support the subroutine isNaN. In order to build mpas with PGI, the calls to isNaN need to be commented out. These can be found in the following files.
\begin{verbatim}
src/core_ocean/mpas_ocean_time_integration.F
\end{verbatim}



\end{document}

