Skip to content

Home

Jump to bottom
Eduard Valeyev edited this page Mar 7, 2017 · 31 revisions

=============================================================================

libint compiler vs library

Before you read on:

  1. If you want to know how to generate a libint library using the libint compiler read on (note that many codes using libint, e.g. orca and mpqc, already include an appropriately configured libint library and you do not need to generate it yourself)
  2. If you want to know how to use a libint library in your code:
  3. if you use C++11 or later (strongly recommended): read this instead.
  4. if you use pre-2011 C++, C, Fortran, or any other language, refer to the Libint Programmer's Manual.

=============================================================================

why use the libint compiler

The primary reason to use libint compiler is to generate custom Libint libraries. Most advanced customization, such as implementation of new integral types, recurrence relations, and computation strategies, will require making changes to the compiler. If you are interested in working on the compiler code please consider consulting with one of Libint authors, if possible, to avoid duplication of effort.

=============================================================================

prerequisites

  1. Robust C++ compiler with "some" C++11 support;
  2. Recent boost library;
  3. Recent GMP library, including C++ support;
  4. (optional) Recent MPFR library for high-precision (>64bit) testing of the computed integrals;
  5. Standard GNU toolchain (make, tar, autoconf);
  6. doxygen and latex to make compiler documentation.
  7. Git client.

=============================================================================

getting the source code

The only way to get the compiler source is from the Libint source code repository on GitHub. You can use a client, like GitHub app or (our favorite) SourceTree app from Atlassian. Or from the command line: git clone https://github.com/evaleev/libint.git

=============================================================================

compiling libint compiler

  1. enter the top source directory
  2. ./autogen.sh
  3. make a separate directory where you will build the compiler (WARNING: BUILD DIRECTORY CANNOT BE LOCATED WITHIN THE SOURCE TREE), and cd that directory
  4. run configure script with appropriate configure command-line options (see the next section for more info). All available options can be listed as such: [libint_srcdir]/configure --help. Some information can be passed to configure via standard environmental variables:
    1. CPPFLAGS can be used if the boost library is not in the default compiler search path, e.g. /path/to/libint/source/configure CPPFLAGS='-I/path/to/boost'.
    2. CXX can be used to specify the C++ compiler.
    3. CXXFLAGS can be used to specify the C++ compiler flags.

=============================================================================

configuring libint compiler

These are the most useful configure options:

  • --enable-eri=N Use this option to enable support for N-th order derivatives of (4-center) electron repulsion integrals. To disable support for ERIs set N to 'no', or use the --disable-eri option. By default, N=0 (i.e. no derivatives are requested).
  • --enable-eri3=N Same as --enable-eri, except for 3-center ERIs.
  • --enable-eri2=N Same as --enable-eri, except for 2-center ERIs.
  • --with-max-am=L Species the maximum angular momentum level for the Gaussian basis functions when computing electron repul- sion integrals. By default, integrals over g-type functions (L=4) are supported.
  • --with-cartgauss-ordering=ORDER Specifies the ordering of cartesian Gaussians in shells. The known values are:
  • --with-shell-set=SET The library will support computation of shell sets sets subject to these restrictions:
    • standard -- standard ordering (default). For (ab|cd): l(a) >= l(b), l(c) >= l(d), l(a)+l(b) <= l(c)+l(d). For (b|cd): l(c) >= l(d).
    • orca -- ORCA ordering. For (ab|cd): l(a) <= l(b), l(c) <= l(d), l(a) < l(c) || (l(a) == l(c) && l(b) < l(d)). For (b|cd): l(c) <= l(d).

=============================================================================

generating libint library

this will produce a tarball of libint library that is suitable for independent distribution (it will have its own configure, etc.):

  1. make export

=============================================================================

compiling libint library

Compilation of the generated library is straightforward:

  1. Unpack the library: tar -xvzf libint-2.x.y-stable.tgz
  2. cd libint-2.x.y-stable
  3. ./configure --prefix=.... CXX=... CXXFLAGS=....
  4. make
  5. make install

It is very important to use the C++ compiler and compiler options that are appropriate for the given platform. It is impossible to provide specific recommendations for specific platforms. We recommend to use a vendor compiler (e.g., Intel) before trying clang++ and g++. In some situations, however, clang++ and g++ are known to outperform the x86 vendor compiler, so we recommend trying several compilers.

Other important configure flags are described in the next section.

=============================================================================

libint library configure options

Besides --prefix and CXX and CXXFLAGS, the following configure options may be necessary/useful:

  • --with-real-type=TYPE specifies the floating-point data type used by the library. The default value for this option is double (double-precision floating-point representation of a real number). By overriding the default it is possible to customize the library to use a lower-precision representation (which typically results in a performance boost) and/or to generate SIMD vectorized code. The following values are valid:
    • float -- single-precision floating-point number;
    • libint2::simd::VectorAVXDouble -- vector of 4 packed doubles that can be used with AVX instructions available on reasonably-modern x86 hardware (starting with Intel Sandy Bridge and AMD Bulldozer microarchitectures, available in processors since 2011);
    • libint2::simd::VectorSSEDouble -- vector of 2 packed doubles that can be used with SSE2 instructions available on all x86 platforms, including those released before 2011;
    • libint2::simd::VectorSSEFloat -- vector of 4 packed floats that can be used with SSE instructions available on all x86 platforms, including those released before 2011;
    • libint2::simd::VectorQPXDouble -- vector of 4 packed doubles that can be used with QPX instructions available on recent PowerPC hardware (IBM Blue Gene/Q);
    • libint2::simd::VectorFP2Double -- vector of 2 packed doubles that can be used with FP2 (Double Hummer) instructions available on older PowerPC hardware (IBM Blue Gene/P).

With the exception of float, these are vector types implemented in Libint using compiler intrinsics, functions that translate directly into vector instructions. To use these vector types you may need to provide additional compiler flags that will enable support for vector instructions. For example, to enable support for AVX in Clang use the -mavx compiler flag. With Intel compiler use flag -xHOST to enable all vector instruction sets supported by the processor on which you are compiling.

N.B. It is also possible to use real vector types of Agner Fog's vectorclass library, e.g. Vec4d and Vec8f for AVX. To use this library you need to add this to CPPFLAGS or CXXFLAGS: -Ipath_to_vectorclass -DLIBINT2_HAVE_AGNER_VECTORCLASS . On OS X we only succeeded in using this library with a recent GNU C++ compiler, not with Clang.

on SIMD vectorization

SIMD vectorization is the crucial contributor to performance of a modern processor core. Libint code can typically hit up to 70% of FLOP peak on a scalar core, hence on a SIMD core divide that number by the vector length (4 for AVX in double precision). The situation is only going to get worse (accelerators already use 8- and 16-wide vector units, and future mainstream processors are likely to use 8-wide units also). Hence if your method spends significant portion of its time computing integrals start rewriting your code now.

Vectorization of Libint is work in progress. However, by switching to AVX we see a factor of 2-2.5 speedup of the integrals kernels compared to scalar performance, thus we are optimistic that it will be possible to attain 50% of peak on AVX hardware. It is clear that significant reorganization of the manner in which integrals are computed and digested is involved, but these costs are unavoidable.

=============================================================================

using libint library

  1. if you use C++11 or later (strongly recommended): read this instead.
  2. if you use pre-2011 C++, C, Fortran, or any other language, refer to the Libint Programmer's Manual for (brief) information on how to use the library in your code.

=============================================================================

platform-specific notes

mac

  • Apple clang++ and MacPorts g++ (4.8) both work with -std=c++11 flag
  • MacPorts gmp package works fine

linux

=============================================================================

program-specific notes

mpqc

  • standard configuration: '--enable-eri=0' '--disable-1body' '--with-max-am=7' '--with-opt-am=4' '--enable-unrolling=1296' '--enable-generic-code' '--enable-contracted-ints'
  • configuration prior to Jan. 8, 2015: '--enable-eri=0' '--with-max-am=7' '--with-opt-am=4' '--disable-unrolling' '--enable-generic-code' '--enable-contracted-ints'

gamess

  • standard configuration: '--enable-eri=0' '--with-max-am=7' '--with-opt-am=4' '--disable-unrolling' '--enable-generic-code' '--enable-contracted-ints' '--with-cartgauss-ordering=gamess'

orca

  • a libint library (version 2.0.2) is embedded in ORCA
  • standard configuration: '--enable-eri=2' '--enable-eri3=2' '--enable-eri2=2' '--with-max-am=7' '--with-opt-am=4' '--with-eri-max-am=7,4,3' '--with-eri-opt-am=4,3,2' '--disable-unrolling' '--enable-generic-code' '--enable-contracted-ints' '--with-cartgauss-ordering=orca' '--with-shell-set=orca' '--enable-eri3-pure-sh' '--enable-eri2-pure-sh'

bagel

  • standard configuration: '--with-max-am=4' '--with-eri3-max-am=6' '--with-eri2-max-am=6' '--enable-eri3=1' '-enable-eri=1' '--enable-eri2=1' '--disable-unrolling' '--enable-generic-code' '--enable-contracted-ints' '--with-cartgauss-ordering=bagel'
  • if you want to use spherical Gaussians only add: '--enable-eri3-pure-sh' '--enable-eri2-pure-sh' (some tests may fail)
  • It appears that on a Mac Libint and BAGEL must be either both static or both shared (2/3/2014)

Wiki Home

Using Modern C++ API

Contributor Guide

Clone this wiki locally