INSTALL

2019-05-29
Susi Lehtola


** Prerequisites **

To compile ERKALE you need

* CMake ( http://cmake.org ), at least version 3.24
* A C++17 compiler and a Fortran compiler (for LAPACK linkage)
* A LAPACK/BLAS library (OpenBLAS, FlexiBLAS, Intel MKL, ... )
* The GNU Scientific Library ( http://www.gnu.org/s/gsl/ )

These are found on the system with find_package and must be installed
from your distribution. The remaining dependencies

* libxc     ( https://libxc.gitlab.io/ )
* libcint   ( https://github.com/sunqm/libcint , or the API-compatible qcint )
* HDF5      ( http://www.hdfgroup.org/HDF5/ )
* Armadillo ( http://arma.sourceforge.net/ )
* libwignernj ( https://github.com/susilehtola/libwignernj )
* nlohmann/json ( https://github.com/nlohmann/json )

are used if installed, and otherwise fetched and built from source
automatically by CMake at configure time (so a network connection is
needed only when a dependency is missing).

** Compiling **

Out of source, from the top of the source tree:

    $ cmake -B build
    $ cmake --build build -j

By default this builds the OpenMP-parallel version; the executables get
an "_omp" suffix. For a serial build, pass -DUSE_OPENMP=OFF (e.g. into a
separate build directory):

    $ cmake -B build-serial -DUSE_OPENMP=OFF
    $ cmake --build build-serial -j

To install, add -DCMAKE_INSTALL_PREFIX=<prefix> and run
"cmake --install build". The tests are run with "ctest" from the build
directory.

Useful options:
* -DERKALE_SYSTEM_LIBRARY=<path>  system-wide basis-set repository
* -DERKALE_BLAS_INT64=ON|OFF|AUTO 64-bit (ILP64) BLAS integers (AUTO probes)
* -DBUILD_SHARED_LIBS=ON          build shared liberkale

If you wish to create the developer documentation, you need a working
installation of doxygen and LaTeX. The documentation can be created by
running
 $ doxygen

** Usage **

ERKALE is used in the following manner
    $ erkale input

Here "input" is a file, that contains at least the directive "Method",
which can be either "HF" for a Hartree-Fock calculation or a
specification of a DFT exchange-correlation functional. For example
 Method gga_x_pbe-gga_c_pbe
will run a calculation with PBE exchange and PBE correlation, and
 Method hyb_gga_xc_b3lyp
will run a B3LYP calculation.

Please consult the list of supported functionals for more choices.

Upon startup, ERKALE will print out the current settings, along with
valid keywords.

** Example **

Here is an example input file:
 Method HF
 Basis aug-cc-pVTZ
 System ethanol.xyz
 SaveChk ethanol-hf.chk
 LoadChk ethanol-lda.chk
 Cholesky false
 Direct true

The first line specifies that a Hartree-Fock calculation is requested.

The second line specifies that the aug-cc-pVTZ basis is to be used in
the calculation. ERKALE searches for the basis set in the following order:
 1. A basis set library location specified by the environmental
 variable ERKALE_LIBRARY.
 2. In the current directory.
 3. In the system wide basis set library repository, which is by
 default /usr/share/erkale/basis. The value can be changed via a
 compile-time option (add to cmake flags), e.g.,
 -DERKALE_SYSTEM_LIBRARY=/usr/local/share/erkale/basis.
The .gbs extension is automatically added, if necessary.

The third line states that the atoms in the system are to be read
from the file "ethanol.xyz". The file must be in xyz format, for
example:
     3
     B3LYP aug-cc-pVTZ optimized water molecule
     O      0.000000    0.117030    0.000000
     H      0.763404   -0.468123    0.000000
     H     -0.763404   -0.468115    0.000000

The fourth line states that the results of the calculation should be
saved to the file erkale-hf.chk.

The fifth line asks that the calculation be initialized with the
wavefunction from the file erkale-lda.chk. The idea behind this is to
speed up the calculation: by default a core guess is used, which
completely ignores electron-electron repulsion. By initializing the
calculation with a more sane starting guess (density-fitted
density-functional theory calculation), the necessary number of
(costly) Hartree-Fock iterations can be brought down.

The sixth line turns off the use of the Cholesky decomposition for
two-electron integrals, which is used by default.

The seventh line states that two-electron (and density-fitting)
integrals should be computed on the fly. By default, the integrals are
tabled in memory.

** Contact information **

Dr Susi Lehtola
Department of Chemistry
University of Helsinki
P. O. Box 55
FI-00014 UNIVERSITY OF HELSINKI
FINLAND

susi (dot) lehtola (at) alumni (dot) helsinki (dot) fi