LibGtoint

Overview

LibGtoint is an analytical GTO (Gaussian type orbital) integral library for C and Fortran.

Firstly note that this library is not fast and currently it is just an implementation for study. It would be much appreciated if you could share your expertise on more efficient implementation by Issues, Pull Requests, or Wiki.

Its main features are as follows:

Supports Cartesian GTOs and spherical GTOs,
Supports GTOs with any angular momentum quantum numbers (s, p, d, f, ...),
Supports analytical derivatives with any orders, and
Implemented compactly.

It supports the following integrals:

overlap integrals,
kinetic energy integrals,
nuclear attraction integrals,
electron repulsion integrals (i.e. two-electron integrals),
multipole moment integrals, and
scalar ECP (effective core potential) integrals.

Currently, LibGtoint uses only Obara-Saika scheme.

Installation

To install LibGtoint, CMake 3.14 or higher is required to be installed in your system.

For Unix-like OS

If you use Unix or Unix-like OS such as Linux and macOS, you can install LibGtoint by executing the following commands:

mkdir build
cd build
cmake ..
make
make test
sudo make install

To use specific C and Fortran compilers, use the cmake options -DCMAKE_C_COMPILER=C-Compiler and -DCMAKE_Fortran_COMPILER=Fortran-Compiler respectively.

If no need of the Fortran interface, use the cmake option -DFortran=OFF.

By default, a static library is built. If you need a shared object version of this library, use the cmake option -DBUILD_SHARED_LIBS=1.

The default installation directory is /usr/local. If you want to change it, use the cmake option -DCMAKE_INSTALL_PREFIX=Installation-Path.

For Windows

If you use Windows, you have two options shown in the sections below.

Using Visual Studio

To install LibGtoint which is built by using Microsoft's genuine build tools, Build Tools for Visual Studio has to be installed in your system. After you have installed it, you can install LibGtoint by executing the following commands using 'Developer Command Prompt for VS 2019' or 'Developer PowerShell for VS 2019':

mkdir build
cd build
cmake -DFortran=OFF -DCMAKE_INSTALL_PREFIX=%USERPROFILE%\libgtoint ..
cmake --build . --config Release
ctest -C Release
cmake --install . --config Release

By default, a static library is built. If you need a dynamic link library, use the cmake option -DBUILD_SHARED_LIBS=1.

In the above commands, the installation directory is set to that directly under your account directory, ex, C:\Users\Your-User-Name\libgtoint. If you want to change it, modify the cmake option -DCMAKE_INSTALL_PREFIX=Installation-Path.

Known Issues:

As of cmake 3.20.1, cmake fails to generate a build configuration for compiling Fortran sources even if Intel Fortran compiler for Windows exists. So, you cannot help but specify the cmake option -DFortran=OFF.
As of cmake 3.20.1, cmake does not see C compilers other than Microsoft Visual C++ compiler (MSVC) even if Intel C/C++ compiler for Windows exists. So, the cmake option -DCMAKE_C_COMPILER=icl has no effect.

Using MinGW-w64

To install LibGtoint which is built by MinGW tool chain, you can install LibGtoint by executing the following commands:

mkdir build
cd build
cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX=/usr/local ..
make
make test
make install

To use specific C and Fortran compilers, use the cmake options -DCMAKE_C_COMPILER=C-Compiler and -DCMAKE_Fortran_COMPILER=Fortran-Compiler respectively.

If no need of the Fortran interface, use the cmake option -DFortran=OFF.

In the above commands, the installation directory is set to /usr/local. If you want to change it, modify the cmake option -DCMAKE_INSTALL_PREFIX=Installation-Path.

Known Issue:

As of GNU Binutils 2.36.1, a DLL version of LibGtoint causes abnormal termination. So, do not specify the cmake option -DBUILD_SHARED_LIBS=1.

API

Preparation

To use the API in a C program, the header file gtoint.h is needed.

#include <gtoint.h>

To use the API in a Fortran program, the module gtoint is needed.

use gtoint

Basic types

In the API for C, two data types are defined.

The data type gtoint_double3_t has three double type member variables named x, y, and z.
The data type gtoint_int3_t has three int type member variables named x, y, and z.

Error codes

As for C, most of API functions return error codes. As for Fortran, most of API routines pass error codes via the argument err.

The error codes are shown below.

GTOINT_ERROR_OK: successfully done with no error
GTOINT_ERROR_ARGUMENT: invalid argument
GTOINT_ERROR_MEMORY: out of memory
GTOINT_ERROR_UNSUPPORTED: unsupported functionality
GTOINT_ERROR_INTERNAL: internal error

Creation of an integrator

To construct basis functions and ECPs, and to compute several kinds of integrals, an integrator is required. It can be created by using the following function or routine.

gtoint_error_t gtoint_integrator_create(gtoint_integrator_t *itg);

Fortran

subroutine gtoint_integrator_create(itg, err)
   type(C_PTR), intent(out) :: itg
   integer(C_INT), intent(out) :: err
end subroutine

Arguments

itg: the integrator to be created
err: the error code (only Fortran)

Return Value

the error code (only C)

Disposal of an integrator

The integrator must be disposed by using the following function or routine when the integrator is no more needed.

void gtoint_integrator_destroy(gtoint_integrator_t itg);

Fortran

subroutine gtoint_integrator_destroy(itg)
   type(C_PTR), intent(in) :: itg
end subroutine

Argument

itg: the integrator to be disposed; nothing is done if GTOINT_NULL (in C) or c_null_ptr (in Fortran)

Duplicate of an integrator

The integrator can be duplicated by using the following function or routine.

gtoint_error_t gtoint_integrator_copy(gtoint_integrator_t *itg, gtoint_integrator_t src);

Fortran

subroutine gtoint_integrator_copy(itg, src, err)
   type(C_PTR), intent(out) :: itg
   type(C_PTR), intent(in) :: src
   integer(C_INT), intent(out) :: err
end subroutine

Argument

itg: the integrator to be created by copying
src: the integrator to be copied
err: the error code (only Fortran)

Return Value

the error code (only C)

Cleanup of work memory

The work memory automatically grown in the integrator can be deallocated by using the following function or routine.

void gtoint_integrator_cleanup_memory(gtoint_integrator_t itg);

Fortran

subroutine gtoint_integrator_cleanup_memory(itg)
   type(C_PTR), intent(in) :: itg
end subroutine

Argument

itg: the integrator whose work memory is to be deallocated

Change of the integral error tolerance

The error tolerance of integrals can be changed by using the following function or routine. The error tolerance is used for nuclear attraction integrals, electron repulsion integrals, and ECP integrals. The default value is 1e-10.

void gtoint_integrator_set_error_tolerance(gtoint_integrator_t itg, double tol);

Fortran

subroutine gtoint_integrator_set_error_tolerance(itg, tol)
   type(C_PTR), intent(in) :: itg
   real(8), intent(in) :: tol
end subroutine

Arguments

itg: the integrator whose error tolerance is to be changed
tol: the new error tolerance

Retrieval of the integral error tolerance

The error tolerance of integrals can be retrieved by using the following function or routine. The error tolerance is used for nuclear attraction integrals, electron repulsion integrals, and ECP integrals.

double gtoint_integrator_get_error_tolerance(gtoint_integrator_t itg);

Fortran

subroutine gtoint_integrator_get_error_tolerance(itg, tol)
   type(C_PTR), intent(in) :: itg
   real(8), intent(out) :: tol
end subroutine

Arguments

itg: the integrator whose error tolerance is to be retrieved
tol: the current error tolerance (only Fortran)

Return Value

the current error tolerance (only C)

Change of the integral cutoff

The cutoff of integrals can be changed by using the following function or routine. The cutoff is used for ECP integrals. The default value is 1e-15.

void gtoint_integrator_set_cutoff(gtoint_integrator_t itg, double cut);

Fortran

subroutine gtoint_integrator_set_cutoff(itg, cut)
   type(C_PTR), intent(in) :: itg
   real(8), intent(in) :: cut
end subroutine

Arguments

itg: the integrator whose cutoff is to be changed
cut: the new cutoff

Retrieval of the integral cutoff

The cutoff of integrals can be retrieved by using the following function or routine. The cutoff is used for ECP integrals.

double gtoint_integrator_get_cutoff(gtoint_integrator_t itg);

Fortran

subroutine gtoint_integrator_get_cutoff(itg, cut)
   type(C_PTR), intent(in) :: itg
   real(8), intent(out) :: cut
end subroutine

Arguments

itg: the integrator whose cutoff is to be retrieved
cut: the current cutoff (only Fortran)

Return Value

the current cutoff (only C)

Construction of basis functions

The basis functions are defined using the following

Libgtoint

Install / Use

README

LibGtoint

Overview

Installation

For Unix-like OS

For Windows

Using Visual Studio

Using MinGW-w64

API

Preparation

Basic types

Error codes

Creation of an integrator

Disposal of an integrator

Duplicate of an integrator

Cleanup of work memory

Change of the integral error tolerance

Retrieval of the integral error tolerance

Change of the integral cutoff

Retrieval of the integral cutoff

Construction of basis functions