Join GitHub today
libint compiler vs library
Before you read on:
- If you want to know how to use a libint library in your code:
- If you want to know how to generate a libint library using the libint compiler , first make sure you really need to do that:
- if all you want is a basic library that computes integrals necessary to compute energies, use the pre-generated library labeled "lmax=6 library (standard ints only)" from the latest release of Libint;
- 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;
- if you do need to make a custom library, read on.
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.
- Robust C++ compiler with "some" C++11 support;
- Recent boost library;
- Recent GMP library, including C++ support;
- (optional) Recent MPFR library for high-precision (>64bit) testing of the computed integrals;
- Standard GNU toolchain (make, tar, autoconf);
- doxygen and latex to make compiler documentation.
- 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
- enter the top source directory
- make a separate directory where you will build the compiler (WARNING: BUILD DIRECTORY CANNOT BE LOCATED WITHIN THE SOURCE TREE), and cd that directory
- 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:
- 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'.
- CXX can be used to specify the C++ compiler.
- 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:
- standard (default) -- the standard ordering (xxx, xxy, xxz, xyy, xyz, xzz, yyy, ...); this is ordering of the Common Component Architecture (CCA) standard for molecular integral data exchange described in “Components for Integral Evaluation in Quantum Chemistry”, J. P. Kenny, C. L. Janssen, E. F. Valeev, and T. L. Windus, J. Comp. Chem. 29, 562 (2008);
- intv3 -- the intv3 ordering (yyy, yyz, yzz, zzz, xyy, xyz, xzz, xxy, xxz, xxx) used the by IntV3, the default integral engine of MPQC; use this to make Libint and IntV3 engines in MPQC interoperable;
- gamess -- GAMESS ordering (xxx, yyy, zzz, xxy, xxz, yyx, yyz, zzx, zzy, xyz)
- orca -- ORCA ordering (hydrid between GAMESS and standard);
- bagel -- BAGEL ordering;
--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.):
compiling libint library
- C++ compiler. Although the generated library can be compiled with a pre-C++11 compiler, however this will not permit the use of C++11 API. Since most modern compilers support C++11, it is recommended to enable C++11 support by adding -std=c++11 to CXXFLAGS.
- GNU Make.
- (optional) Eigen library is necessary to compile additional validation tests. For thorough validation Libint uses two implementations of integral-direct Hartree-Fock (source located under tests/hartree-fock):
- hartree-fock.cc is a minimal implementation primarily used for teaching purposes
- hartree-fock++.cc is a complete shared-memory parallel implementation of Hartree-Fock up to forces (complete) and Hessians (minus the orbital response).
Compilation of the generated library is straightforward:
- Unpack the library: tar -xvzf libint-2.x.y-stable.tgz
- cd libint-2.x.y-stable
- ./configure --prefix=.... CXX=... CXXFLAGS=....
- optional: make check
- make install
To obtain peak performance 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
--prefix option and
CXXFLAGS environment variables, 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. N.B. C++11 interface cannot be currently used with SIMD vectorized libraries! 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.
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
- if you use C++11 or later (strongly recommended): read this.
- 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.
- Apple clang++ and MacPorts g++ (4.8) both work with -std=c++11 flag
- MacPorts gmp package works fine
- standard configuration: '--enable-generic-code' '--with-max-am=6' '--with-opt-am=3' '--enable-eri3=0' '--enable-eri2=0' '--enable-eri3-pure-sh' '--enable-eri2-pure-sh' '--enable-fma' '--disable-1body-property-derivs'
- 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'
- 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'
- 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'
- 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)