This page provides guidance and instructions for building an executable from the shipped code package. Often this will be as simple as unpacking the code, and then "make" or "make platform", but should rarely be much more complicated than that. Mostly, you will be visiting this page in the uncommon event that something broke, and are looking for details and instructions on how to fix the make.
The code is very compact, is written entirely in f77, and is fully self-contained except for the need to invoke LAPACK/BLAS math libraries. Hence, the code has a relatively simple build procedure. Usually, one of the named options within the provided makefile will build a working executable, by typing "make platform" and, at worst, you may need to modify the makefile to specify the appropriate compiler, some common compiler flags, and/or the location of the math libraries. It is easier than it sounds, and the provided makefile gives lots of guidance. And this web page is intended to help you through the process.
You should set up a new empty directory for the code, and place the shipped package in that directory and unpack.
The libraries of atom files that the code needs to operate come in a
separate package, and you should place them in their own directories,
segregated by functional.
Return to Top
|READ.ME||The name says it all - brief instructions to make the code|
|makefile||The default makefile for the code|
|lcaomain.f||The main program for the code|
|lcao.params||Dimension parameters for the code|
|lcaosubs.f||All the functional subroutines|
|utl_*.f|| The configuration files for the code. All the machine/system
dependent code are in these routines, and the code can usually
be reconfigured for the idiosyncracies of almost any environment by
modifying the routines here: timing diagnostics, file systems,
I/O management, parallel handling, etc. Currently only two versions:
utl_gen.f - general usage
utl_mpi.f - MPI version
Yup - machine/system dependence in the code is absolutely minimal.
|lapack.f, blas.f||Explicit source for the LAPACK/BLAS routines (obtained from netlib) required by the code, in the event that LAPACK/BLAS libraries are not available on a target platform.|
|lapackx.f||Expert drivers for eigensolver routines, that are frequently not part of vendor LAPACK libraries, and hence are explicitly compiled and linked into the code.|
|linpack.f||Some isolated LINPACK routines that the code uses (these will eventually be either purged or replaced).|
The code makes liberal use of LAPACK and BLAS, to invoke specific functionality, e.g. eigensolvers, and to enhance performance of the code. The name and location of the math libraries will vary from system to system. On many SGI's, the math libraries are invoked by linking in -lcomplib. On some Alpha-based machines, the libraries can be invoked with -ldxml, but on more recent Compaq-vintage Alphas this has become -lcxml. IBM and Intel machines have yet different conventions. If you have a platform that did not come equipped with a vendor-supplied math library, ATLAS-generated libraries will work well, but you will need to specify their location to link them.
Alternately, you can compile and link the math routines downloaded from NETLIB in the files (lapack.f, blas.f) sent with the package. Be aware that using these compiled (not-optimized) routines can significantly slow performance in key parts of the code. In particular, the BLAS/3 implementation of the grid integrals can be THREE times slower or worse. When linked to compiled math source rather optimized libraries, the input files should add an instruction to bypass the BLAS/3 routines (see the command options) and use the explicitly coded paths in the code.
The code requires Version 3.0 of LAPACK. Earlier versions WILL fail.
Return to Top
The parameters in "lcao.params" define the limits on the code. This file is used in only one place: it is inserted via an "include" into the main program "lcaomain.f". The virtue of this single use is that a redimensioned executable can be built by simply recompiling the main program (quick) and not the entire code (slower). The bulk of the code is in the subroutines file "lcaosubs.f", and those subroutines are completely insensitive to dimensions.
There are two kinds of parameters in the "lcao.params" file: those that determine specific problem aspects, and those that fix available memory.
Most of the parameters place limits on discrete problem aspects: number of atams, number of basis functions, k-points, symmetries, etc. It is clear what they refer to, and they can usually be modified rather freely as they do not allocate large amounts of memory. If your calculation requests a larger problem in some respect than what the code is dimensioned for, the input routines will stop and point out what parameter needs to be modified. Modify that parameter in "lcao.params" and recompile.
The parameter "maxwkd" specifies the size of the principal workspace
used in the code, and determines the amount of memory the code can use.
At initialization, the code creates one huge real*8 workspace
dimensioned to "maxwkd", and then dynamically allocates memory it
needs from this workspace. Before entering any computationally
expensive routines, the code does an exact forecast of the memory
needed to complete, and will stop if it sees it has insufficient to
complete and will output the minimum necessary memory to finish.
Modify "maxwkd" in "lcao.params" accordingly and recompile.
The biggest workspace you can have --the maximum you can set "maxwkd"--
is limited by the physical memory of your platform. On a 256MB machine,
the largest you can set "maxwkd" is about 30M, on 512MB about 60M,
and on 1GB about 110M. The exact limit will vary depending on the
system, and how much space the OS reserves for other purposes.
Return to Top