%
% 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$^b$ \\
\ \\
{\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.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 A well-optimized basic linear algebra subroutine (BLAS) library
  for vital matrix-matrix and matrix-vector multiplication routines.
  We recommend the excellent ATLAS package developed at the University
  of Tennessee.  \htmladdnormallink{{\tt
  math-atlas.sourceforge.net}}{http://math-atlas.sourceforge.net}
\item The linear algebra package (LAPACK), also available from
  netlib.org.  \PSIthree\ makes use of LAPACK's eigenvalue/eigenvector
  and matrix inversion routines.  \htmladdnormallink{{\tt
  www.netlib.org/netlib}}{http://www.netlib.org/netlib}
\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:
\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{Basic Configuration 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 autoconf}
\item {\tt mkdir objdir}
\item {\tt cd objdir}
\item {\tt ../configure}
\item {\tt make}
\item {\tt make tests} (optional, but recommended)
\item {\tt make install}
\item {\tt make doc} (optional)
\end{enumerate}

There is also a perl script, {\tt INSTALL.pl}, in the top-level 
{\tt \$PSI3} source directory which provides an interactive interface 
for installation.

\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}.
\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 gcc},
  {\tt cc}.  (NB: On AIX systems, the search order is {\tt
  cc\_r}, {\tt gcc}.)
\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 g++},
  {\tt c++}, {\tt cxx}.  (NB: On AIX systems, the search order is {\tt
  xlC\_r}, {\tt c++}, {\tt g++}.)
\item {\tt -}{\tt -with-fc=compiler} --- Use this option to specify a
  Fortran-77 compiler.  One should use compilers that generate reentrant code,
  if possible. The default search order for compilers is:
  {\tt g77}, {\tt f77}, {\tt fc}, {\tt f2c}.  (NB: On AIX systems, the
  search order is {\tt xlf\_r}, {\tt g77}, {\tt f77}, {\tt
  fc}, {\tt f2c}.)
\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-perl=perl} --- Use this option to specify a
  Perl interpreter.  The default is to look for {\tt perl} automatically.
\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'}.
\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'}.
\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=option} --- This option turns on debugging
  options.  If the argument is omitted, ``{\tt -g}'' will be used by default.
\item {\tt -}{\tt -with-opt=options} --- This option may be used to select
  special optimization flags, overriding defaults.
\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.in}.
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 automatically execute 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
psi3@psicode.org. 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.

Testing \PSIthree\ from the source directory, which was possible in
prerelease version of \PSIthree\ ({\tt rc1} and {\tt rc2}), is no longer
recommended.

\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{Miscellaneous architecture-specific notes}
\begin{itemize}

\item AIX 4.3/5.$x$ in 64-bit environment:
if IBM VisualAge C++ and IBM XL Fortran are used,
one has to manually specify
the {\tt -q64} compiler flag
that enables production of 64-bit executables.
The following configure options should be used:
{\tt -}{\tt -with-cc='cc\_r -q64 -DFCLINK=2' -}{\tt -with-cxx='xlC\_r -q64
-DFCLINK=2' -}{\tt -with-fc='xlf\_r -q64'}. Note that
the reentrant versions of the compilers
are used. Also, we haven't had much luck
using {\tt xlc\_r} because of its
handling of functions with variable argument lists,
use {\tt cc\_r} instead.

\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}.

\item Mac OS 10.$x$:

  \begin{itemize}
   \item The compilation requires a developer's toolkit from {\tt apple.com}.

   \item You need the {\tt libcompat} library. It can be obtained from Apple's 
   website at {\tt http://www.opensource.apple.com/}. Then add {\tt -lcompat} to the
   {\tt configure} flag {\tt --with-libs}.

   \item If you are using compilers from the developer's kit then for
   BLAS and LAPACK, use the configure options:
   \begin{verbatim}
   --with-blas='-altivec -framework vecLib'
   \end{verbatim}
   If you compiled compilers yourself from GNU source code then
   Apple-specific extensions will not work and you will have to specify
   the location of {\tt vecLib} manually:
   \begin{verbatim}
   --with-blas='/System/Library/Frameworks/vecLib.framework/vecLib'
   \end{verbatim}

   \item The Fortran compiler in GCC version 3.3 and higher requires the latest
   assembler, as. It can be obtained as a part of {\tt cctools} from 
   {\tt http://www.opensource.apple.com/}.  Mac OS X 10.3 (Panther) should come 
   with cctools recent enough to compile \PSIthree.

   \item Certain \PSIthree\ codes require significant stackspace for compilation.
   Increase your shell's stacksize limit before running '{\tt make}'.  For csh,
   for example, this is done using '{\tt unlimit stacksize}'.
  \end{itemize}

\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}

\end{itemize}


\end{document}
