Ctrl+K

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 mamory leaks.

Overall four classes of objects are provided by the library

  • error handlers (dftd4_error), used to communicate exceptional conditions and errors from the library to the user

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

  • dispersion model objects (dftd4_model), general model for calculating dispersion releated properties

  • damping function objects (dftd4_param) polymorphic objects to represent the actual method parametrisation

Note

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

Error handling#

typedef struct _dftd4_error *dftd4_error;#

Error handle class

The library provides a light error handle type (dftd4_error) for storing error information The error handle requires only small overhead to construct and can only contain a single error.

The handler is represented by an opaque pointer and can only be manipulated by call from the library. The user of those objects is required to delete the handlers again using the library provided deconstructors to avoid memory leaks.

dftd4_error dftd4_new_error();#
Returns:

New allocation for error handle

Create new error handle object

int dftd4_check_error(dftd4_error error);#
Parameters:

  • error – Error handle

Returns:

Current status of error handle, non-zero in case of error

Check error handle status

void dftd4_get_error(dftd4_error error, char *buffer, const int *buffersize);#
Parameters:

  • error – Error handle

  • buffer – Allocation to store error message in

  • buffersize – Maximum length of the buffer (optional)

Get error message from error handle

void dftd4_delete_error(dftd4_error *error);#
Parameters:

  • error – Error handle

Delete error handle object

Structure data#

typedef struct _dftd4_structure *dftd4_structure;#

Molecular structure data class

The structure data is used to represent the system of interest in the library. It contains immutable system specific information like the number of atoms, the unique atom groups and the boundary conditions as well as mutable geometry data like cartesian coordinates and lattice parameters.

dftd4_structure dftd4_new_structure(dftd4_error error, const int natoms, const int *numbers, const double *positions, const double *charge, const double *lattice, const bool *periodic);#
Parameters:

  • natoms – Number of atoms in the system

  • numbers – Atomic numbers of all atoms [natoms]

  • positions – Cartesian coordinates in Bohr [natoms, 3]

  • charge – Total molecular charge (optional)

  • lattice – Lattice parameters in Bohr [3, 3] (optional)

  • periodic – Periodic dimension of the system [3] (optional)

Returns:

New molecular structure data handle

Create new molecular structure data (quantities in Bohr)

void dftd4_delete_structure(dftd4_structure *mol);#
Parameters:

  • mol – Molecular structure data handle

Delete molecular structure data

void dftd4_update_structure(dftd4_error error, dftd4_structure mol, const double *positions, const double *lattice);#
Parameters:

  • error – Error handle

  • mol – Molecular structure data handle

  • positions – Cartesian coordinates in Bohr [natoms, 3]

  • lattice – Lattice parameters in Bohr [3, 3] (optional)

Update coordinates and lattice parameters (quantities in Bohr)

Dispersion model#

typedef struct _dftd4_model *dftd4_model;#

Dispersion model class

Instantiated for a given molecular structure type, it carries no information on the geometry but relies on the atomic species of the structure object. Recreating a structure object requires to recreate the dispersion model as well.

dftd4_model dftd4_new_d4_model(dftd4_error error, dftd4_structure mol);#
Parameters:

  • error – Error handle

  • mol – Molecular structure data handle

Returns:

New dispersion model handle

Create new D4 dispersion model

dftd4_model dftd4_custom_d4_model(dftd4_error error, dftd4_structure mol, double ga, double gc, double wf);#
Parameters:

  • error – Error handle

  • mol – Molecular structure data handle

  • ga – Charge scaling height

  • gc – Charge scaling steepness

  • wf – Weighting factor for coordination number interpolation

Returns:

New dispersion model handle

Create new D4 dispersion model with custom parameters

void dftd4_delete_model(dftd4_model *disp);#
Parameters:

  • disp – Dispersion model handle

Delete dispersion model

Damping parameters#

typedef struct _dftd4_param *dftd4_param;#

Damping parameter class

The damping parameter object determining the short-range behaviour of the dispersion correction. Standard damping parameters like the rational damping are independent of the molecular structure and can easily be reused for several structures or easily exchanged.

dftd4_param dftd4_new_rational_damping(dftd4_error error, double s6, double s8, double s9, double a1, double a2, double alp);#
Parameters:

  • error – Error handle

  • s6 – Scaling factor for C6 contribution

  • s8 – Scaling factor for C8 contribution

  • s9 – Scaling factor for C9 contribution

  • a1 – Scaling factor for critical radii

  • a2 – Offset distance in Bohr for critical radii

Returns:

New damping function parameter handle

Create new rational damping parameters

dftd4_param dftd4_load_rational_damping(dftd4_error error, char *method, bool mdb);#
Parameters:

  • error – Error handle

  • method – Name of the method to load parameters for

  • mbd – Use three-body specific parametrization

Returns:

New damping function parameter handle

Load rational damping parameters from internal storage

void dftd4_delete_param(dftd4_param *param);#
Parameters:

  • param – Damping function parameter handle

Delete damping parameters

Calculation entrypoints#

To evaluate dispersion energies or related properties the dftd4_get_dispersion procedure and similar can be used.

void dftd4_get_properties(dftd4_error error, dftd4_structure mol, dftd4_model disp, double *cn, double *charges, double *c6, double *alpha);#
Parameters:

  • error – Error handle

  • mol – Molecular structure data handle

  • disp – Dispersion model handle

  • cn – Coordination number for all atoms [natoms]

  • charges – Partial charges for all atoms [natoms]

  • c6 – C6 coefficients for all atom pairs [natoms, natoms]

  • alpha – Static polarizibilities for all atoms [natoms]

Evaluate properties related to the dispersion model

void dftd4_get_dispersion(dftd4_error error, dftd4_structure mol, dftd4_model disp, dftd4_param param, double *energy, double *gradient, double *sigma);#
Parameters:

  • error – Error handle

  • mol – Molecular structure data handle

  • disp – Dispersion model handle

  • param – Damping function parameter handle

  • energy – Dispersion energy

  • gradient – Dispersion gradient [natoms, 3] (optional)

  • sigma – Dispersion strain derivatives [3, 3] (optional)

Evaluate the dispersion energy and its derivatives

void dftd4_get_pairwise_dispersion(dftd4_error error, dftd4_structure mol, dftd4_model disp, dftd4_param param, double *pair_energy2, double *pair_energy3);#
Parameters:

  • error – Error handle

  • mol – Molecular structure data handle

  • disp – Dispersion model handle

  • param – Damping function parameter handle

  • energy – Pairwise additive dispersion energies

  • energy – Pairwise non-addititive dispersion energies

Evaluate the pairwise representation of the dispersion energy

Contents