\label{sec:install}

This chapter contains guidance on how to obtain a copy of NWChem and
install it on your system.   The best source for installation instructions
is the INSTALL file in the NWChem source distribution, so those
instructions will not be repeated here.  If you have problems with the
installation, you can request help from NWChem 
support via e-mail at {\tt nwchem-support@emsl.pnl.gov}.

The following subsections discuss some of the important considerations
when installing NWChem, and provide information on environmental
variables, libraries, and makefiles needed to run the code.

\section{How to Obtain NWChem}

The NWChem source code tree current release is version 5.1.1.  To obtain NWChem
a User's Agreement must be properly filled out and sent to us.  The User's
Agreement may be found on the NWChem webpages at

\begin{verbatim}
     http://www.emsl.pnl.gov:2080/docs/nwchem
\end{verbatim}

by clicking on the link "Download" and following the
instructions as they appear.  If you already have an older version of NWChem,
new download informaiton may be obtained at the location on the web.
If you have any problems
using the WWW pages or forms, or getting access to the code, send e-mail to
{\tt nwchem-support@emsl.pnl.gov}.

\section{Supported Platforms}
\label{sec:platforms}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% NOTE: this section is adapted from the current (as of 3/28/01) version of
% the script INSTALL for NWChem, in the CVS repository.  If INSTALL
% has been updated since, this section should be updated, too.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
NWChem is readily portable to essentially any sequential or parallel computer.  
The source code currently contains options for versions that will run
on the following platforms.

\begin{verbatim}

    NWCHEM_TARGET  Platform       Checked    OS/Version    Precision
    -----------------------------------------------------------------
    SOLARIS        Sun             ***      Solaris 2.X    double
    IBM            IBM RS/6000     ***      AIX 4.X        double
    DECOSF         DEC AXP         ***      Tru64 4.0-5.0  double
    SGI_N32        SGI 64 bit os   ***      IRIX 6.5       double
                   using 32 ints
    SGITFP         SGI 64 bit os   ***      IRIX 6.5       double
    CRAY-T3D       Cray T3D                 UNICOS         single
    CRAY-T3E       Cray T3E        ***      UNICOS         single
    LAPI           IBM SP          ***      AIX/LAPI       double
    LINUX          Intel x86       ***      RedHat 5.2-6.2 double
                   PowerPC         **       RedHat 6.0     double
    LINUX64        Alpha           **       RedHat 6.2     double
    HPUX           HP              **       HPUX 11.0      double
    WIN32          Intel x86        *       Windows98/NT   double
    -----------------------------------------------------------------
   *Note: LAPI is now the primary way to use NWChem on an IBM SP system.
          If you don't have it get it from IBM. 

\end{verbatim}
The environment variable {\tt NWCHEM\_TARGET} must
be set to the symbolic name
that matches your target platform.  For example, if you are installing
the code on an IBM SP, the command is

\begin{verbatim}
       % setenv NWCHEM_TARGET LAPI
\end{verbatim}

Refer to Section \ref{sec:envar} for additional discussion of environmental variables
required by NWChem.

\subsection{Porting Notes}
\label{sec:PortingNotes}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% NOTE: this section is adapted from the current (as of 9/29/98) version of
% the file Porting.notes, from ~/doc/ in the CVS repository.  If Porting.notes
% has been updated since, this section should be updated, too.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

While it is true that NWChem will run on {\em almost} any computer, there are always
a few jokers in the deck.  Here are some that have been found, and were
considered sufficiently amusing to be documented.

\begin{itemize}
\item from the Intel Paragon OSF/1 R1.2.1 (discovered 16 July 1994 by DE Bernholdt);
PGI's compilation system is braindamaged in some fascinating ways:
\begin{enumerate}
\item cpp860 by default defines {\tt \_\_PARAGON\_\_} and other things, as stated in
   the {\tt man} page, but when invoked by {\tt if77}, these things are {\em not} defined.
\item ld's -L prepends directories to the search path instead of
   appending, as is done in almost every other unix compiler package
\end{enumerate}

\item from the HP-UX 9000/735, also some others (reported 08 Feb 1996 by Jarek Nieplocha):

\begin{enumerate}
\item Avoid the "free" HP C compiler - use gcc instead:
HP cc does not generate any symbols or code for several routines in one of
the GA files. To make the user's life more entertaining, there are no 
warning or error messages either -- compiler creates a junk object file
quietly and pretends that everything went well.
(Karl Anderson says: "(HP) cc is worth every penny you paid for it.")

\item {\tt fort77} instead of {\tt f77} should be used to link fortran programs, since 
{\tt f77} doesn't support the {\tt -L} flag. Fortran code should be compiled with the 
{\tt +ppu} flag that adds underscores to the subroutine names.
\end{enumerate}

\end{itemize}


\section{Environmental Variables}
\label{sec:envar}

There are mandatory environmental variables, as well as optional ones,
 that need to be set for the compilation of NWChem to work correctly.  
The mandatory one are listed first:

\begin{table}[htbp]
\begin{center}
\begin{tabular}{lcc}
\verb+NWCHEM_TOP+                & the top directory of the NWChem tree, e.g.\\
   \verb+ setenv NWCHEM_TOP /u/adrian/nwchem+\\
\\
\verb+NWCHEM_TARGET+             & the symbolic name that matches your target
\\
                              & platform, e.g.\\
   \verb+ setenv NWCHEM_TARGET LAPI+\\
\\
\verb+NWCHEM_MODUELS+            & the modules you want included in the binary
\\
                              & that you build, e.g.\\
   \verb+ setenv NWCHEM_MODULES "all gapss"+
\end{tabular}
\end{center}
\end{table}

The following environment variables which tell NWChem more about your
system are optional.  If they are not set, NWChem will try to pick
reasonable defaults:

\begin{table}[htbp]
\begin{center}
\begin{tabular}{lcc}
   \verb+NWCHEM_TARGET_CPU+         & more information about a particular\\
                              & architechture\\
   \verb+ setenv NWCHEM_TARGET_CPU P2SC+\\
\\
   \verb+SCRATCH_DEF_DIR+           & default scratch directory for\\
                              & temporary files, e.g.\\
   \verb+ setenv SCRATCH_DEF_DIR "\'/scratch\'"+\\
 \\
   \verb+PERMANENT_DEF_DIR+         & default permanent directory for\\
                              & files to keep, e.g.\\
   \verb+ setenv PERMANENT_DEF_DIR "\'/home/user\'"+\\
 \\
   \verb+NWCHEM_BASIS_LIBRARY_PATH+ & location of the basis set libraries \\
                              & (the builder is responsible to make \\
                              & sure that the library gets to the \\
                              & place), e.g.\\
   \verb+ setenv NWCHEM_BASIS_LIBRARY_PATH "/bin/libraries/"+\\
 \\
   \verb+LARGE_FILES+               & needed to circumvent the 2 GB limit\\
                              & on IBM (note that your system \\
                              & administrator must also enable \\
                              & large files in the file system), e.g.\\
   \verb+ setenv LARGE_FILES TRUE+\\
 \\
   \verb+JOBTIME_PATH+              & directory where jobtime and jobtime.pl\\
                              & will be placed by the builder on \\
                              & IBM SP, e.g.\\
   \verb+ setenv JOBTIME_PATH /u/nwchem/bin+\\
\\
   \verb+LIB_DEFINES+               & additional defines for the C \\
                              & preprocessor (for both Fortran \\
                              & and C), e.g.\\
   \verb+ setenv LIB_DEFINES -DDFLT_TOT_MEM=16777216+\\
       This sets the dynamic memory available for \\
       NWChem to run, where the units are in doubles.\\
       Check out the Section for MEMORY SCRIPT below.\\
 \\
   \verb+TCGRSH+                    & alternate path for rsh, it is intended \\
                              & to allow usage of ssh in TCGMSG \\
                              & (default communication protocol \\
                              & for workstation builds).\\
   \verb+ setenv TCGRSH /usr/local/bin/ssh+\\
 \\
    IMPORTANT: ssh should not ask for a password.  \\
      In order to do that:\\
      1) On the master node, run "ssh-keygen"\\
      2) For each slave node, \verb+slave_node+,\\
         \verb+ scp ~/.ssh/identity.pub \+ \\
           \verb+  username@slave_node:.ssh/authorized_keys+
\end{tabular}
\end{center}
\end{table}
