%
% The PSI Installation Manual
%

\documentclass[12pt]{article}
\usepackage{html}
\setlength{\textheight}{9in}
\setlength{\textwidth}{6.5in}
\setlength{\hoffset}{0in}
\setlength{\voffset}{0in}
\setlength{\headheight}{0in}
\setlength{\headsep}{0in}
\setlength{\topmargin}{0in}
\setlength{\oddsidemargin}{-0.05in}
\setlength{\evensidemargin}{-0.05in}
\setlength{\marginparsep}{0in}
\setlength{\marginparwidth}{0in}
\setlength{\parsep}{0.8ex}
\setlength{\parskip}{1ex plus \fill}
\baselineskip 18pt
\renewcommand{\topfraction}{.8}
\renewcommand{\bottomfraction}{.2}

\begin{document}
\include{macros}

\begin{center}
\ \\
\vspace{2.0in}
{\bf {\Large Installation Manual for the \PSIthree\ Program Package}} \\
\vspace{0.5in}
T.\ Daniel Crawford,$^a$ C.\ David Sherrill,$^b$ and Edward F.\ Valeev$^{a}$ 
\\ \  \\
{\em $^a$Department of Chemistry, Virginia Tech, Blacksburg, 
Virginia 24061-0001} \\
\vspace{0.1in}
{\em $^b$Center for Computational Molecular Science and Technology, 
\mbox{Georgia Institute of Technology,} Atlanta, Georgia 30332-0400} \\
\vspace{0.1in}
\ \\
\vspace{0.3in}
\PSIthree\ Version: \PSIversion \\
Created on: \today
\end{center}

\thispagestyle{empty}

\newpage
\section{Compilation Prerequisites}

The following external software packages are needed to complile \PSIthree:
\begin{itemize}
\item C, C++, and FORTRAN77 compilers. The FORTRAN77 compiler is only
  used to determine the symbol-naming convention of and some system
  routines for the BLAS and LAPACK libraries on some architectures. It
  is optional in a few cases (e.g. Mac OS X systems).
\item A well-optimized basic linear algebra subroutine (BLAS) library
  for vital matrix-matrix and matrix-vector multiplication
  routines. (See recommendations below.)
\item The linear algebra package (LAPACK).  \PSIthree\ makes use of
  LAPACK's eigenvalue/eigenvector and matrix inversion routines.  (See
  recommendations below)
\item POSIX threads (Pthreads) library
\item Perl interpreter (version 5.005 or higher)
\item Various GNU utilies: \htmladdnormallink{{\tt
www.gnu.org}}{http://www.gnu.org}
\begin{itemize}
\item {\tt autoconf (version 2.52 or higher)}
\item {\tt make}
\item {\tt flex}
\item {\tt bison}
\item {\tt fileutils} (esp.\ {\tt install})
\end{itemize}
\item For documentation only:
\begin{itemize}
\item {\tt LaTeX}
\item {\tt LaTeX2html} (v0.99.1 or 1.62, including the patch supplied in
psi3/misc)
\end{itemize}
\end{itemize}

\section{Brief Summary of Configuration, Compilation, and Installation}

A good directory for the \PSIthree\ source code is /usr/local/src/psi3.
The directory should {\em not} be named {\tt /usr/local/psi}, as that is
the default installation directory unless changed by the {\tt --prefix}
directive (see below).  It should also not have any periods in the path,
e.g., {\tt /usr/local/psi3.2}, because of a bug in {\tt dvips} which will
cause the compilation of documentation to fail.

The following series of steps will configure and build the \PSIthree\
package and install the executables in /usr/local/psi/bin:

\begin{enumerate}
\item {\tt cd \$PSI3} (your top-level \PSIthree\ source directory)
\item {\tt mkdir objdir}
\item {\tt cd objdir}
\item {\tt ../configure} (may need some of the options below, esp.~if
  {\tt blas} or {\tt lapack} are in non-standard locations)
\item {\tt make}
\item {\tt make tests} (optional, but recommended)
\item {\tt make install}
\item {\tt make doc} (optional)
\end{enumerate}

\noindent
You may need to make use of one or more of the following options to
the {\tt configure} script:
\begin{itemize}
\item {\tt -}{\tt -prefix=directory} --- Use this option if you wish to
  install the \PSIthree\ package somewhere other than the default
  directory, {\tt /usr/local/psi}.  This directory will contain
  subdirectories with the final installed binaries, libraries, 
  documentation, and shared data files.
\item {\tt -}{\tt -with-cc=compiler} --- Use this option to specify a
  C compiler.  One should use compilers that generate reentrant code,
  if possible.  The default search order for compilers is: {\tt cc\_r} (AIX
  only), {\tt gcc}, {\tt icc}, {\tt cc}.
\item {\tt -}{\tt -with-cxx=compiler} --- Use this option to specify a
  C++ compiler.  One should use compilers that generate reentrant
  code, if possible. The default search order for compilers is: {\tt xlC\_r}
  (AIX only), {\tt g++}, {\tt c++}, {\tt icpc}, {\tt cxx}.
\item {\tt -}{\tt -with-fc=compiler} --- Use this option to specify a
  Fortran-77 compiler, which is used to determine linking coventions
  for BLAS and LAPACK libraries and to provide system routines for
  those libraries.  Note that no fortran compiler is necessary on Mac
  OS X systems (see below).  The default search order for compilers
  is: {\tt xlf\_r} (AIX only), {\tt gfortran}, {\tt g77}, {\tt ifort},
  {\tt f77}, {\tt f2c}.
\item {\tt -}{\tt -with-f77-symbol=value} --- This option allows manual
  assignment of the F77 symbol convention, which is necessary for C
  programs to link Fortran-interface libraries such as BLAS and
  LAPACK. This option should only be used by experts and even then
  should almost never be necessary.  Allowed values are:
\begin{itemize}                            
\item[lc] lower-case
\item[lcu]lower-case with underscore (default)
\item[uc] upper-case
\item[ucu] upper-case with underscore
\end{itemize}
\item {\tt -}{\tt -with-ld=linker} --- Use this option to specify
  a linker program. The default is {\tt ld}.
\item {\tt -}{\tt -with-ranlib=ranlib} --- Use this option to specify
  a ranlib program. The default behavior is to detect an appropriate
  choice automatically.
\item {\tt -}{\tt -with-ar=archiver} --- Use this option to specify an
  archiver.  The default is to look for {\tt ar} automatically.
\item {\tt -}{\tt -with-ar-flags=options} --- Use this option to specify
  archiver command-line flags. The default is {\tt r}.
\item {\tt -}{\tt -with-incdirs=directories} --- Use this option to
  specify extra directories where to look for header
  files. Directories should be specified prepended by {\tt -I},
  i.e. {\tt -Idir1 -Idir2}, etc. If several directories are specified,
  enclose the list with single right-quotes, e.g., {\tt -}{\tt
    -with-incdirs='-I/usr/local/include -I/home/psi3/include'}.
\item {\tt -}{\tt -with-libs=libraries} --- Use this option to specify
  extra libraries which should be used during linking. Libraries
  should be specified by their full names or in the usual {\tt -l}
  notation, i.e. {\tt -lm /usr/lib/libm.a}, etc.  If several libraries
  are specified, enclose the list with single right-quotes, e.g., {\tt
    -}{\tt -with-libs='-lcompat /usr/local/lib/libm.a'}.
\item {\tt -}{\tt -with-libdirs=directories} --- Use this option to
  specify extra directories where to look for libraries. Directories
  should be specified prepended by {\tt -L}, i.e. {\tt -Ldir1 -Ldir2},
  etc. If several directories are specified, enclose the list with
  single right-quotes, e.g., {\tt -}{\tt
    -with-libdirs='-L/usr/local/lib -I/home/psi3/lib'}.
\item {\tt -}{\tt -with-blas=library} --- Use this option to specify a
  BLAS library.  If your BLAS library has multiple components, enclose
  the file list with single right-quotes, e.g., {\tt -}{\tt
    -with-blas='-lf77blas -latlas'}.  Note that many BLAS libraries
  can be detected automatically.
\item {\tt -}{\tt -with-lapack=library} --- Use this option to specify
  a LAPACK library.  If your LAPACK library has multiple components,
  enclose the file list with single right-quotes, e.g., {\tt -}{\tt
    -with-lapack='-llapack -lcblas -latlas'}.  note that many LAPACK
  libraries can be detected automatically.
\item {\tt -}{\tt -with-max-am-eri=integer} --- Specifies the maximum
  angular momentum level for the primitive Gaussian basis functions
  when computing electron repulsion integrals.  This is set to
  $g$-type functions (AM=4) by default.
\item {\tt -}{\tt -with-max-am-deriv1=integer} --- Specifies the maximum
  angular momentum level for first derivatives of the primitive
  Gaussian basis functions.  This is set to $f$-type functions (AM=3)
  by default.
\item {\tt -}{\tt -with-max-am-deriv2=integer} --- Specifies the maximum
  angular momentum level for second derivatives of the primitive
  Gaussian basis functions.  This is set to $d$-type functions (AM=2)
  by default.
\item {\tt -}{\tt -with-max-am-r12=integer} --- Specifies the maximum
  angular momentum level for primitive Gaussian basis functions used
  in $r_{12}$ explicitly correlated methods.  This is set to $f$-type
  functions (AM=3) by default.
\item {\tt -}{\tt -with-debug=yes/no} --- This option turns on debugging
  options.  This is set to {\tt no} by default.
\item {\tt -}{\tt -with-opt=options} --- Turn off compiler
  optimizations if {\tt no}.  This is set to {\tt yes} by default.
\item {\tt -}{\tt --with-strict=yes} -- Turns on strict compiler warnings.
\end{itemize}

\section{Detailed Installation Instructions}

This section provides detailed instructions for compiling and
installing the \PSIthree\ package.  

\subsection{Step 1: Configuration}

First, we recommend that you choose for the top-level {\tt \$PSI3}
source directory something other than {\tt /usr/local/psi}; your {\tt
  \$HOME} directory or {\tt /usr/local/src/psi3} are convenient
choices.  Next, in the top-level {\tt \$PSI3} source directory you've
chosen, first run {\tt autoconf} to generate the configure script from
{\tt configure.ac}.  It is best to keep the source code separate from
the compilation area, so you must choose a subdirectory for
compilation of the codes.  A simple option is {\tt \$PSI3/objdir},
which should work for most environments.  However, if you need
executables for several architectures, choose more meaningful
subdirectory names.

$\bullet$ The compilation directory will be referred to as {\tt \$objdir}
for the remainder of these instructions.

In {\tt \$objdir}, run the configure script found in the {\tt \$PSI3}
top-level source directory.  This script will scan your system to locate
certain libraries, header files, etc. needed for complete compilation.
The script accepts a number of options, all of which are listed above.
The most important of these is the {\tt --prefix} option, which selects the
installation directory for the executables, the libraries, header files,
basis set data, and other administrative files.  The default {\tt -}{\tt -prefix}
is {\tt /usr/local/psi}.

$\bullet$ The configure script's {\tt -}{\tt -prefix} directory will be referred
to as {\tt \$prefix} for the remainder of these instructions.

\subsection{Step 2: Compilation}

Running {\tt make} (which must be GNU's {\tt 'make'} utility) in {\tt
\$objdir} will compile the \PSIthree\ libraries and executable
modules.

\subsection{Step 3: Testing}

To execute automatically the ever-growing number of test cases after
compilation, simply execute ``make tests'' in the {\tt \$objdir}
directory.  This will run each (relatively small) test case and report
the results.  Failure of any of the test cases should be reported to
the developers at \PSIemail. By default, any such failure will stop
the testing process.  If you desire to run the entire testing suit
without interruption, execute ``make tests TESTFLAGS='-u -q' ''. Note
that you must do a ``make testsclean'' in {\tt \$objdir} to run the test
suite again.

\subsection{Step 4: Installation}

Once testing is complete, installation into \$prefix is accomplished by
running {\tt make install} in {\tt \$objdir}.   Executable modules are
installed in {\tt \$prefix/bin}, libraries in {\tt \$prefix/lib} and basis 
set data and other control strctures {\tt \$prefix/share}.

\subsection{Step 5: Documentation}

If your system has the appropriate utilities, you may build the package
documentation from the top-level {\tt \$objdir} by running {\tt make doc}.  
The resulting files will appear in the {\tt \$prefix/doc} area.

\subsection{Step 6: Cleaning}

All compilation-area object files and libraries can be removed to save
disk space by running {\tt make clean} in {\tt \$objdir}.

\subsection{Step 7: User Configuration}

After the \PSIthree\ package has been successfullly installed, the user will
need to add the installation directory into their path.  If the package
has been installed in the default location {\tt /usr/local/psi3}, then
in C shell, the user should add something like the following to 
their {\tt .cshrc} file:
\begin{verbatim}
setenv PSI /usr/local/psi3
set path = ($path $PSI/bin)
setenv MANPATH $PSI/doc/man:$MANPATH
\end{verbatim}
The final line will enable the use of the \PSIthree\ man pages.
\begin{verbatim}
\end{verbatim}

\section{Recommendations for BLAS and LAPACK Libraries}

Much of the speed and efficiency of the PSI3 programs depends on the
corresponding speed and efficiency of the available BLAS and LAPACK
libraries (especially the former).  In addition, the most common
compilation problems involve these libraries.  Users may therefore
wish to consider the following BLAS and LAPACK recommendations when
building PSI3:

\begin{itemize}
\item It is NOT wise to use the stock BLAS library provided with many
  Linux distributions like RedHat.  This library is usually just the
  netlib ({http://netlib.org/}distribution and is completely
  unoptimized.  PSI3's performance will suffer if you choose this
  route.  The choice of LAPACK is less critical, and so the
  unoptimized netlib distribution is acceptable.  If you do choose to
  use the RedHat/Fedora stock BLAS and LAPACK, be aware that some
  RPM's do not make the correct symbolic links.  For example, you may
  have {\tt /usr/lib/libblas.so.3.1.0} but not {\tt
    /usr/lib/libblas.so}.  If this happens, create the link as, e.g.,
  {\tt ln -s /usr/lib/libblas.so.3.1.0 /usr/lib/libblas.so}.  You may
  need to do similarly for lapack.

\item Perhaps the best choices for BLAS are Kazushige Goto's
  hand-optimized BLAS \\
({\tt http://www.tacc.utexas.edu/resources/software/}) and ATLAS \\ ({\tt
http://math-atlas.sourceforge.net/}).  These work well on nearly
  every achitecture to which the PSI3 developers have access, though we have
  identified at least one case in which the Goto libraries yielded faulty
  DGEMM call.  On Mac OS X systems, however, the {\tt vecLib} package that
  comes with Xcode works well. Note also that we have encountered problems
with the  version 10 of Intel's MKL, particularly for very large coupled
cluster  calculations.

\item PSI3 does not require a Fortran compiler, unless the resident
  BLAS and LAPACK libraries require Fortran-based system libraries.
  If you see compiler complaints about missing symbols like ``{\tt
    do\_fio}'' or ``{\tt e\_wsfe}'' then your libraries were most likely
  compiled with g77 or gfortran, which require {\tt -lg2c} to resolve
  the Fortran I/O calls.  Use of the same gcc package for PSI3 should
  normally resolve this problem.

\item The PSI3 configure script can often identify and use
  several different BLAS and LAPACK libraries, but its ability to do
  this automatically depends on a number of factors, including
  correspondence between the compiler used for PSI3 and the compiler
  used to build BLAS/LAPACK, and placement of the libraries in
  commonly searched directories, among others.  PSI3's configure
  script will find your BLAS and LAPACK if any of the the following
  are installed in standard locations (e.g. {\tt /usr/local/lib}):

\begin{itemize}  
    \item ATLAS: {\tt libf77blas.a} and {\tt libatlas.a}, plus netlib's
    {\tt liblapack.a}
    \item MKL 8: {\tt libmkl.so} and {\tt libmkl\_lapack64.a} (with the corresponding Intel compilers)
    \item Goto: {\tt libgoto.a} and netlib's {\tt liblapack.a}
    \item Cray SCSL (e.g. on SGI Altix): {\tt libscs.so} (NB: No Fortran compiler
      is necessary in this case, so {\tt -}{\tt -with-fc=no} should work.)
    \item ESSL (e.g. on AIX systems): {\tt libessl.a}
    \end{itemize}  
  \item If configure cannot identify your BLAS and LAPACK libraries
    automatically, you can specify them on the command-line using the
    {\tt -}{\tt -with-blas} and {\tt -}{\tt -with-lapack} arguments
    described above.  Here are a few examples that work on the PSI3
    developers' systems:
  
    (a) Linux with ATLAS:
  
    {\tt -}{\tt -with-blas='-lf77blas -latlas'} {\tt -}{\tt -with-lapack='-llapack -lcblas'}

    (b) Mac OS X with vecLib: 
  
    {\tt -}{\tt -with-blas='-altivec -framework vecLib'} {\tt -}{\tt -with-lapack=' '}
  
    (c) Linux with MKL 8.1 and {\tt icc/icpc/ifort} 9.1: 
  
    {\tt -}{\tt -with-libdirs=-L/usr/local/opt/intel/mkl/8.0.2/lib/32} {\tt -}{\tt -with-blas=-lmkl} {\tt -}{\tt -with-lapack=-lmkl\_lapack32}
\end{itemize}

    (d) Linux on ia32 with MKL 10.1 and {\tt icc/icpc} 11.0:

    {\tt -}{\tt -with-blas='-Wl,--start-group -L/usr/local/opt/intel/mkl/10.1.0.015/lib/32 -lmkl -Wl,}{\tt -}{\tt -end-group -lguide -lpthread'}

\section{Miscellaneous architecture-specific notes}
\begin{itemize}

\item Linux on x86 and x86\_64:
  \begin{itemize}
   \item {\tt gcc} compiler: versions 3.2, 3.3, 3.4, 4.0, and 4.1 have been tested.
   \item Intel compilers: versions 9.0 and 11.0 have been tested. We do not 
   recommend using version 8.1.
   \item Portland Group compilers: version 6.0-5 has been tested.
   \item Some versions of RedHat/Fedora Core RPM packages for the 
   BLAS and LAPACK libraries fail to make all the required symlinks.  
   For example, you may have {\tt /usr/lib/libblas.so.3.1.0} but not
   {\tt /usr/lib/libblas.so}.  If this happens, create the link as, e.g.,
   {\tt ln -s /usr/lib/libblas.so.3.1.0 /usr/lib/libblas.so}.  You
   may need to do something similar for lapack.
  \end{itemize}

\item Linux on Itanium2 (IA64):
  \begin{itemize}
   \item Intel compiler versions 9.0 and 10.0 have been tested and work.
   Version 8.1 does not work.  
   \item {\tt gcc} compilers work.
  \end{itemize}

\item Mac OS 10.$x$:

  \begin{itemize}
  \item The compilation requires a developer's toolkit (Xcode) from
    {\tt apple.com}.  Note that a fortran compiler is not needed for
    PSI 3.4 on Mac OS X systems.

  \item The {\tt libcompat.a} library is no longer needed as of 1/24/2008.

  \item For apple systems, the latest configure script assumes that the
  {\tt vecLib} will be used for the optimized BLAS and LAPACK
  libraries, unless the user indicates otherwise using the {\tt -}{\tt
    -with-blas} and {\tt -}{\tt -with-lapack} flags to configure.  If
  you encounter difficulty with configure, you may have success
  explicitly indicating the vecLib using:

      {\tt -}{\tt -with-blas='-altivec -framework vecLib'} {\tt -}{\tt
        -with-lapack=' '}

  \item Pre Mac OS 10.4: Certain PSI3 codes require significant
      stackspace for compilation.  Increase your shell's stacksize
      limit before running {\tt make}.  For csh, for example, this is
      done using ``unlimit stacksize.''  [NB: This limit appears to have
      been lifted starting with Mac OS 10.3.X (Panther).]

  \item Mac 10.5 users can take advantage of the ruby driver in PSI 3.4 by
   including the following options on the configure command line:

   {\tt -}{\tt -with-ruby-include='-I/System/Library/Frameworks/Ruby.framework/Headers'} {\tt -}{\tt -with-ruby-lib='-framework Ruby'}

  \end{itemize}

\item AIX in a 64-bit environment:

We do not presently support the use of XL compilers on AIX systems.  We 
have tested gcc-4.1.1 under AIX 5.3, and we recommend use of the 
configure flag: {\tt -}{\tt -with-aix64}.


\item SGI IRIX 6.$x$:
  \begin{itemize}
   \item MIPSpro C++ compilers prior to version 7.4 require a command-line flag
   '{\tt -LANG:std}' in order to compile \PSIthree\ properly.

   \item Use command-line flag '{\tt -64}' in order to produce 64-bit \PSIthree\ executables with
   MIPSpro compilers. The following is an example of appropriate configure options:
   \begin{verbatim}
  --with-cc='cc -64' --with-cxx='CC -64 -LANG:std' --with-fc='f77 -64'
   \end{verbatim}

   \item Under IRIX configure will attempt to detect automatically and use
   the optimized SGI Scientific Computing Software Library (SCSL).
  \end{itemize}

\item Compaq Alpha/OSF 5.1: default shell ({\tt /bin/sh})
is not POSIX-compliant which causes some \PSIthree\ makefiles
to fail. Set environmental variable {\tt BIN\_SH} to {\tt xpg4}.

\end{itemize}


\end{document}