dftd3_api Module

Definition of the public C-API of s-dftd3

/* This file is part of s-dftd3.
 * SPDX-Identifier: LGPL-3.0-or-later
 *
 * s-dftd3 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.
 *
 * s-dftd3 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 s-dftd3.  If not, see <https://www.gnu.org/licenses/>.
**/
#pragma once

#ifdef __cplusplus
#define SDFTD3_API_ENTRY extern "C"
#else
#define SDFTD3_API_ENTRY extern
#ifndef SDFTD3_CFFI
#include <stdbool.h>
#endif
#endif
#define SDFTD3_API_CALL
#define SDFTD3_API_SUFFIX__V_0_2
#define SDFTD3_API_SUFFIX__V_0_3
#define SDFTD3_API_SUFFIX__V_0_4
#define SDFTD3_API_SUFFIX__V_0_5
#define SDFTD3_API_SUFFIX__V_1_3

/// Error handle class
typedef struct _dftd3_error* dftd3_error;

/// Molecular structure data class
typedef struct _dftd3_structure* dftd3_structure;

/// Dispersion model class
typedef struct _dftd3_model* dftd3_model;

/// Counter-poisecorrection parameters class
typedef struct _dftd3_gcp* dftd3_gcp;

/// Damping parameter class
typedef struct _dftd3_param* dftd3_param;

/*
 * Type generic macro for convenience
**/

#define dftd3_delete(ptr) _Generic((ptr), \
                       dftd3_error: dftd3_delete_error, \
                   dftd3_structure: dftd3_delete_structure, \
                       dftd3_model: dftd3_delete_model, \
                       dftd3_param: dftd3_delete_param, \
                         dftd3_gcp: dftd3_delete_gcp \
                                  )(&ptr)

/*
 * Global API queries
**/

/// Obtain library version as major * 10000 + minor + 100 + patch
SDFTD3_API_ENTRY int SDFTD3_API_CALL
dftd3_get_version() SDFTD3_API_SUFFIX__V_0_2;

/*
 * Error handle class
**/

/// Create new error handle object
SDFTD3_API_ENTRY dftd3_error SDFTD3_API_CALL
dftd3_new_error() SDFTD3_API_SUFFIX__V_0_2;

/// Check error handle status
SDFTD3_API_ENTRY int SDFTD3_API_CALL
dftd3_check_error(dftd3_error /* error */) SDFTD3_API_SUFFIX__V_0_2;

/// Get error message from error handle
SDFTD3_API_ENTRY void SDFTD3_API_CALL
dftd3_get_error(dftd3_error /* error */,
                char* /* buffer */,
                const int* /* buffersize */) SDFTD3_API_SUFFIX__V_0_2;

/// Delete error handle object
SDFTD3_API_ENTRY void SDFTD3_API_CALL
dftd3_delete_error(dftd3_error* /* error */) SDFTD3_API_SUFFIX__V_0_2;

/*
 * Molecular structure data class
**/

/// Create new molecular structure data (quantities in Bohr)
SDFTD3_API_ENTRY dftd3_structure SDFTD3_API_CALL
dftd3_new_structure(dftd3_error /* error */,
                    const int /* natoms */,
                    const int* /* numbers [natoms] */,
                    const double* /* positions [natoms][3] */,
                    const double* /* lattice [3][3] */,
                    const bool* /* periodic [3] */) SDFTD3_API_SUFFIX__V_0_2;

/// Delete molecular structure data
SDFTD3_API_ENTRY void SDFTD3_API_CALL
dftd3_delete_structure(dftd3_structure* /* mol */) SDFTD3_API_SUFFIX__V_0_2;

/// Update coordinates and lattice parameters (quantities in Bohr)
SDFTD3_API_ENTRY void SDFTD3_API_CALL
dftd3_update_structure(dftd3_error /* error */,
                       dftd3_structure /* mol */,
                       const double* /* positions [natoms][3] */,
                       const double* /* lattice [3][3] */) SDFTD3_API_SUFFIX__V_0_2;

/*
 * Dispersion model class
**/

/// Create new D3 dispersion model
SDFTD3_API_ENTRY dftd3_model SDFTD3_API_CALL
dftd3_new_d3_model(dftd3_error /* error */,
                   dftd3_structure /* mol */) SDFTD3_API_SUFFIX__V_0_2;

/// Set realspace cutoffs (quantities in Bohr)
SDFTD3_API_ENTRY void SDFTD3_API_CALL
dftd3_set_model_realspace_cutoff(dftd3_error /* error */,
                                 dftd3_model /* model */,
                                 double /* disp2 */,
                                 double /* disp3 */,
                                 double /* cn */) SDFTD3_API_SUFFIX__V_0_5;

/// Delete dispersion model
SDFTD3_API_ENTRY void SDFTD3_API_CALL
dftd3_delete_model(dftd3_model* /* disp */) SDFTD3_API_SUFFIX__V_0_2;

/*
 * Damping parameter class
**/

/// Create new zero damping parameters
SDFTD3_API_ENTRY dftd3_param SDFTD3_API_CALL
dftd3_new_zero_damping(dftd3_error /* error */,
                       double /* s6 */,
                       double /* s8 */,
                       double /* s9 */,
                       double /* rs6 */,
                       double /* rs8 */,
                       double /* alp */) SDFTD3_API_SUFFIX__V_0_4;

/// Load zero damping parameters from internal storage
SDFTD3_API_ENTRY dftd3_param SDFTD3_API_CALL
dftd3_load_zero_damping(dftd3_error /* error */,
                        char* /* method */,
                        bool /* atm */) SDFTD3_API_SUFFIX__V_0_4;

/// Create new rational damping parameters
SDFTD3_API_ENTRY dftd3_param SDFTD3_API_CALL
dftd3_new_rational_damping(dftd3_error /* error */,
                           double /* s6 */,
                           double /* s8 */,
                           double /* s9 */,
                           double /* a1 */,
                           double /* a2 */,
                           double /* alp */) SDFTD3_API_SUFFIX__V_0_4;

/// Load rational damping parameters from internal storage
SDFTD3_API_ENTRY dftd3_param SDFTD3_API_CALL
dftd3_load_rational_damping(dftd3_error /* error */,
                            char* /* method */,
                            bool /* atm */) SDFTD3_API_SUFFIX__V_0_4;

/// Create new modified zero damping parameters
SDFTD3_API_ENTRY dftd3_param SDFTD3_API_CALL
dftd3_new_mzero_damping(dftd3_error /* error */,
                        double /* s6 */,
                        double /* s8 */,
                        double /* s9 */,
                        double /* rs6 */,
                        double /* rs8 */,
                        double /* alp */,
                        double /* bet */) SDFTD3_API_SUFFIX__V_0_4;

/// Load modified zero damping parameters from internal storage
SDFTD3_API_ENTRY dftd3_param SDFTD3_API_CALL
dftd3_load_mzero_damping(dftd3_error /* error */,
                         char* /* method */,
                         bool /* atm */) SDFTD3_API_SUFFIX__V_0_4;

/// Create new modified rational damping parameters
SDFTD3_API_ENTRY dftd3_param SDFTD3_API_CALL
dftd3_new_mrational_damping(dftd3_error /* error */,
                            double /* s6 */,
                            double /* s8 */,
                            double /* s9 */,
                            double /* a1 */,
                            double /* a2 */,
                            double /* alp */) SDFTD3_API_SUFFIX__V_0_4;

/// Load modified rational damping parameters from internal storage
SDFTD3_API_ENTRY dftd3_param SDFTD3_API_CALL
dftd3_load_mrational_damping(dftd3_error /* error */,
                             char* /* method */,
                             bool /* atm */) SDFTD3_API_SUFFIX__V_0_4;

/// Create new optimized power damping parameters
SDFTD3_API_ENTRY dftd3_param SDFTD3_API_CALL
dftd3_new_optimizedpower_damping(dftd3_error /* error */,
                                 double /* s6 */,
                                 double /* s8 */,
                                 double /* s9 */,
                                 double /* a1 */,
                                 double /* a2 */,
                                 double /* alp */,
                                 double /* bet */) SDFTD3_API_SUFFIX__V_0_5;

/// Load optimized power damping parameters from internal storage
SDFTD3_API_ENTRY dftd3_param SDFTD3_API_CALL
dftd3_load_optimizedpower_damping(dftd3_error /* error */,
                                  char* /* method */,
                                  bool /* atm */) SDFTD3_API_SUFFIX__V_0_5;

/// Delete damping parameters
SDFTD3_API_ENTRY void SDFTD3_API_CALL
dftd3_delete_param(dftd3_param* /* param */) SDFTD3_API_SUFFIX__V_0_2;

/*
 * Counter-poise correction parameters
**/

/// Load geometric counter-poise parameters from internal storage
SDFTD3_API_ENTRY dftd3_gcp SDFTD3_API_CALL
dftd3_load_gcp_param(dftd3_error /* error */,
                     dftd3_structure /* mol */,
                     char* /* method */,
                     char* /* basis */) SDFTD3_API_SUFFIX__V_1_3;

/// Set realspace cutoffs (quantities in Bohr)
SDFTD3_API_ENTRY void SDFTD3_API_CALL
dftd3_set_gcp_realspace_cutoff(dftd3_error /* error */,
                               dftd3_gcp /* gcp */,
                               double /* bas */,
                               double /* srb */) SDFTD3_API_SUFFIX__V_1_3;

/// Delete counter-poise parameters
SDFTD3_API_ENTRY void SDFTD3_API_CALL
dftd3_delete_gcp(dftd3_gcp* /* gcp */) SDFTD3_API_SUFFIX__V_1_3;

/*
 * Perform dispersion calculations
**/

/// Evaluate the dispersion energy and its derivatives
SDFTD3_API_ENTRY void SDFTD3_API_CALL
dftd3_get_dispersion(dftd3_error /* error */,
                     dftd3_structure /* mol */,
                     dftd3_model /* disp */,
                     dftd3_param /* param */,
                     double* /* energy */,
                     double* /* gradient[n][3] */,
                     double* /* sigma[3][3] */) SDFTD3_API_SUFFIX__V_0_2;

/// Evaluate the pairwise representation of the dispersion energy
SDFTD3_API_ENTRY void SDFTD3_API_CALL
dftd3_get_pairwise_dispersion(dftd3_error /* error */,
                              dftd3_structure /* mol */,
                              dftd3_model /* disp */,
                              dftd3_param /* param */,
                              double* /* pair_energy2[n][n] */,
                              double* /* pair_energy3[n][n] */) SDFTD3_API_SUFFIX__V_0_5;

/*
 * Perform geometric counterpoise calculations
**/

/// Evaluate the dispersion energy and its derivatives
SDFTD3_API_ENTRY void SDFTD3_API_CALL
dftd3_get_counterpoise(dftd3_error /* error */,
                       dftd3_structure /* mol */,
                       dftd3_gcp /* gcp */,
                       double* /* energy */,
                       double* /* gradient[n][3] */,
                       double* /* sigma[3][3] */) SDFTD3_API_SUFFIX__V_1_3;

Uses


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_gcp

Void pointer to counter-poise parameters

Components

Type Visibility Attributes Name Initial
type(realspace_cutoff), public, allocatable :: cutoff

Additional real space cutoff
type(gcp_param), public :: ptr

Actual payload

type, public ::  vp_model

Void pointer to dispersion model

Components

Type Visibility Attributes Name Initial
type(realspace_cutoff), public, allocatable :: cutoff

Additional real space cutoff
type(d3_model), public :: 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 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_gcp_param_api(verror, vmol, cmethod, cbasis) result(vgcp) bind(C, name=namespace//"load_gcp_param")

Create new error handle object

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
type(c_ptr), value :: vmol
character(kind=c_char, len=1), intent(in), optional :: cmethod(*)
character(kind=c_char, len=1), intent(in), optional :: cbasis(*)

Return Value type(c_ptr)

public function load_mrational_damping_api(verror, charptr, atm) result(vparam) bind(C, name=namespace//"load_mrational_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 load_mzero_damping_api(verror, charptr, atm) result(vparam) bind(C, name=namespace//"load_mzero_damping")

Load zero 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 load_optimizedpower_damping_api(verror, charptr, atm) result(vparam) bind(C, name=namespace//"load_optimizedpower_damping")

Load optimized power 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 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 load_zero_damping_api(verror, charptr, atm) result(vparam) bind(C, name=namespace//"load_zero_damping")

Load zero 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_d3_model_api(verror, vmol) result(vdisp) bind(C, name=namespace//"new_d3_model")

Create new D3 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_mrational_damping_api(verror, s6, s8, s9, a1, a2, alp) result(vparam) bind(C, name=namespace//"new_mrational_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_mzero_damping_api(verror, s6, s8, s9, rs6, rs8, alp, bet) result(vparam) bind(C, name=namespace//"new_mzero_damping")

Create new zero 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 :: rs6
real(kind=c_double), intent(in), value :: rs8
real(kind=c_double), intent(in), value :: alp
real(kind=c_double), intent(in), value :: bet

Return Value type(c_ptr)

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

Create new optimized power 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
real(kind=c_double), intent(in), value :: bet

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_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_lattice(3,3)
logical(kind=c_bool), intent(in), optional :: c_periodic(3)

Return Value type(c_ptr)

public function new_zero_damping_api(verror, s6, s8, s9, rs6, rs8, alp) result(vparam) bind(C, name=namespace//"new_zero_damping")

Create new zero 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 :: rs6
real(kind=c_double), intent(in), value :: rs8
real(kind=c_double), intent(in), value :: alp

Return Value type(c_ptr)


Subroutines

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_gcp_api(vgcp) bind(C, name=namespace//"delete_gcp")

Delete counter-poise parameter handle object

Arguments

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

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

public subroutine get_counterpoise_api(verror, vmol, vgcp, energy, c_gradient, c_sigma) bind(C, name=namespace//"get_counterpoise")

Calculate dispersion

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
type(c_ptr), value :: vmol
type(c_ptr), value :: vgcp
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

public subroutine set_gcp_realspace_cutoff(verror, vgcp, bas, srb) bind(C, name=namespace//"set_gcp_realspace_cutoff")

Arguments

Type IntentOptional Attributes Name
type(c_ptr), value :: verror
type(c_ptr), value :: vgcp
real(kind=c_double), intent(in), value :: bas
real(kind=c_double), intent(in), value :: srb

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)