<p><b>duda</b> 2012-10-26 17:25:02 -0600 (Fri, 26 Oct 2012)</p><p>Update build instructions.<br>
<br>
<br>
M documents/atm/mpas_users_guide.tex<br>
</p><hr noshade><pre><font color="gray">Modified: trunk/documents/atm/mpas_users_guide.tex
===================================================================
--- trunk/documents/atm/mpas_users_guide.tex 2012-10-26 22:14:14 UTC (rev 2278)
+++ trunk/documents/atm/mpas_users_guide.tex 2012-10-26 23:25:02 UTC (rev 2279)
@@ -35,42 +35,110 @@
\section{Prequisites}
-At a minimum, compatible C and Fortran compilers are needed, as is a netCDF installation
-created with those compilers. For the MPAS makefiles to find the netCDF include files and
-libraries, the environment variable {\tt NETCDF} should be set to the root directory of the netCDF installation; also, if the netCDF installation
-uses a separate Fortran interface library, {\tt -lnetcdff} will need to be added just before {\tt -lnetcdf} in the specification of {\tt LIBS} in the
-top-level Makefile.
+To build MPAS, compatible C and Fortran compilers are required. Additionally, the MPAS software relies on the PIO parallel I/O library to read and write model fields, and the PIO library requires the standard netCDF library as well as the parallel-netCDF library from Argonne National Labs. All libraries must be compiled with the same compilers that will be used to build MPAS. Section \ref{sec:build_io} summarizes the basic procedure of installing the required I/O libraries for MPAS.
-For distributed-memory parallel execution with MPI, an MPI installation such as MPICH or Open MPI
-is also needed. Currently, there is no support for shared-memory parallelism with OpenMP.
+In order for the MPAS makefiles to find the PIO, parallel-netCDF, and netCDF include files and libraries, the environment variables {\tt PIO}, {\tt PNETCDF}, and {\tt NETCDF} should be set to the root installation directories of the PIO, parallel-netCDF, and netCDF installations, respectively. Newer versions of the netCDF library use a separate Fortran interface library; the top-level MPAS Makefile attempts to add {\tt -lnetcdff} to the linker flags, but some linkers require that {\tt -lnetcdff} appear before {\tt -lnetcdf}, in which case {\tt -lnetcdff} will need to be manually added just before {\tt -lnetcdf} in the specification of {\tt LIBS} in the top-level Makefile.
-\section{Compiling}
+An MPI installation such as MPICH or Open MPI is also required, and there is no option to build a serial version of the MPAS executables. There is currently no support for shared-memory parallelism with OpenMP in the MPAS non-hydrostatic atmosphere model.
+
+\section{Compiling I/O Libraries}
+\label{sec:build_io}
+
+Although most recent versions of the I/O libraries should work, the most tested versions of these libraries are: netCDF 4.1.3, parallel-netCDF 1.3.0, and PIO 1.4.1. The netCDF and parallel-netCDF libraries must be installed before building PIO library.
+
+\subsection{netCDF}
+
+Version 4.1.3 of the netCDF library may be downloaded from \url{http://www.unidata.ucar.edu/downloads/netcdf/netcdf-4\_1\_3/index.jsp}.
+Assuming the gfortran and gcc compilers will be used, the following shell commands are generally sufficient to install netCDF.
+
+\vspace{12pt}
+{\tt > setenv FC gfortran}
+
+{\tt > setenv F77 gfortran}
+
+{\tt > setenv F90 gfortran}
+
+{\tt > setenv CC gcc}
+
+{\tt > setenv CPPFLAGS '-DpgiFortran'}
+
+{\tt > ./configure --prefix=XXXXX --disable-dap --disable-netcdf-4 --disable-cxx \hfill\break --disable-shared --enable-fortran}
+
+{\tt > make}
+
+{\tt > make install}
+\vspace{12pt}
+
+Here, {\tt XXXXX} should be replaced with the directory that will serve as the root installation directory for netCDF.
+{\em Before proceeding to compile PIO the {\tt NETCDF\_PATH} environment variable should be set to the netCDF root installation directory.}
+
+
+\subsection{parallel-netCDF}
+
+Version 1.3.0 of the parallel-netCDF library may be downloaded from \url{https://trac.mcs.anl.gov/projects/parallel-netcdf/wiki/Download}.
+Assuming the gfortran and gcc compilers will be used, the following shell commands are generally sufficient to install parallel-netCDF.
+
+\vspace{12pt}
+{\tt > setenv MPIF90 mpif90}
+
+{\tt > setenv MPIF77 mpif90}
+
+{\tt > setenv MPICC mpicc}
+
+{\tt > ./configure --prefix=XXXXX}
+
+{\tt > make}
+
+{\tt > make install}
+\vspace{12pt}
+
+Here, {\tt XXXXX} should be replaced with the directory that will serve as the root installation directory for parallel-netCDF.
+{\em Before proceeding to compile PIO the {\tt PNETCDF\_PATH} environment variable should be set to the parallel-netCDF root installation directory.}
+
+
+\subsection{PIO}
+
+Due to the rapid development pace of PIO, the preferred method of obtaining the PIO library is via subversion checkout. The PIO repository URL
+can be found at \url{http://code.google.com/p/parallelio/}.
+Assuming that all environment variable mentioned in the preceding sections are still set (including {\tt NETCDF\_PATH} and {\tt PNETCDF\_PATH}), the following shell commands are generally sufficient to build the PIO library; there is no separate installation step for PIO.
+
+\vspace{12pt}
+{\tt > svn co http://parallelio.googlecode.com/svn/trunk/pio PIO}
+
+{\tt > ./configure}
+
+{\tt > make}
+\vspace{12pt}
+
+Since PIO uses no installation step, the {\tt PIO} environment variable should be set to the directory containing the {\tt libpio.a} file (i.e., the directory where `make' was run in the final step above.
+
+
+\section{Compiling MPAS}
+
+{\em Before compiling MPAS, the {\tt NETCDF}, {\tt PNETCDF}, and {\tt PIO} environment variables must be set to the library installation directories as
+described in the previous section.}
+
The MPAS code uses only the `make' utility for compilation. Rather than employing a separate configuration step
before building the code, all information about compilers, compiler flags, etc., is contained in the top-level {\tt Makefile}; each
supported combination of compilers (i.e., a configuration) is included in the {\tt Makefile} as a separate make target, and the user selects among
these configurations by running {\tt make} with the name of a build target specified on the command-line, e.g.,
\vspace{12pt}
-{\tt > make ifort}
+{\tt > make gfortran}
\vspace{12pt}
-</font>
<font color="blue">oindent to build the code with MPI using the ifort Fortran compiler and gcc C compiler. Available targets are listed in the table below, and additional
+</font>
<font color="gray">oindent to build the code using the GNU Fortran and C compilers. Available targets are listed in the table below, and additional
targets can be added by simply editing the top-level {\tt Makefile}.
\vspace{12pt}
\begin{longtable}{| l | l | l | l |}
\hline
Target & Fortran compiler & C compiler & MPI wrappers \\ \hline \hline
-{\tt xlf-serial} & xlf90 & xlc & - \\ \hline
{\tt xlf} & xlf90 & xlc & mpxlf90 / mpcc \\ \hline
-{\tt pgi-serial} & pgf90 & pgcc & - \\ \hline
{\tt pgi} & pgf90 & pgcc & mpif90 / mpicc \\ \hline
-{\tt ifort-serial} & ifort & gcc & - \\ \hline
{\tt ifort} & ifort & gcc & mpif90 / mpicc \\ \hline
-{\tt gfortran-serial} & gfortran & gcc & - \\ \hline
{\tt gfortran} & gfortran & gcc & mpif90 / mpicc \\ \hline
-{\tt g95-serial} & g95 & gcc & - \\ \hline
{\tt g95} & g95 & gcc & mpif90 / mpicc \\ \hline
\end{longtable}
\vspace{12pt}
@@ -84,13 +152,13 @@
\vspace{12pt}
{\tt > setenv CORE nhyd\_atmos}
-{\tt > make ifort}
+{\tt > make gfortran}
\vspace{12pt}
</font>
<font color="gray">oindent or
\vspace{12pt}
-{\tt > make ifort CORE=nhyd\_atmos}
+{\tt > make gfortran CORE=nhyd\_atmos}
\vspace{12pt}
If the {\tt CORE} environment variable is set and a core is specified on the command-line, the command-line value takes precedence; if no core
@@ -108,7 +176,9 @@
{\tt > make clean}
\vspace{12pt}
+As with compiling, the core to be cleaned is specified by the {\tt CORE} environment variable, or by specifying a core explicitly on the command-line with {\tt CORE=}.
+
%--------------------------------------------------------------------------------------------
% Generating meshes
%--------------------------------------------------------------------------------------------
</font>
</pre>