dftd4_api Module

Definition of the public C-API of dftd4

/* This file is part of dftd4.
 * SPDX-Identifier: LGPL-3.0-or-later
 *
 * dftd4 is free software: you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * dftd4 is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with dftd4.  If not, see <https://www.gnu.org/licenses/>.
**/
#pragma once

#ifdef __cplusplus
#define DFTD4_API_ENTRY extern "C"
#else
#define DFTD4_API_ENTRY extern
#ifndef DFTD4_CFFI
#include <stdbool.h>
#endif
#endif
#define DFTD4_API_CALL
#define DFTD4_API_SUFFIX__V_3_0
#define DFTD4_API_SUFFIX__V_3_1
#define DFTD4_API_SUFFIX__V_3_2
#define DFTD4_API_SUFFIX__V_3_3
#define DFTD4_API_SUFFIX__V_3_4
#define DFTD4_API_SUFFIX__V_3_5
#define DFTD4_API_SUFFIX__V_4_0

/// Error handle class
typedef struct _dftd4_error* dftd4_error;

/// Molecular structure data class
typedef struct _dftd4_structure* dftd4_structure;

/// Dispersion model class
typedef struct _dftd4_model* dftd4_model;

/// Damping parameter class
typedef struct _dftd4_param* dftd4_param;

/*
 * Type generic macro for convenience
**/

#define dftd4_delete(ptr) _Generic((ptr), \
                       dftd4_error: dftd4_delete_error, \
                   dftd4_structure: dftd4_delete_structure, \
                       dftd4_model: dftd4_delete_model, \
                       dftd4_param: dftd4_delete_param \
                                  )(&ptr)

/*
 * Global API queries
**/

/// Obtain library version as major * 10000 + minor + 100 + patch
DFTD4_API_ENTRY int DFTD4_API_CALL
dftd4_get_version(void) DFTD4_API_SUFFIX__V_3_0;

/*
 * Error handle class
**/

/// Create new error handle object
DFTD4_API_ENTRY dftd4_error DFTD4_API_CALL
dftd4_new_error(void) DFTD4_API_SUFFIX__V_3_0;

/// Check error handle status
DFTD4_API_ENTRY int DFTD4_API_CALL
dftd4_check_error(dftd4_error /* error */) DFTD4_API_SUFFIX__V_3_0;

/// Get error message from error handle
DFTD4_API_ENTRY void DFTD4_API_CALL
dftd4_get_error(dftd4_error /* error */,
                char* /* buffer */,
                const int* /* buffersize */) DFTD4_API_SUFFIX__V_3_0;

/// Delete error handle object
DFTD4_API_ENTRY void DFTD4_API_CALL
dftd4_delete_error(dftd4_error* /* error */) DFTD4_API_SUFFIX__V_3_0;

/*
 * Molecular structure data class
**/

/// Create new molecular structure data (quantities in Bohr)
DFTD4_API_ENTRY dftd4_structure DFTD4_API_CALL
dftd4_new_structure(dftd4_error /* error */,
                    const int /* natoms */,
                    const int* /* numbers [natoms] */,
                    const double* /* positions [natoms][3] */,
                    const double* /* charge */,
                    const double* /* lattice [3][3] */,
                    const bool* /* periodic [3] */) DFTD4_API_SUFFIX__V_3_0;

/// Delete molecular structure data
DFTD4_API_ENTRY void DFTD4_API_CALL
dftd4_delete_structure(dftd4_structure* /* mol */) DFTD4_API_SUFFIX__V_3_0;

/// Update coordinates and lattice parameters (quantities in Bohr)
DFTD4_API_ENTRY void DFTD4_API_CALL
dftd4_update_structure(dftd4_error /* error */,
                       dftd4_structure /* mol */,
                       const double* /* positions [natoms][3] */,
                       const double* /* lattice [3][3] */) DFTD4_API_SUFFIX__V_3_0;

/*
 * Dispersion model class
**/

/// Create new D4 dispersion model
DFTD4_API_ENTRY dftd4_model DFTD4_API_CALL
dftd4_new_d4_model(dftd4_error /* error */,
                   dftd4_structure /* mol */) DFTD4_API_SUFFIX__V_3_0;

/// Create new D4 dispersion model
DFTD4_API_ENTRY dftd4_model DFTD4_API_CALL
dftd4_new_d4s_model(dftd4_error /* error */,
                    dftd4_structure /* mol */) DFTD4_API_SUFFIX__V_4_0;

/// Create new D4 dispersion model
DFTD4_API_ENTRY dftd4_model DFTD4_API_CALL
dftd4_custom_d4_model(dftd4_error /* error */,
                      dftd4_structure /* mol */,
                      double /* ga */,
                      double /* gc */,
                      double /* wf */) DFTD4_API_SUFFIX__V_3_1;

/// Create new D4 dispersion model
DFTD4_API_ENTRY dftd4_model DFTD4_API_CALL
dftd4_custom_d4s_model(dftd4_error /* error */,
                      dftd4_structure /* mol */,
                      double /* ga */,
                      double /* gc */) DFTD4_API_SUFFIX__V_4_0;


/// Delete dispersion model
DFTD4_API_ENTRY void DFTD4_API_CALL
dftd4_delete_model(dftd4_model* /* disp */) DFTD4_API_SUFFIX__V_3_0;

/*
 * Damping parameter class
**/

/// Create new rational damping parameters
DFTD4_API_ENTRY dftd4_param DFTD4_API_CALL
dftd4_new_rational_damping(dftd4_error /* error */,
                           double /* s6 */,
                           double /* s8 */,
                           double /* s9 */,
                           double /* a1 */,
                           double /* a2 */,
                           double /* alp */) DFTD4_API_SUFFIX__V_3_0;

/// Load rational damping parameters from internal storage
DFTD4_API_ENTRY dftd4_param DFTD4_API_CALL
dftd4_load_rational_damping(dftd4_error /* error */,
                            char* /* method */,
                            bool /* mdb */) DFTD4_API_SUFFIX__V_3_0;

/// Delete damping parameters
DFTD4_API_ENTRY void DFTD4_API_CALL
dftd4_delete_param(dftd4_param* /* param */) DFTD4_API_SUFFIX__V_3_0;

/*
 * Perform dispersion calculations
**/

/// Evaluate properties related to the dispersion model
DFTD4_API_ENTRY void DFTD4_API_CALL
dftd4_get_properties(dftd4_error /* error */,
                     dftd4_structure /* mol */,
                     dftd4_model /* disp */,
                     double* /* cn[n] */,
                     double* /* charges[n] */,
                     double* /* c6[n*n] */,
                     double* /* alpha[n] */) DFTD4_API_SUFFIX__V_3_1;

/// Evaluate the dispersion energy and its derivative
DFTD4_API_ENTRY void DFTD4_API_CALL
dftd4_get_dispersion(dftd4_error /* error */,
                     dftd4_structure /* mol */,
                     dftd4_model /* disp */,
                     dftd4_param /* param */,
                     double* /* energy */,
                     double* /* gradient[n][3] */,
                     double* /* sigma[3][3] */) DFTD4_API_SUFFIX__V_3_0;

/// Evaluate the dispersion hessian numerically
DFTD4_API_ENTRY void DFTD4_API_CALL
dftd4_get_numerical_hessian(dftd4_error /* error */,
                            dftd4_structure /* mol */,
                            dftd4_model /* disp */,
                            dftd4_param /* param */,
                            double* /* hess[n][3][n][3] */) DFTD4_API_SUFFIX__V_3_5;

/// Evaluate the pairwise representation of the dispersion energy
DFTD4_API_ENTRY void DFTD4_API_CALL
dftd4_get_pairwise_dispersion(dftd4_error /* error */,
                              dftd4_structure /* mol */,
                              dftd4_model /* disp */,
                              dftd4_param /* param */,
                              double* /* pair_energy2[n][n] */,
                              double* /* pair_energy3[n][n] */) DFTD4_API_SUFFIX__V_3_2;

Uses


Variables

Type Visibility Attributes Name Initial
logical, private, parameter :: debug = .false.
character(len=*), private, parameter :: namespace = "dftd4_"

Namespace for C routines

Derived Types

type, public ::  vp_error

Void pointer to error handle

Components

Type Visibility Attributes Name Initial
type(error_type), public, allocatable :: ptr

Actual payload

type, public ::  vp_model

Void pointer to dispersion model

Components

Type Visibility Attributes Name Initial
class(dispersion_model), public, allocatable :: ptr

Actual payload

type, public ::  vp_param

Void pointer to damping parameters

Components

Type Visibility Attributes Name Initial
class(damping_param), public, allocatable :: ptr

Actual payload

type, public ::  vp_structure

Void pointer to molecular structure data

Components

Type Visibility Attributes Name Initial
type(structure_type), public :: ptr

Actual payload

Functions

public function check_error_api(verror) result(status) bind(C, name=namespace//"check_error")

Check error handle status

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror

Return Value integer(kind=c_int)

public function custom_d4_model_api(verror, vmol, ga, gc, wf) result(vdisp) bind(C, name=namespace//"custom_d4_model")

Create new custom D4 dispersion model

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
type(c_ptr), value :: vmol
real(kind=c_double), intent(in), value :: ga
real(kind=c_double), intent(in), value :: gc
real(kind=c_double), intent(in), value :: wf

Return Value type(c_ptr)

public function custom_d4s_model_api(verror, vmol, ga, gc) result(vdisp) bind(C, name=namespace//"custom_d4s_model")

Create new custom D4S dispersion model

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
type(c_ptr), value :: vmol
real(kind=c_double), intent(in), value :: ga
real(kind=c_double), intent(in), value :: gc

Return Value type(c_ptr)

public function get_version_api() result(version) bind(C, name=namespace//"get_version")

Obtain library version as major * 10000 + minor + 100 + patch

Arguments

None

Return Value integer(kind=c_int)

public function load_rational_damping_api(verror, charptr, atm) result(vparam) bind(C, name=namespace//"load_rational_damping")

Load rational damping parameters from internal storage

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
character(kind=c_char, len=1), intent(in) :: charptr(*)
logical(kind=c_bool), intent(in), value :: atm

Return Value type(c_ptr)

public function new_d4_model_api(verror, vmol) result(vdisp) bind(C, name=namespace//"new_d4_model")

Create new D4 dispersion model

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
type(c_ptr), value :: vmol

Return Value type(c_ptr)

public function new_d4s_model_api(verror, vmol) result(vdisp) bind(C, name=namespace//"new_d4s_model")

Create new D4S dispersion model

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
type(c_ptr), value :: vmol

Return Value type(c_ptr)

public function new_error_api() result(verror) bind(C, name=namespace//"new_error")

Create new error handle object

Arguments

None

Return Value type(c_ptr)

public function new_rational_damping_api(verror, s6, s8, s9, a1, a2, alp) result(vparam) bind(C, name=namespace//"new_rational_damping")

Create new rational damping parameters

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
real(kind=c_double), intent(in), value :: s6
real(kind=c_double), intent(in), value :: s8
real(kind=c_double), intent(in), value :: s9
real(kind=c_double), intent(in), value :: a1
real(kind=c_double), intent(in), value :: a2
real(kind=c_double), intent(in), value :: alp

Return Value type(c_ptr)

public function new_structure_api(verror, natoms, numbers, positions, c_charge, c_lattice, c_periodic) result(vmol) bind(C, name=namespace//"new_structure")

Create new molecular structure data (quantities in Bohr)

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
integer(kind=c_int), intent(in), value :: natoms
integer(kind=c_int), intent(in) :: numbers(natoms)
real(kind=c_double), intent(in) :: positions(3,natoms)
real(kind=c_double), intent(in), optional :: c_charge
real(kind=c_double), intent(in), optional :: c_lattice(3,3)
logical(kind=c_bool), intent(in), optional :: c_periodic(3)

Return Value type(c_ptr)


Subroutines

private subroutine c_f_character(rhs, lhs)

Arguments

Type IntentOptional Attributes Name
character(kind=c_char, len=1), intent(in) :: rhs(*)
character(kind=c_char, len=:), intent(out), allocatable :: lhs

public subroutine delete_error_api(verror) bind(C, name=namespace//"delete_error")

Delete error handle object

Arguments

Type IntentOptional Attributes Name
type(c_ptr), intent(inout) :: verror

public subroutine delete_model_api(vdisp) bind(C, name=namespace//"delete_model")

Delete dispersion model

Arguments

Type IntentOptional Attributes Name
type(c_ptr), intent(inout) :: vdisp

public subroutine delete_param_api(vparam) bind(C, name=namespace//"delete_param")

Delete damping parameters

Arguments

Type IntentOptional Attributes Name
type(c_ptr), intent(inout) :: vparam

public subroutine delete_structure_api(vmol) bind(C, name=namespace//"delete_structure")

Delete molecular structure data

Arguments

Type IntentOptional Attributes Name
type(c_ptr), intent(inout) :: vmol

private subroutine f_c_character(rhs, lhs, len)

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: rhs
character(kind=c_char, len=1), intent(out) :: lhs(*)
integer, intent(in) :: len

public subroutine get_dispersion_api(verror, vmol, vdisp, vparam, energy, c_gradient, c_sigma) bind(C, name=namespace//"get_dispersion")

Calculate dispersion

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
type(c_ptr), value :: vmol
type(c_ptr), value :: vdisp
type(c_ptr), value :: vparam
real(kind=c_double), intent(out) :: energy
real(kind=c_double), intent(out), optional :: c_gradient(3,*)
real(kind=c_double), intent(out), optional :: c_sigma(3,3)

public subroutine get_error_api(verror, charptr, buffersize) bind(C, name=namespace//"get_error")

Get error message from error handle

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
character(kind=c_char, len=1), intent(inout) :: charptr(*)
integer(kind=c_int), intent(in), optional :: buffersize

private subroutine get_numerical_hessian_api(verror, vmol, vdisp, vparam, c_hessian) bind(C, name=namespace//"get_numerical_hessian")

Calculate hessian numerically

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
type(c_ptr), value :: vmol
type(c_ptr), value :: vdisp
type(c_ptr), value :: vparam
real(kind=c_double), intent(out) :: c_hessian(*)

public subroutine get_pairwise_dispersion_api(verror, vmol, vdisp, vparam, c_pair_energy2, c_pair_energy3) bind(C, name=namespace//"get_pairwise_dispersion")

Calculate pairwise representation of dispersion energy

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
type(c_ptr), value :: vmol
type(c_ptr), value :: vdisp
type(c_ptr), value :: vparam
type(c_ptr), intent(in), value :: c_pair_energy2
type(c_ptr), intent(in), value :: c_pair_energy3

public subroutine get_properties_api(verror, vmol, vdisp, c_cn, c_charges, c_c6, c_alpha) bind(C, name=namespace//"get_properties")

Calculate dispersion

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
type(c_ptr), value :: vmol
type(c_ptr), value :: vdisp
real(kind=c_double), intent(out), optional :: c_cn(*)
real(kind=c_double), intent(out), optional :: c_charges(*)
real(kind=c_double), intent(out), optional :: c_c6(*)
real(kind=c_double), intent(out), optional :: c_alpha(*)

public subroutine update_structure_api(verror, vmol, positions, lattice) bind(C, name=namespace//"update_structure")

Update coordinates and lattice parameters (quantities in Bohr)

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
type(c_ptr), value :: vmol
real(kind=c_double), intent(in) :: positions(3,*)
real(kind=c_double), intent(in), optional :: lattice(3,3)

private subroutine verify_structure(error, mol)

Cold fusion check

Arguments

Type IntentOptional Attributes Name
type(error_type), intent(out), allocatable :: error
type(structure_type), intent(in) :: mol