1. PFLOTRAN
  2. code
  3. pflotran-dev

Source

pflotran-dev / docs / user_manual / quick_start.tex

\section{Quick Start}

For those adverse to reading manuals the following is a quick start guide to getting up and running with PFLOTRAN in four easy steps.

\begin{description}
\item[Required Software Packages] ~
\begin{itemize}
\item Compilers (compatible with Fortran 2003: gcc 4.7.x, Intel 12.1.x, PGI)

For MacOSX 10.8.2 the latest Fortran compiler binaries (gcc/gfortran 4.8 at the time of this writing) may be downloaded from the web site \href{http://hpc.sourceforge.net}{HPC for MacOSX}.

%{\footnotesize\tt http://hpc.sourceforge.net}.

\item Mercurial (hg) (version control system)
\item CMAKE (version 2.8.x)
\item Developer version of PETSc: \href{http://www.mcs.anl.gov/petsc/developers/index.html}{petsc-dev}
\begin{itemize}
\item MPI (for running in parallel)
\item BLAS/LAPACK libraries
\item HDF5 (parallel output)
\item METIS/ParMETIS (unstructured grids)
\end{itemize}
\item \href{https://bitbucket.org/pflotran/pflotran-dev}{PFLOTRAN}
\end{itemize}
\end{description}

\subsection{Installing PFLOTRAN}

\begin{description}
\item[Step 1: Installing PETSc] The first step is to download the developer version of PETSc, \href{http://www.mcs.anl.gov/petsc/developers/index.html}{petsc-dev}. To do this follow the directions at the PETSc Developer web site. The recommended approach is to use \href{http://mercurial.selenic.com/}{Mercurial}---also needed to obtain the PFLOTRAN source code. Mercurial(hg) is the version control system used by both PETSc and PFLOTRAN. Often one can find executables for particular platforms and there is no need to compile the application from scratch. On a UNIX system you can check to see if Mercurial is already installed by issuing the command: {\footnotesize\tt which hg}.

To compile PETSc it is first necessary to configure the makefile. To this end define the environmental variables {\footnotesize\tt PETSC\_DIR} and {\footnotesize\tt PETSC\_ARCH} pointing to the directory where petsc-dev is installed and an identifying name for the installation, respectively. E.g. if using the t-shell on MacOSX 10.8.2 and gcc-4.8 enter into the .tcshrc file:

{\footnotesize\tt setenv PETSC\_DIR `path to petsc-dev`}

and

{\footnotesize\tt setenv PETSC\_ARCH MacOSX-10.8.2-gcc4.8}.

Finally, set the environmental variable {\footnotesize\tt MPI\_HOME} and add to the {\footnotesize\tt PATH} variable:
\footnotesize
\begin{Verbatim}
setenv MPI_HOME ${PETSC_DIR}/${PETSC_ARCH}
setenv PATH $MPI_HOME/bin:$PATH
\end{Verbatim}
\normalsize
Decide which options are needed for running PFLOTRAN: structured grids are the simplest; if unstructured grids are needed then install METIS and ParMETIS. See Table~\ref{tinstall} for several of the different configure options possible.

For example, to configure PETSC to run in production mode and install openmpi, HDF5, METIS and ParMETIS use:
\footnotesize
\begin{Verbatim}
cd ./petsc-dev

./config/configure.py --with-debugging=0 --with-shared-libraries=0 --with-x=0 
--download-openmpi=1 --download-hdf5=1 --download-metis=1 --download-parmetis=1
\end{Verbatim}
\normalsize

\noindent
Check to make sure {\footnotesize\tt mpicc} and {\footnotesize\tt mpif90} are working and are recent versions that are compatible with Fortran 2003: e.g. GNU gfortran version 4.7.x, Intel version 12.x or PGI.

\begin{table}[H]\centering
\caption{Options for configuring petsc-dev.}
\label{tinstall}

\vspace{3mm}

\begin{tabular}{llcl}
\toprule
& Option & Package\\
\midrule
MPI & Parallel & \href{http://www.open-mpi.org/}{OpenMPI} & --download-openmpi=1\\
&& \href{http://www.mpich.org/}{MPICH} &--download-mpich=1\\
\midrule
Grid & Structured & ---\\
& Unstructured & \href{http://glaros.dtc.umn.edu/gkhome/views/metis}{METIS} and \href{http://glaros.dtc.umn.edu/gkhome/views/metis}{ParMETIS}$^*$ & --download-metis=1\\
&&& --download-parmetis=1\\
\midrule
Output & TecPlot, VTK & ---\\
& HDF5 & Parallel \href{http://www.hdfgroup.org/HDF5/}{HDF5} & --download-hdf5=1\\
\midrule
Solvers & Iterative (GMRES)/Direct & ---\\
%& Direct & \\
& Parallel Direct & \href{http://graal.ens-lyon.fr/MUMPS/}{MUMPS} & --download-mumps=1\\
& Multigrid & \href{http://trilinos.sandia.gov/packages/ml/}{ML} & --download-ml=1\\
& Preconditioners & \href{http://acts.nersc.gov/hypre/}{Hypre} & --download-hypre=1\\
\bottomrule
\multicolumn{2}{l}{$^*$ Need CMAKE}
\end{tabular}
\end{table}

\item[Step 2: Downloading PFLOTRAN] PFLOTRAN can be downloaded from bitbucket.org using Mercurial (hg):

{\footnotesize\tt hg clone https://bitbucket.org/pflotran/pflotran-dev}.

\item[Step 3: Compiling PFLOTRAN] Once PETSc and associated third party software has been installed, it is easy to install PFLOTRAN. To compile PFLOTRAN first decide on the options needed to run your problem. The most common of these are listed in Table~\ref{topt}.

\begin{table}[H]\centering
\caption{Compile options for PFLOTRAN.}

\vspace{3mm}

\label{topt}
\begin{tabular}{ll}
\toprule
Option & \multicolumn{1}{c}{Description}\\
\midrule
scco2=1 & MPHASE mode for supercritical CO$_2$\\
scorpio=1 & SCORPIO$^{*}$ parallel IO\\
%mfd=1 & Mimetic finite difference for full permeability tensor\\
\bottomrule
\multicolumn{2}{l}{$^{*}$ See \S\ref{parallelio} for installing SCORPIO.}
\end{tabular}

\end{table}

\footnotesize
\begin{Verbatim}
cd PLOTRAN_DIR/src/pflotran
make [options] ./pflotran
\end{Verbatim}
\normalsize

For example: {\footnotesize\tt make scco2=1 ./ppflotran}

\item[Step 4: Running PFLOTRAN] PFLOTRAN is run in parallel on {\tt N} cores using the command:

{\footnotesize\tt mpirun -np N ./pflotran -pflotranin input\_file\_name.in}

with input file {\footnotesize\tt input\_file\_name.in}. The default input file name is simply {\footnotesize\tt pflotran.in}.
\end{description}

\noindent
To get the most out of PFLOTRAN subscribe to the PFLOTRAN User Group:

{\footnotesize\tt pflotran-users@googlegroups.com}.

\noindent
PFLOTRAN developers monitor this site and will as quickly as possible respond to your queries.

The final challenge is setting up an input file. Various modes available are listed in Table~\ref{tmodes} and example input decks are stored in the {\footnotesize\tt ./pflotran/example\_problems} and \linebreak {\footnotesize\tt ./pflotran/shortcourse} directories.

\begin{table}[H]\centering
\caption{Available modes in PFLOTRAN}
\label{tmodes}
\vspace{3mm}
\begin{tabular}{lcc}
\toprule
MODE & \multicolumn{1}{c}{Description} & Required Databases$^\dag$\\
\midrule
RICHARDS & Solves Richards equation & ---\\
MPHASE & Supercritcal CO$_2$ & {\tt co2data0.dat} \\
TH & Thermal-Hydrology mode & ---\\
CHEMISTRY & Reactive Transport & {\tt hanford.dat}$^\ddag$ \\
\bottomrule
\end{tabular}

\vspace{3mm}

\parbox{4.5in}{
\indent $^\dag$ Provided with the PFLOTRAN distribution in directory {\tt ./pflotran/database}.

\medskip

\indent $^\ddag$ An equivalent user supplied thermodynamic database for chemical reactions may also be used (see \S\ref{thermo:database} for a description of the database format). 
}
\end{table}

An example input file is listed in \S\ref{exinput} for a coupled problem using Richards and Chemistry modes.

\subsection{Running on Big Iron Parallel Architectures}

Generally these machines use {\footnotesize\tt module} to load the computing environment.
Make sure the correct compilers are loaded that are compatible with Fortran 2003. The following instructions apply to Yellowstone running Red Hat linux using the Intel compiler. As MPI is already installed it is not necessary to reinstall it through PETSc.

\noindent
Use a recent version of CMAKE: {\footnotesize\tt module load cmake/2.8.10.2}.

\noindent Set the environmental variable for the BLAS/LAPACK libraries to use MKL:

\noindent
{\footnotesize\tt setenv BLAS\_LAPACK\_LIB\_DIR /ncar/opt/intel/12.1.0.233/composer\_xe\_2013.1.117/mkl}

\noindent
Configure PETSc:
\footnotesize
\begin{Verbatim}
./config/configure.py --with-cc=mpicc --with-fc=mpif90 --with-cxx=mpicxx 
--with-clanguage=c --with-blas-lapack-dir=$BLAS_LAPACK_LIB_DIR 
--with-shared-libraries=0 --with-debugging=0 --download-hdf5=yes 
--download-parmetis=yes --download-metis=yes
\end{Verbatim}
\normalsize

%\subsection{Debug Mode}

%To install Valgrind