C API

C API#

The C API bindings are provided by using the iso_c_binding intrinsic module. Generally, objects are exported as opaque pointers and can only be manipulated within the library. The API user is required delete all objects created in the library by using the provided deconstructor functions to avoid memory leaks.

Overall four classes of objects are provided by the library

  • error handlers (tblite_error and tblite_context), used to communicate exceptional conditions and errors from the library to the user, also usable to communicate general setting to the library in case of a context handle

  • structure containers (tblite_structure), used to represent the system specific information and geometry data, only the latter are mutable for the user

  • calculator objects (tblite_calculator), used to store actual method parametrisation

  • result and restart data (tblite_result) used to hold calculated properties and persistent data for restarting between calculations

Note

Generally, all quantities provided to the library are assumed to be in atomic units.

Main header#

#include "tblite.h"

Provides convenience functionality for working with the C API bindings for tblite by including all relevant headers and defining general type generic macros for working with the object handles.

Defines

tblite_delete(ptr)#

Generic macro to free an object handle.

Parameters:

  • ptr – Opaque object handle

tblite_check(ptr)#

Generic macro to check for error status

Parameters:

  • ptr – Opaque object handle

Version query#

#include "tblite/version.h"

Warning

doxygenfile: Cannot find file “tblite/version.h

Macro definitions#

#include "tblite/macros.h"

Warning

doxygenfile: Cannot find file “tblite/macros.h

Error handler#

#include "tblite/error.h"

Warning

doxygenfile: Cannot find file “tblite/error.h

Context handler#

#include "tblite/context.h"

Warning

doxygenfile: Cannot find file “tblite/context.h

Molecular structure data#

#include "tblite/structure.h"

Warning

doxygenfile: Cannot find file “tblite/structure.h

Calculator instance#

#include "tblite/calculator.h"

Warning

doxygenfile: Cannot find file “tblite/calculator.h

Interaction container#

#include "tblite/container.h"

Warning

doxygenfile: Cannot find file “tblite/container.h

Result container#

#include "tblite/result.h"

Warning

doxygenfile: Cannot find file “tblite/result.h

Parametrization records#

#include "tblite/param.h"

Warning

doxygenfile: Cannot find file “tblite/param.h

Table data structure#

#include "tblite/table.h"

Warning

doxygenfile: Cannot find file “tblite/table.h

Work partitioning#

The work partition described in Work partitioning is set on the context handle and applied to the calculator when running a calculation.

tblite_set_context_partition(ctx, part, nparts);

Reducing the partial results of all parts is left to the caller, unless the library performs the reduction itself over an MPI communicator, see Distributing over MPI.

int comm = MPI_Comm_c2f(MPI_COMM_WORLD);
tblite_set_context_mpi(ctx, &comm);

Passing NULL instead of a communicator handle selects MPI_COMM_WORLD, which allows using the entry point without including the MPI headers. Both entry points are always available, tblite_set_context_mpi reports an error if the library was built without MPI support, query tblite_get_feature("mpi") to check beforehand.