2
% The PSI Installation Manual
5
\documentclass[12pt]{article}
7
\setlength{\textheight}{9in}
8
\setlength{\textwidth}{6.5in}
9
\setlength{\hoffset}{0in}
10
\setlength{\voffset}{0in}
11
\setlength{\headheight}{0in}
12
\setlength{\headsep}{0in}
13
\setlength{\topmargin}{0in}
14
\setlength{\oddsidemargin}{-0.05in}
15
\setlength{\evensidemargin}{-0.05in}
16
\setlength{\marginparsep}{0in}
17
\setlength{\marginparwidth}{0in}
18
\setlength{\parsep}{0.8ex}
19
\setlength{\parskip}{1ex plus \fill}
21
\renewcommand{\topfraction}{.8}
22
\renewcommand{\bottomfraction}{.2}
30
{\bf {\Large Installation Manual for the \PSIthree\ Program Package}} \\
32
T.\ Daniel Crawford,$^a$ C.\ David Sherrill,$^b$ and Edward F.\ Valeev.$^{b,c}$ \\
34
{\em $^a$Department of Chemistry, Virginia Tech, Blacksburg, Virginia 24061-0001} \\
36
{\em $^c$Center for Computational Molecular Science and Technology, \mbox{Georgia
37
Institute of Technology,} Atlanta, Georgia 30332-0400} \\
39
{\em $^b$\mbox{Oak Ridge National Laboratory,} Oak Ridge, Tennessee 37831-6367}\\
42
\PSIthree\ Version: \PSIversion \\
49
\section{Compilation Prerequisites}
51
The following external software packages are needed to complile \PSIthree:
53
\item C, C++, and FORTRAN77 compilers. The FORTRAN77 compiler is only used to determine
54
the symbol convention of BLAS and LAPACK libraries.
55
\item A well-optimized basic linear algebra subroutine (BLAS) library
56
for vital matrix-matrix and matrix-vector multiplication routines.
57
We recommend the excellent ATLAS package developed at the University
58
of Tennessee. \htmladdnormallink{{\tt
59
math-atlas.sourceforge.net}}{http://math-atlas.sourceforge.net}
60
\item The linear algebra package (LAPACK), also available from
61
netlib.org. \PSIthree\ makes use of LAPACK's eigenvalue/eigenvector
62
and matrix inversion routines. \htmladdnormallink{{\tt
63
www.netlib.org/netlib}}{http://www.netlib.org/netlib}
64
\item POSIX threads (Pthreads) library
65
\item Perl interpreter (version 5.005 or higher)
66
\item Various GNU utilies: \htmladdnormallink{{\tt
67
www.gnu.org}}{http://www.gnu.org}
69
\item {\tt autoconf (version 2.52 or higher)}
73
\item {\tt fileutils} (esp.\ {\tt install})
75
\item For documentation:
78
\item {\tt LaTeX2html} (v0.99.1 or 1.62, including the patch supplied in
83
\section{Basic Configuration and Installation}
85
A good directory for the \PSIthree\ source code is /usr/local/src/psi3.
86
The directory should {\em not} be named {\tt /usr/local/psi}, as that is
87
the default installation directory unless changed by the {\tt --prefix}
88
directive (see below). It should also not have any periods in the path,
89
e.g., {\tt /usr/local/psi3.2}, because of a bug in {\tt dvips} which will
90
cause the compilation of documentation to fail.
92
The following series of steps will configure and build the \PSIthree\
93
package and install the executables in /usr/local/psi/bin:
96
\item {\tt cd \$PSI3} (your top-level \PSIthree\ source directory)
98
\item {\tt mkdir objdir}
100
\item {\tt ../configure}
102
\item {\tt make tests} (optional, but recommended)
103
\item {\tt make install}
104
\item {\tt make doc} (optional)
107
There is also a perl script, {\tt INSTALL.pl}, in the top-level
108
{\tt \$PSI3} source directory which provides an interactive interface
112
You may need to make use of one or more of the following options to
113
the {\tt configure} script:
115
\item {\tt -}{\tt -prefix=directory} --- Use this option if you wish to
116
install the \PSIthree\ package somewhere other than the default
117
directory, {\tt /usr/local/psi}.
118
\item {\tt -}{\tt -with-cc=compiler} --- Use this option to specify a C
119
compiler. One should use compilers that generate reentrant code,
120
if possible. The default search order for compilers is: {\tt gcc},
121
{\tt cc}. (NB: On AIX systems, the search order is {\tt
123
\item {\tt -}{\tt -with-cxx=compiler} --- Use this option to specify a C++
124
compiler. One should use compilers that generate reentrant code,
125
if possible. The default search order for compilers is: {\tt g++},
126
{\tt c++}, {\tt cxx}. (NB: On AIX systems, the search order is {\tt
127
xlC\_r}, {\tt c++}, {\tt g++}.)
128
\item {\tt -}{\tt -with-fc=compiler} --- Use this option to specify a
129
Fortran-77 compiler. One should use compilers that generate reentrant code,
130
if possible. The default search order for compilers is:
131
{\tt g77}, {\tt f77}, {\tt fc}, {\tt f2c}. (NB: On AIX systems, the
132
search order is {\tt xlf\_r}, {\tt g77}, {\tt f77}, {\tt
134
\item {\tt -}{\tt -with-ld=linker} --- Use this option to specify
135
a linker program. The default is {\tt ld}.
136
\item {\tt -}{\tt -with-ranlib=ranlib} --- Use this option to specify
137
a ranlib program. The default behavior is to detect an appropriate
138
choice automatically.
139
\item {\tt -}{\tt -with-ar=archiver} --- Use this option to specify an
140
archiver. The default is to look for {\tt ar} automatically.
141
\item {\tt -}{\tt -with-ar-flags=options} --- Use this option to specify
142
archiver command-line flags. The default is {\tt r}.
143
\item {\tt -}{\tt -with-perl=perl} --- Use this option to specify a
144
Perl interpreter. The default is to look for {\tt perl} automatically.
145
\item {\tt -}{\tt -with-incdirs=directories} --- Use this option to specify extra
146
directories where to look for header files. Directories should be specified
147
prepended by {\tt -I}, i.e. {\tt -Idir1 -Idir2}, etc. If several directories are specified,
148
enclose the list with single right-quotes, e.g., {\tt
149
-}{\tt -with-incdirs='-I/usr/local/include -I/home/psi3/include'}.
150
\item {\tt -}{\tt -with-libs=libraries} --- Use this option to specify extra
151
libraries which should be used during linking. Libraries should be specified by
152
their full names or in the usual {\tt -l} notation, i.e. {\tt -lm /usr/lib/libm.a}, etc.
153
If several libraries are specified, enclose the list with single right-quotes, e.g., {\tt
154
-}{\tt -with-libs='-lcompat /usr/local/lib/libm.a'}.
155
\item {\tt -}{\tt -with-libdirs=directories} --- Use this option to specify extra
156
directories where to look for libraries. Directories should be specified
157
prepended by {\tt -L}, i.e. {\tt -Ldir1 -Ldir2}, etc. If several directories are specified,
158
enclose the list with single right-quotes, e.g., {\tt
159
-}{\tt -with-libdirs='-L/usr/local/lib -I/home/psi3/lib'}.
160
\item {\tt -}{\tt -with-blas=library} --- Use this option to specify a BLAS
161
library. If your BLAS library has multiple components, enclose the
162
file list with single right-quotes, e.g., {\tt
163
-}{\tt -with-blas='-lf77blas -latlas'}.
164
\item {\tt -}{\tt -with-lapack=library} --- Use this option to specify a
165
LAPACK library. If your LAPACK library has multiple components,
166
enclose the file list with single right-quotes, e.g., {\tt
167
-}{\tt -with-lapack='-llapack -lcblas -latlas'}.
168
\item {\tt -}{\tt -with-max-am-eri=integer} --- Specifies the maximum
169
angular momentum level for the primitive Gaussian basis functions
170
when computing electron repulsion integrals. This is set to
171
$g$-type functions (AM=4) by default.
172
\item {\tt -}{\tt -with-max-am-deriv1=integer} --- Specifies the maximum
173
angular momentum level for first derivatives of the primitive
174
Gaussian basis functions. This is set to $f$-type functions (AM=3)
176
\item {\tt -}{\tt -with-max-am-deriv2=integer} --- Specifies the maximum
177
angular momentum level for second derivatives of the primitive
178
Gaussian basis functions. This is set to $d$-type functions (AM=2)
180
\item {\tt -}{\tt -with-max-am-r12=integer} --- Specifies the maximum
181
angular momentum level for primitive Gaussian basis functions used
182
in $r_{12}$ explicitly correlated methods. This is set to $f$-type
183
functions (AM=3) by default.
184
\item {\tt -}{\tt -with-debug=option} --- This option turns on debugging
185
options. If the argument is omitted, ``{\tt -g}'' will be used by default.
186
\item {\tt -}{\tt -with-opt=options} --- This option may be used to select
187
special optimization flags, overriding defaults.
190
\section{Detailed Installation Instructions}
192
This section provides detailed instructions for compiling and
193
installing the \PSIthree\ package.
195
\subsection{Step 1: Configuration}
197
First, we recommend that you choose for the top-level {\tt \$PSI3} source
198
directory something other than {\tt /usr/local/psi}; your {\tt \$HOME}
199
directory or {\tt /usr/local/src/psi3} are convenient choices. Next,
200
in the top-level {\tt \$PSI3} source directory you've chosen, first run
201
{\tt autoconf} to generate the configure script from {\tt configure.in}.
202
It is best to keep the source code separate from the compilation area,
203
so you must choose a subdirectory for compilation of the codes. A simple
204
option is {\tt \$PSI3/objdir}, which should work for most environments.
205
However, if you need executables for several architectures, choose more
206
meaningful subdirectory names.
208
$\bullet$ The compilation directory will be referred to as {\tt \$objdir}
209
for the remainder of these instructions.
211
In {\tt \$objdir}, run the configure script found in the {\tt \$PSI3}
212
top-level source directory. This script will scan your system to locate
213
certain libraries, header files, etc. needed for complete compilation.
214
The script accepts a number of options, all of which are listed above.
215
The most important of these is the {\tt --prefix} option, which selects the
216
installation directory for the executables, the libraries, header files,
217
basis set data, and other administrative files. The default {\tt -}{\tt -prefix}
218
is {\tt /usr/local/psi}.
220
$\bullet$ The configure script's {\tt -}{\tt -prefix} directory will be referred
221
to as {\tt \$prefix} for the remainder of these instructions.
223
\subsection{Step 2: Compilation}
225
Running {\tt make} (which must be GNU's {\tt 'make'} utility) in {\tt
226
\$objdir} will compile the \PSIthree\ libraries and executable
229
\subsection{Step 3: Testing}
231
To automatically execute the ever-growing number of test cases after
232
compilation, simply execute "make tests" in the {\tt \$objdir} directory.
233
This will run each (relatively small) test case and report the results.
234
Failure of any of the test cases should be reported to the developers at
235
psi3@psicode.org. By default, any such failure will stop the testing process.
236
If you desire to run the entire testing suit without interruption, execute
237
"make tests TESTFLAGS='-u -q'". Note that you must do a "make testsclean" in
238
{\tt \$objdir} to run the test suite again.
240
Testing \PSIthree\ from the source directory, which was possible in
241
prerelease version of \PSIthree\ ({\tt rc1} and {\tt rc2}), is no longer
244
\subsection{Step 4: Installation}
246
Once testing is complete, installation into \$prefix is accomplished by
247
running {\tt make install} in {\tt \$objdir}. Executable modules are
248
installed in {\tt \$prefix/bin}, libraries in {\tt \$prefix/lib} and basis
249
set data and other control strctures {\tt \$prefix/share}.
251
\subsection{Step 5: Documentation}
253
If your system has the appropriate utilities, you may build the package
254
documentation from the top-level {\tt \$objdir} by running {\tt make doc}.
255
The resulting files will appear in the {\tt \$prefix/doc} area.
257
\subsection{Step 6: Cleaning}
259
All compilation-area object files and libraries can be removed to save
260
disk space by running {\tt make clean} in {\tt \$objdir}.
262
\subsection{Step 7: User Configuration}
264
After the \PSIthree\ package has been successfullly installed, the user will
265
need to add the installation directory into their path. If the package
266
has been installed in the default location {\tt /usr/local/psi3}, then
267
in C shell, the user should add something like the following to
268
their {\tt .cshrc} file:
270
setenv PSI /usr/local/psi3
271
set path = ($path $PSI/bin)
272
setenv MANPATH $PSI/doc/man:$MANPATH
274
The final line will enable the use of the \PSIthree\ man pages.
279
\section{Miscellaneous architecture-specific notes}
282
\item Linux on x86 and x86\_64:
284
\item {\tt gcc} compiler: versions 3.2, 3.3, and 3.4 have been tested.
285
\item Intel compilers: version 9.0 has been tested. We do not recommend
287
\item Portland Group compilers: version 6.0-5 has been tested.
290
\item Linux on Intel Itanium:
292
\item Intel compilers version 9.0 have been tested and work. Version 8.1
296
\item AIX 4.3/5.$x$ in 64-bit environment:
297
if IBM VisualAge C++ and IBM XL Fortran are used,
298
one has to manually specify
299
the {\tt -q64} compiler flag
300
that enables production of 64-bit executables.
301
The following configure options have been tested on an AIX5.2
302
system with IBM VisualAge C++ 6.0 compiler and IBM XL Fortran 8.1 compiler:
303
{\tt -}{\tt -with-cc='xlc\_r -q64' -}{\tt -with-cxx='xlC\_r -q64'
304
-}{\tt -with-fc='xlf\_r -q64' -}{\tt -with-blas=-lessl
305
-}{\tt -with-lapack=<your NETLIB LAPACK library>}. Note that
306
the reentrant versions of the compilers
309
\item Compaq Alpha/OSF 5.1: default shell ({\tt /bin/sh})
310
is not POSIX-compliant which causes some \PSIthree\ makefiles
311
to fail. Set environmental variable {\tt BIN\_SH} to {\tt xpg4}.
316
\item The compilation requires a developer's toolkit from {\tt apple.com}.
318
\item You need the {\tt libcompat} library. It can be obtained from Apple's
319
website at {\tt http://www.opensource.apple.com/}. Then add {\tt -lcompat} to the
320
{\tt configure} flag {\tt --with-libs}.
322
\item If you are using compilers from the developer's kit then for
323
BLAS and LAPACK, use the configure options:
325
--with-blas='-altivec -framework vecLib'
327
If you compiled compilers yourself from GNU source code then
328
Apple-specific extensions will not work and you will have to specify
329
the location of {\tt vecLib} manually:
331
--with-blas='/System/Library/Frameworks/vecLib.framework/vecLib'
334
\item The Fortran compiler in GCC version 3.3 and higher requires the latest
335
assembler, as. It can be obtained as a part of {\tt cctools} from
336
{\tt http://www.opensource.apple.com/}. Mac OS X 10.3 (Panther) should come
337
with cctools recent enough to compile \PSIthree.
339
\item Certain \PSIthree\ codes require significant stackspace for compilation.
340
Increase your shell's stacksize limit before running '{\tt make}'. For csh,
341
for example, this is done using '{\tt unlimit stacksize}'.
344
\item SGI IRIX 6.$x$:
346
\item MIPSpro C++ compilers prior to version 7.4 require a command-line flag
347
'{\tt -LANG:std}' in order to compile \PSIthree\ properly.
349
\item Use command-line flag '{\tt -64}' in order to produce 64-bit \PSIthree\ executables with
350
MIPSpro compilers. The following is an example of appropriate configure options:
352
--with-cc='cc -64' --with-cxx='CC -64 -LANG:std' --with-fc='f77 -64'
355
\item Under IRIX configure will attempt to detect automatically and use
356
the optimized SGI Scientific Computing Software Library (SCSL).
added
removed
doc/installation/installation.tex
