51
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.
53
\item C, C++, and FORTRAN77 compilers. The FORTRAN77 compiler is only
54
used to determine the symbol-naming convention of and some system
55
routines for the BLAS and LAPACK libraries on some architectures. It
56
is optional in a few cases (e.g. Mac OS X systems).
55
57
\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}
58
for vital matrix-matrix and matrix-vector multiplication
59
routines. (See recommendations below.)
60
\item The linear algebra package (LAPACK). \PSIthree\ makes use of
61
LAPACK's eigenvalue/eigenvector and matrix inversion routines. (See
62
recommendations below)
64
63
\item POSIX threads (Pthreads) library
65
64
\item Perl interpreter (version 5.005 or higher)
66
65
\item Various GNU utilies: \htmladdnormallink{{\tt
96
95
\item {\tt cd \$PSI3} (your top-level \PSIthree\ source directory)
98
96
\item {\tt mkdir objdir}
99
97
\item {\tt cd objdir}
100
\item {\tt ../configure}
98
\item {\tt ../configure} (may need some of the options below, esp.~if
99
{\tt blas} or {\tt lapack} are in non-standard locations)
102
101
\item {\tt make tests} (optional, but recommended)
103
102
\item {\tt make install}
104
103
\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
107
You may need to make use of one or more of the following options to
113
108
the {\tt configure} script:
115
110
\item {\tt -}{\tt -prefix=directory} --- Use this option if you wish to
116
111
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++}.)
112
directory, {\tt /usr/local/psi}. This directory will contain
113
subdirectories with the final installed binaries, libraries,
114
documentation, and shared data files.
115
\item {\tt -}{\tt -with-cc=compiler} --- Use this option to specify a
116
C compiler. One should use compilers that generate reentrant code,
117
if possible. The default search order for compilers is: {\tt cc\_r} (AIX
118
only), {\tt gcc}, {\tt icc}, {\tt cc}.
119
\item {\tt -}{\tt -with-cxx=compiler} --- Use this option to specify a
120
C++ compiler. One should use compilers that generate reentrant
121
code, if possible. The default search order for compilers is: {\tt xlC\_r}
122
(AIX only), {\tt g++}, {\tt c++}, {\tt icpc}, {\tt cxx}.
128
123
\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
124
Fortran-77 compiler, which is used to determine linking coventions
125
for BLAS and LAPACK libraries and to provide system routines for
126
those libraries. Note that no fortran compiler is necessary on Mac
127
OS X systems (see below). The default search order for compilers
128
is: {\tt xlf\_r} (AIX only), {\tt gfortran}, {\tt g77}, {\tt ifort},
129
{\tt f77}, {\tt f2c}.
130
\item {\tt -}{\tt -with-f77-symbol=value} --- This option allows manual
131
assignment of the F77 symbol convention, which is necessary for C
132
programs to link Fortran-interface libraries such as BLAS and
133
LAPACK. This option should only be used by experts and even then
134
should almost never be necessary. Allowed values are:
137
\item[lcu]lower-case with underscore (default)
139
\item[ucu] upper-case with underscore
134
141
\item {\tt -}{\tt -with-ld=linker} --- Use this option to specify
135
142
a linker program. The default is {\tt ld}.
136
143
\item {\tt -}{\tt -with-ranlib=ranlib} --- Use this option to specify
140
147
archiver. The default is to look for {\tt ar} automatically.
141
148
\item {\tt -}{\tt -with-ar-flags=options} --- Use this option to specify
142
149
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'}.
150
\item {\tt -}{\tt -with-incdirs=directories} --- Use this option to
151
specify extra directories where to look for header
152
files. Directories should be specified prepended by {\tt -I},
153
i.e. {\tt -Idir1 -Idir2}, etc. If several directories are specified,
154
enclose the list with single right-quotes, e.g., {\tt -}{\tt
155
-with-incdirs='-I/usr/local/include -I/home/psi3/include'}.
156
\item {\tt -}{\tt -with-libs=libraries} --- Use this option to specify
157
extra libraries which should be used during linking. Libraries
158
should be specified by their full names or in the usual {\tt -l}
159
notation, i.e. {\tt -lm /usr/lib/libm.a}, etc. If several libraries
160
are specified, enclose the list with single right-quotes, e.g., {\tt
161
-}{\tt -with-libs='-lcompat /usr/local/lib/libm.a'}.
162
\item {\tt -}{\tt -with-libdirs=directories} --- Use this option to
163
specify extra directories where to look for libraries. Directories
164
should be specified prepended by {\tt -L}, i.e. {\tt -Ldir1 -Ldir2},
165
etc. If several directories are specified, enclose the list with
166
single right-quotes, e.g., {\tt -}{\tt
167
-with-libdirs='-L/usr/local/lib -I/home/psi3/lib'}.
168
\item {\tt -}{\tt -with-blas=library} --- Use this option to specify a
169
BLAS library. If your BLAS library has multiple components, enclose
170
the file list with single right-quotes, e.g., {\tt -}{\tt
171
-with-blas='-lf77blas -latlas'}. Note that many BLAS libraries
172
can be detected automatically.
173
\item {\tt -}{\tt -with-lapack=library} --- Use this option to specify
174
a LAPACK library. If your LAPACK library has multiple components,
175
enclose the file list with single right-quotes, e.g., {\tt -}{\tt
176
-with-lapack='-llapack -lcblas -latlas'}. note that many LAPACK
177
libraries can be detected automatically.
168
178
\item {\tt -}{\tt -with-max-am-eri=integer} --- Specifies the maximum
169
179
angular momentum level for the primitive Gaussian basis functions
170
180
when computing electron repulsion integrals. This is set to
195
206
\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
First, we recommend that you choose for the top-level {\tt \$PSI3}
209
source directory something other than {\tt /usr/local/psi}; your {\tt
210
\$HOME} directory or {\tt /usr/local/src/psi3} are convenient
211
choices. Next, in the top-level {\tt \$PSI3} source directory you've
212
chosen, first run {\tt autoconf} to generate the configure script from
213
{\tt configure.ac}. It is best to keep the source code separate from
214
the compilation area, so you must choose a subdirectory for
215
compilation of the codes. A simple option is {\tt \$PSI3/objdir},
216
which should work for most environments. However, if you need
217
executables for several architectures, choose more meaningful
208
220
$\bullet$ The compilation directory will be referred to as {\tt \$objdir}
209
221
for the remainder of these instructions.
229
241
\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
243
To execute automatically the ever-growing number of test cases after
244
compilation, simply execute "make tests" in the {\tt \$objdir}
245
directory. This will run each (relatively small) test case and report
246
the results. Failure of any of the test cases should be reported to
247
the developers at \PSIemail. By default, any such failure will stop
248
the testing process. If you desire to run the entire testing suit
249
without interruption, execute "make tests TESTFLAGS='-u -q'". Note
250
that you must do a "make testsclean" in {\tt \$objdir} to run the test
244
253
\subsection{Step 4: Installation}
287
\section{Recommendations for BLAS and LAPACK Libraries}
289
Much of the speed and efficiency of the PSI3 programs depends on the
290
corresponding speed and efficiency of the available BLAS and LAPACK
291
libraries (especially the former). In addition, the most common
292
compilation problems involve these libraries. Users may therefore
293
wish to consider the following BLAS and LAPACK recommendations when
297
\item It is NOT wise to use the stock BLAS library provided with many
298
Linux distributions like RedHat. This library is usually just the
299
netlib ({http://netlib.org/}distribution and is completely
300
unoptimized. PSI3's performance will suffer if you choose this
301
route. The choice of LAPACK is less critical, and so the
302
unoptimized netlib distribution is acceptable. If you do choose to
303
use the RedHat/Fedora stock BLAS and LAPACK, be aware that some
304
RPM's do not make the correct symbolic links. For example, you may
305
have {\tt /usr/lib/libblas.so.3.1.0} but not {\tt
306
/usr/lib/libblas.so}. If this happens, create the link as, e.g.,
307
{\tt ln -s /usr/lib/libblas.so.3.1.0 /usr/lib/libblas.so}. You may
308
need to do similarly for lapack.
310
\item Perhaps the best choices for BLAS are Kazushige Goto's
311
hand-optimized BLAS ({\tt
312
http://www.tacc.utexas.edu/resources/software/}) and ATLAS ({\tt
313
http://math-atlas.sourceforge.net/}). These work well on nearly
314
every achitecture to which the PSI3 developers have access. On Mac
315
OS X systems, however, the {\tt vecLib} package that comes with
318
\item PSI3 does not require a Fortran compiler, unless the resident
319
BLAS and LAPACK libraries require Fortran-based system libraries.
320
If you see compiler complaints about missing symbols like "{\tt
321
do\_fio}" or "{\tt e\_wsfe}", then your libraries were most likely
322
compiled with g77 or gfortran, which require {\tt -lg2c} to resolve
323
the Fortran I/O calls. Use of the same gcc package for PSI3 should
324
normally resolve this problem.
326
\item The PSI3 configure script can conveniently identify and use
327
several different BLAS and LAPACK libraries, but its ability to do
328
this automatically depends on a number of factors, including
329
correspondence between the compiler used for PSI3 and the compiler
330
used to build BLAS/LAPACK, and placement of the libraries in
331
commonly searched directories, among others. PSI3's configure
332
script will find your BLAS and LAPACK if any of the the following
333
are installed in standard locations (e.g. {\tt /usr/local/lib}):
336
\item ATLAS: {\tt libf77blas.a} and {\tt libatlas.a}, plus netlib's
338
\item MKL: {\tt libmkl.so} and {\tt libmkl\_lapack64.a} (with the Intel compilers)
339
\item Goto: {\tt libgoto.a} and netlib's {\tt liblapack.a}
340
\item Cray SCSL (e.g. on SGI Altix): {\tt libscs.so} (NB: No Fortran compiler
341
is necessary in this case, so {\tt -}{\tt -with-fc=no} should work.)
342
\item ESSL (e.g. on AIX systems): {\tt libessl.a}
344
\item If configure cannot identify your BLAS and LAPACK libraries
345
automatically, you can specify them on the command-line using the
346
{\tt -}{\tt -with-blas} and {\tt -}{\tt -with-lapack} arguments
347
described above. Here are a few examples that work on the PSI3
350
(a) Linux with ATLAS:
352
{\tt -}{\tt -with-blas='-lf77blas -latlas'} {\tt -}{\tt -with-lapack='-llapack -lcblas'}
354
(b) Mac OS X with vecLib:
356
{\tt -}{\tt -with-blas='-altivec -framework vecLib'} {\tt -}{\tt -with-lapack=' '}
358
(c) Linux with MKL and {\tt icc/icpc/ifort}:
360
{\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}
279
363
\section{Miscellaneous architecture-specific notes}
282
366
\item Linux on x86 and x86\_64:
284
\item {\tt gcc} compiler: versions 3.2, 3.3, and 3.4 have been tested.
368
\item {\tt gcc} compiler: versions 3.2, 3.3, 3.4, 4.0, and 4.1 have been tested.
285
369
\item Intel compilers: version 9.0 has been tested. We do not recommend
286
370
using version 8.1.
287
371
\item Portland Group compilers: version 6.0-5 has been tested.
372
\item Some versions of RedHat/Fedora Core RPM packages for the
373
BLAS and LAPACK libraries fail to make all the required symlinks.
374
For example, you may have {\tt /usr/lib/libblas.so.3.1.0} but not
375
{\tt /usr/lib/libblas.so}. If this happens, create the link as, e.g.,
376
{\tt ln -s /usr/lib/libblas.so.3.1.0 /usr/lib/libblas.so}. You
377
may need to do similarly for lapack.
290
\item Linux on Intel Itanium:
380
\item Linux on Itanium2 (IA64):
292
382
\item Intel compilers version 9.0 have been tested and work. Version 8.1
384
\item {\tt gcc} compilers work.
390
\item The compilation requires a developer's toolkit (Xcode) from
391
{\tt apple.com}. Note that a fortran compiler is not needed for
392
PSI 3.3 on Mac OS X systems.
394
\item The {\tt libcompat.a} library is also needed, but it is not
395
provided in the Xcode toolkit. If you see compiler complaints
396
about missing symbols like {\tt re\_comp} or{\tt re\_exec} then your
397
{\tt -lcompat} is missing or PSI3 is not aware of it. As of 6
398
April 2007, it can be obtained from Apple's website at:
400
{\tt http://www.opensource.apple.com/darwinsource/tarballs/apsl/Libcompat-14.1.tar.gz}
402
You must sign up for a free developer's account to access the above
403
library. You can identify the library to configure by adding {\tt
404
-}{\tt -with-libs=-lcompat} to the command line.
406
\item For apple systems, the latest configure script assumes that the
407
{\tt vecLib} will be used for the optimized BLAS and LAPACK
408
libraries, unless the user indicates otherwise using the {\tt -}{\tt
409
-with-blas} and {\tt -}{\tt -with-lapack} flags to configure. If
410
you encounter difficulty with configure, you may have success
411
explicitly indicating the vecLib using:
413
{\tt -}{\tt -with-blas='-altivec -framework vecLib'} {\tt -}{\tt
416
\item Pre Mac OS 10.4: Certain PSI3 codes require significant
417
stackspace for compilation. Increase your shell's stacksize
418
limit before running {\tt make}. For csh, for example, this is
419
done using "unlimit stacksize". [NB: This limit appears to have
420
been lifted starting with Mac OS 10.3.X (Panther).]
296
424
\item AIX 4.3/5.$x$ in 64-bit environment:
297
425
if IBM VisualAge C++ and IBM XL Fortran are used,
298
one has to manually specify
426
one has to specify manually
299
427
the {\tt -q64} compiler flag
300
428
that enables production of 64-bit executables.
301
429
The following configure options have been tested on an AIX5.2
306
434
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
437
\item SGI IRIX 6.$x$:
346
439
\item MIPSpro C++ compilers prior to version 7.4 require a command-line flag
added
removed
doc/installation/installation.tex
