C API to the extended tight binding programΒΆ
The xtb program can included in other application by its
C application programmable interface (API) for all languages that
cannot access the Fortran modules directly.
The API declarations are given in xtb.h
Important
The C API is considered stable with version 6.3.0 and will be kept compatible to following versions.
Previous experimental API versions from the 6.2 series are deprecated.
The C side has to work with four different Fortran objects which are allocated and deallocated on the Fortran side and only provided as opaque data pointer.
Generally the first set for every API call is to construct a
calculation environment xtb_TEnvironment, which handles the input
and output streams and the error log.
The API will not perform any calculation if a null pointer is passed
instead of the environment and fail silently.
Note that once the environment has caught on an error all further
API calls will fail unless the environment is freed again and the
error has been handled.
xtb provides a persistent environment as well which is handled
entirely by the API. Producing an error for this environment is
consider fatal and will halt the program (usually via drastic means,
i.e., without giving the caller a way to react).
This case is always considered a bug in the API and should be reported.
The input data for the calculation is generated as molecular
structure data xtb_TMolecule. Note that the number of atoms,
the atomic number, the boundary conditions, total charge and
multiplicity are immutable and require to reconstruct the object.
Cartesian coordinates and lattice parameters are provided in Bohr
and can be updated after the object has been constructed.
Both the update and the constructor will fail on invalid input,
which are to close interatomic distances or atomic number outside of
the range 1 to 118 (while individual methods might impose additional
constraints).
The actual calculation can be performed with a single point
calculator xtb_TCalculator which must be loaded with a particular
parametrisation before it can be used for a calculation.
GFN2-xTB and GFN1-xTB can savely load their parametrisation without
a parameter file. For the experimental GFN0-xTB a parameter file
is required in the XTBPATH or must be provided by the API.
The GFN-FF can also provide its own parameters internally but
API support is still experimental.
Finally, the calculation results are stored in the xtb_TResults
object which can also be used to restart calculations from previous
runs (e.g. after updating coordinates).
The calculation results can be queried for properties they will
return in error in case the property is not available.
Passing calculation results from one calculator to another will
usually result in dimension missmatches, it is recommended to
reconstruct the results object for this purpose.
Generally, the API tries to be particular flexible in this case
and will try to reallocate the individual components as necessary.
Note that this can fail in particular if the total charge or
multiplicity of the molecular structure has changed.
A simple example program to obtain the total energy from a GFN2-xTB calculation is given here.
#include <stddef.h>
#include "xtb.h"
int main (int argc, char** argv)
{
double energy = 0.0;
int const natoms = 7;
int const attyp[7] = {6,6,6,1,1,1,1};
double const charge = 0.0;
int const uhf = 0;
double const coord[3*7] =
{0.00000000000000, 0.00000000000000,-1.79755622305860,
0.00000000000000, 0.00000000000000, 0.95338756106749,
0.00000000000000, 0.00000000000000, 3.22281255790261,
-0.96412815539807,-1.66991895015711,-2.53624948351102,
-0.96412815539807, 1.66991895015711,-2.53624948351102,
1.92825631079613, 0.00000000000000,-2.53624948351102,
0.00000000000000, 0.00000000000000, 5.23010455462158};
/*
* All objects except for the molecular structure can be
* constructued without other objects present.
*
* The construction of the molecular structure locks the
* number of atoms, atomic number, total charge, multiplicity
* and boundary conditions.
**/
xtb_TEnvironment env = xtb_newEnvironment();
xtb_TCalculator calc = xtb_newCalculator();
xtb_TResults res = xtb_newResults();
xtb_TMolecule mol = xtb_newMolecule(
env, &natoms, attyp, coord, &charge, &uhf, NULL, NULL);
if (xtb_checkEnvironment(env)) {
xtb_showEnvironment(env, NULL);
return 1;
}
/*
* Apply changes to the environment which will be respected
* in all further API calls.
**/
xtb_setVerbosity(env, XTB_VERBOSITY_FULL);
if (xtb_checkEnvironment(env)) {
xtb_showEnvironment(env, NULL);
return 1;
}
/*
* Load a parametrisation, the last entry is a char* which can
* be used to provide a particular parameter file.
*
* Otherwise the XTBPATH environment variable is used to find
* parameter files.
*
* The calculator has to be reconstructed if the molecular
* structure is reconstructed.
**/
xtb_loadGFN2xTB(env, mol, calc, NULL);
if (xtb_checkEnvironment(env)) {
xtb_showEnvironment(env, NULL);
return 1;
}
/*
* Actual calculation, will populate the results object,
* the API can raise errors on failed SCF convergence or other
* numerical problems.
*
* Not supported boundary conditions are usually raised here.
**/
xtb_singlepoint(env, mol, calc, res);
if (xtb_checkEnvironment(env)) {
xtb_showEnvironment(env, NULL);
return 1;
}
/*
* Query the environment for properties, an error in the environment
* is not considered blocking for this calls and allows to query
* for multiple entries before handling possible errors
**/
xtb_getEnergy(env, res, &energy);
if (xtb_checkEnvironment(env)) {
xtb_showEnvironment(env, NULL);
return 1;
}
/*
* deconstructor will deallocate the objects and overwrite the
* pointer with NULL
**/
xtb_delResults(&res);
xtb_delCalculator(&calc);
xtb_delMolecule(&mol);
xtb_delEnvironment(&env);
return 0;
}
The header additionally defines macros for the version of the xtb API
to guard usage of API functionalities introduced in particular versions.