Interfacing TCHInt
==================

For using the library, a cmake config file ``tchint-config.cmake`` is
created in the build directory. By using the cmake ``find_package``
command, the ``tchint`` library can be made visible to cmake as a
target ``tchint`` with corresponding include paths and linkage, e.g.
by including:

.. code-block:: cmake

  find_package(tchint)
  target_link_library(<my_target> tchint)

in the CMakeLists.txt of a calling program, we can link the target
``<my_target>`` to the ``tchint`` library. Note that this requires
having the tchint build directory visible to cmake, which can be
achieved e.g. by setting the environment variable
``TCHINT_ROOT=<tchint_build_dir>``.

Alternatively, one can also manually link to the ``libtchint.so``
library. This then requires including the module directory
``<tchint_build_dir>/include`` when compiling, as the module files are
required at compile time.

Exported functions
^^^^^^^^^^^^^^^^^^

The direct interface is given in the form of the ``tchint`` module in
``src/tchint.F90`` (or ``src/tchint.h`` for the C interface; note this is put
into `src/include` of the build directory), which contains the
interface functions for external code to call in order to:
* set up the integrals
* receive the value of an integral
* receive two- or three-body matrix elements
* finalize the library and deallocate resources

The corresponding functions' signatures are:

.. code-block:: fortran

  !> Return a matrix element of a given excitation, i.e. between
  !! a determinant D and a determinant excit * D (defined as replacing
  !! excit(1,:) in D with excit(2,:)
  !! This follows the slater condon rules for three-body terms
  !> @param[in] D determinant from which the electrons are excited
  !> @param[in] ex (2,lvl)-matrix with the ex(1,:) containing the
  !!               source and ex(2,:) the target of the excitation
  !!               as spin orbitals
  !> @param[in] ex_parity parity of the excitation, i.e. if an even or
  !!                      odd number of electrons are exchanged when
  !!                      bringing the new determinant into canonical
  !!                      order
  function tc_matel(D, excit) result(matel)
    integer, intent(in) :: D(:)
    integer, intent(in) :: excit(:,:)
    real(dp) :: matel
  end function

.. code-block:: fortran

  !> Initialize the tchint module. This pre-calculates all required
  !! integrals and can thus take a substantial amount of time.
  !! The settings are read from the tchint.json file.
  subroutine tchint_init()
  end subroutine

.. code-block:: fortran

  !> Finalize the tchint module, deallocating all resources
  subroutine tchint_finalize()
  end subroutine tchint_finalize

These functions can be called once the ``tchint`` module has been
loaded with:

.. code-block:: fortran

  use tchint

An example program using the library is also availabe in
``examples/using_tchint.f90``, with the corresponding
``examples/CMakeLists.txt`` for building the application.

The standalone program runs ``tchint_init`` followed by
``tchint_finalize``. This precalculates all required integrals and
writes them to disk. See also :ref:`running` for a description of the
functionality.