libefp
Data Structures | Macros | Typedefs | Enumerations | Functions
efp.h File Reference

Public libefp interface. More...

Data Structures

struct  efp_opts
 Options controlling EFP computation. More...
 
struct  efp_energy
 EFP energy terms. More...
 
struct  efp_atom
 EFP atom info. More...
 

Macros

#define LIBEFP_VERSION_STRING   "1.4.2"
 Version string. More...
 

Typedefs

typedef enum efp_result(* efp_electron_density_field_fn) (size_t n_pt, const double *xyz, double *field, void *user_data)
 Callback function which is called by libefp to obtain electric field in the specified points. More...
 

Enumerations

enum  efp_result {
  EFP_RESULT_SUCCESS = 0, EFP_RESULT_FATAL,
  EFP_RESULT_NO_MEMORY, EFP_RESULT_FILE_NOT_FOUND,
  EFP_RESULT_SYNTAX_ERROR, EFP_RESULT_UNKNOWN_FRAGMENT,
  EFP_RESULT_POL_NOT_CONVERGED
}
 Result of an operation. More...
 
enum  efp_term {
  EFP_TERM_ELEC = 1 << 0, EFP_TERM_POL = 1 << 1,
  EFP_TERM_DISP = 1 << 2, EFP_TERM_XR = 1 << 3,
  EFP_TERM_CHTR = 1 << 4, EFP_TERM_AI_ELEC = 1 << 5,
  EFP_TERM_AI_POL = 1 << 6, EFP_TERM_AI_DISP = 1 << 7,
  EFP_TERM_AI_XR = 1 << 8, EFP_TERM_AI_CHTR = 1 << 9
}
 Flags to specify EFP energy terms. More...
 
enum  efp_disp_damp {
  EFP_DISP_DAMP_OVERLAP = 0, EFP_DISP_DAMP_TT,
  EFP_DISP_DAMP_OFF
}
 Fragment-fragment dispersion damping type. More...
 
enum  efp_elec_damp {
  EFP_ELEC_DAMP_SCREEN = 0, EFP_ELEC_DAMP_OVERLAP,
  EFP_ELEC_DAMP_OFF
}
 Fragment-fragment electrostatic damping type. More...
 
enum  efp_pol_damp { EFP_POL_DAMP_TT = 0, EFP_POL_DAMP_OFF }
 Fragment-fragment polarization damping type. More...
 
enum  efp_coord_type {
  EFP_COORD_TYPE_XYZABC = 0, EFP_COORD_TYPE_POINTS,
  EFP_COORD_TYPE_ROTMAT
}
 Describes the way fragment coordinates are specified. More...
 
enum  efp_pol_driver { EFP_POL_DRIVER_ITERATIVE = 0, EFP_POL_DRIVER_DIRECT }
 Driver used for solving polarization equations. More...
 

Functions

const char * efp_banner (void)
 Get a human readable banner string with information about the library. More...
 
struct efpefp_create (void)
 Create a new efp object. More...
 
void efp_opts_default (struct efp_opts *opts)
 Get default values of simulation options. More...
 
void efp_set_error_log (void(*cb)(const char *))
 Set the error log callback function. More...
 
enum efp_result efp_set_opts (struct efp *efp, const struct efp_opts *opts)
 Set computation options. More...
 
enum efp_result efp_get_opts (struct efp *efp, struct efp_opts *opts)
 Get currently set computation options. More...
 
enum efp_result efp_add_potential (struct efp *efp, const char *path)
 Add EFP potential from a file. More...
 
enum efp_result efp_add_fragment (struct efp *efp, const char *name)
 Add a new fragment to the EFP subsystem. More...
 
enum efp_result efp_prepare (struct efp *efp)
 Prepare the calculation. More...
 
enum efp_result efp_skip_fragments (struct efp *efp, size_t i, size_t j, int value)
 Skip interactions between the fragments. More...
 
enum efp_result efp_set_electron_density_field_fn (struct efp *efp, efp_electron_density_field_fn fn)
 Set the callback function which computes electric field from electrons in ab initio subsystem. More...
 
enum efp_result efp_set_electron_density_field_user_data (struct efp *efp, void *user_data)
 Set user data to be passed to efp_electron_density_field_fn. More...
 
enum efp_result efp_set_point_charges (struct efp *efp, size_t n_ptc, const double *ptc, const double *xyz)
 Setup arbitrary point charges interacting with EFP subsystem. More...
 
enum efp_result efp_get_point_charge_count (struct efp *efp, size_t *n_ptc)
 Get the number of currently set point charges. More...
 
enum efp_result efp_get_point_charge_values (struct efp *efp, double *ptc)
 Get values of currently set point charges. More...
 
enum efp_result efp_set_point_charge_values (struct efp *efp, const double *ptc)
 Set values of point charges. More...
 
enum efp_result efp_get_point_charge_coordinates (struct efp *efp, double *xyz)
 Get coordinates of currently set point charges. More...
 
enum efp_result efp_set_point_charge_coordinates (struct efp *efp, const double *xyz)
 Set coordinates of point charges. More...
 
enum efp_result efp_get_point_charge_gradient (struct efp *efp, double *grad)
 Get gradient on point charges from EFP subsystem. More...
 
enum efp_result efp_set_coordinates (struct efp *efp, enum efp_coord_type coord_type, const double *coord)
 Update positions and orientations of effective fragments. More...
 
enum efp_result efp_set_frag_coordinates (struct efp *efp, size_t frag_idx, enum efp_coord_type coord_type, const double *coord)
 Update position and orientation of the specified effective fragment. More...
 
enum efp_result efp_get_coordinates (struct efp *efp, double *xyzabc)
 Get center of mass positions and Euler angles of the effective fragments. More...
 
enum efp_result efp_get_frag_xyzabc (struct efp *efp, size_t frag_idx, double *xyzabc)
 Get center of mass position and Euler angles of a fragment. More...
 
enum efp_result efp_set_periodic_box (struct efp *efp, double x, double y, double z)
 Setup periodic box size. More...
 
enum efp_result efp_get_stress_tensor (struct efp *efp, double *stress)
 Get the stress tensor. More...
 
enum efp_result efp_get_ai_screen (struct efp *efp, size_t frag_idx, double *screen)
 Get the ab initio screening parameters. More...
 
enum efp_result efp_set_orbital_energies (struct efp *efp, size_t n_core, size_t n_act, size_t n_vir, const double *oe)
 Set ab initio orbital energies. More...
 
enum efp_result efp_set_dipole_integrals (struct efp *efp, size_t n_core, size_t n_act, size_t n_vir, const double *dipint)
 Set ab initio dipole integrals. More...
 
enum efp_result efp_get_wavefunction_dependent_energy (struct efp *efp, double *energy)
 Update wave function dependent energy terms. More...
 
enum efp_result efp_compute (struct efp *efp, int do_gradient)
 Perform the EFP computation. More...
 
enum efp_result efp_get_frag_charge (struct efp *efp, size_t frag_idx, double *charge)
 Get total charge of a fragment. More...
 
enum efp_result efp_get_frag_multiplicity (struct efp *efp, size_t frag_idx, int *mult)
 Get spin multiplicity of a fragment. More...
 
enum efp_result efp_get_frag_multipole_count (struct efp *efp, size_t frag_idx, size_t *n_mult)
 Get number of electrostatic multipole points for a particular fragment. More...
 
enum efp_result efp_get_multipole_count (struct efp *efp, size_t *n_mult)
 Get total number of multipoles from EFP electrostatics. More...
 
enum efp_result efp_get_multipole_coordinates (struct efp *efp, double *xyz)
 Get coordinates of electrostatics multipoles. More...
 
enum efp_result efp_get_multipole_values (struct efp *efp, double *mult)
 Get electrostatics multipoles from EFP fragments. More...
 
enum efp_result efp_get_induced_dipole_count (struct efp *efp, size_t *n_dip)
 Get the number of polarization induced dipoles. More...
 
enum efp_result efp_get_induced_dipole_coordinates (struct efp *efp, double *xyz)
 Get coordinates of induced dipoles. More...
 
enum efp_result efp_get_induced_dipole_values (struct efp *efp, double *dip)
 Get values of polarization induced dipoles. More...
 
enum efp_result efp_get_induced_dipole_conj_values (struct efp *efp, double *dip)
 Get values of polarization conjugated induced dipoles. More...
 
enum efp_result efp_get_lmo_count (struct efp *efp, size_t frag_idx, size_t *n_lmo)
 Get the number of LMOs in a fragment. More...
 
enum efp_result efp_get_lmo_coordinates (struct efp *efp, size_t frag_idx, double *xyz)
 Get coordinates of LMO centroids. More...
 
enum efp_result efp_get_xrfit (struct efp *efp, size_t frag_idx, double *xrfit)
 Get parameters of fitted exchange-repulsion. More...
 
enum efp_result efp_get_energy (struct efp *efp, struct efp_energy *energy)
 Get computed energy components. More...
 
enum efp_result efp_get_gradient (struct efp *efp, double *grad)
 Get computed EFP energy gradient. More...
 
enum efp_result efp_get_atomic_gradient (struct efp *efp, double *grad)
 Get computed EFP energy gradient on individual atoms. More...
 
enum efp_result efp_get_frag_count (struct efp *efp, size_t *n_frag)
 Get the number of fragments in this computation. More...
 
enum efp_result efp_get_frag_name (struct efp *efp, size_t frag_idx, size_t size, char *frag_name)
 Get the name of the specified effective fragment. More...
 
enum efp_result efp_get_frag_mass (struct efp *efp, size_t frag_idx, double *mass_out)
 Get total mass of a fragment. More...
 
enum efp_result efp_get_frag_inertia (struct efp *efp, size_t frag_idx, double *inertia_out)
 Get fragment principal moments of inertia. More...
 
enum efp_result efp_get_frag_atom_count (struct efp *efp, size_t frag_idx, size_t *n_atoms)
 Get the number of atoms in the specified fragment. More...
 
enum efp_result efp_get_frag_atoms (struct efp *efp, size_t frag_idx, size_t size, struct efp_atom *atoms)
 Get atoms comprising the specified fragment. More...
 
enum efp_result efp_get_electric_field (struct efp *efp, size_t frag_idx, const double *xyz, double *field)
 Get electric field for a point on a fragment. More...
 
void efp_torque_to_derivative (const double *euler, const double *torque, double *deriv)
 Convert rigid body torque to derivatives of energy by Euler angles. More...
 
void efp_shutdown (struct efp *efp)
 Release all resources used by this efp. More...
 
const char * efp_result_to_string (enum efp_result res)
 Convert efp_result to a human readable message. More...
 

Detailed Description

Public libefp interface.

A note on units: masses are in AMU, everything else is in atomic units.

Macro Definition Documentation

§ LIBEFP_VERSION_STRING

#define LIBEFP_VERSION_STRING   "1.4.2"

Version string.

Typedef Documentation

§ efp_electron_density_field_fn

typedef enum efp_result(* efp_electron_density_field_fn) (size_t n_pt, const double *xyz, double *field, void *user_data)

Callback function which is called by libefp to obtain electric field in the specified points.

This function is used to obtain the electric field from electrons in the ab initio part. This callback is called by libefp during polarization calculation. Libefp supplies the xyz array with coordinates of the points where the field should be computed.

Parameters
[in]n_ptNumber of points in xyz array.
[in]xyzCoordinates of points where electric field should be computed. The size of this array must be [3 * n_pt] elements.
[out]fieldComputed x y z components of electric field. The size of this array must be at least [3 * n_pt] elements.
[in]user_dataUser data which was specified during initialization.
Returns
The implemented function should return EFP_RESULT_FATAL on error and EFP_RESULT_SUCCESS if the calculation has succeeded.

Enumeration Type Documentation

§ efp_result

enum efp_result

Result of an operation.

Enumerator
EFP_RESULT_SUCCESS 

Operation was successful.

EFP_RESULT_FATAL 

Fatal error has occurred.

EFP_RESULT_NO_MEMORY 

Insufficient memory.

EFP_RESULT_FILE_NOT_FOUND 

File not found.

EFP_RESULT_SYNTAX_ERROR 

Syntax error.

EFP_RESULT_UNKNOWN_FRAGMENT 

Unknown EFP fragment.

EFP_RESULT_POL_NOT_CONVERGED 

Polarization SCF procedure did not converge.

§ efp_term

enum efp_term

Flags to specify EFP energy terms.

Enumerator
EFP_TERM_ELEC 

EFP/EFP electrostatics.

EFP_TERM_POL 

EFP/EFP polarization.

EFP_TERM_DISP 

EFP/EFP dispersion.

EFP_TERM_XR 

EFP/EFP exchange repulsion.

EFP_TERM_CHTR 

EFP/EFP charge transfer, reserved for future use.

EFP_TERM_AI_ELEC 

Ab initio/EFP electrostatics.

EFP_TERM_AI_POL 

Ab initio/EFP polarization.

EFP_TERM_AI_DISP 

Ab initio/EFP dispersion, reserved for future use.

EFP_TERM_AI_XR 

Ab initio/EFP exchange repulsion, reserved for future use.

EFP_TERM_AI_CHTR 

Ab initio/EFP charge transfer, reserved for future use.

§ efp_disp_damp

Fragment-fragment dispersion damping type.

Enumerator
EFP_DISP_DAMP_OVERLAP 

Overlap-based damping (default).

EFP_DISP_DAMP_TT 

Tang-Toennies damping.

EFP_DISP_DAMP_OFF 

No dispersion damping.

§ efp_elec_damp

Fragment-fragment electrostatic damping type.

Enumerator
EFP_ELEC_DAMP_SCREEN 

SCREEN-controlled damping (default).

EFP_ELEC_DAMP_OVERLAP 

Overlap-based damping.

EFP_ELEC_DAMP_OFF 

No electrostatic damping.

§ efp_pol_damp

Fragment-fragment polarization damping type.

Enumerator
EFP_POL_DAMP_TT 

Tang-Toennies like damping (default).

EFP_POL_DAMP_OFF 

No polarization damping.

§ efp_coord_type

Describes the way fragment coordinates are specified.

Enumerator
EFP_COORD_TYPE_XYZABC 

Coordinates of center of mass of a fragment and Euler angles.

EFP_COORD_TYPE_POINTS 

Coordinates of three points belonging to a fragment.

EFP_COORD_TYPE_ROTMAT 

Coordinates of fragment center of mass and its rotation matrix.

§ efp_pol_driver

Driver used for solving polarization equations.

Enumerator
EFP_POL_DRIVER_ITERATIVE 

Iterative solution of polarization equations.

EFP_POL_DRIVER_DIRECT 

Direct solution of polarization equations.

Function Documentation

§ efp_banner()

const char* efp_banner ( void  )

Get a human readable banner string with information about the library.

Returns
Banner string, zero-terminated.

§ efp_create()

struct efp* efp_create ( void  )

Create a new efp object.

Returns
A new efp object or NULL on error.

§ efp_opts_default()

void efp_opts_default ( struct efp_opts opts)

Get default values of simulation options.

Parameters
[out]optsStructure to store the defaults. See efp_opts.

§ efp_set_error_log()

void efp_set_error_log ( void(*)(const char *)  cb)

Set the error log callback function.

The callback function can be used to print verbose diagnostic messages from libefp. It can be as simple as the following:

void log_cb(const char *msg)
{
printf("%s\n", msg);
}
Parameters
[in]cbError log callback function or NULL if none.

§ efp_set_opts()

enum efp_result efp_set_opts ( struct efp efp,
const struct efp_opts opts 
)

Set computation options.

Parameters
[in]efpThe efp structure.
[in]optsNew options for EFP computation. See efp_opts.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_opts()

enum efp_result efp_get_opts ( struct efp efp,
struct efp_opts opts 
)

Get currently set computation options.

Parameters
[in]efpThe efp structure.
[out]optsCurrent options for EFP computation. See efp_opts.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_add_potential()

enum efp_result efp_add_potential ( struct efp efp,
const char *  path 
)

Add EFP potential from a file.

Parameters
[in]efpThe efp structure.
[in]pathPath to the EFP potential file, zero terminated string.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_add_fragment()

enum efp_result efp_add_fragment ( struct efp efp,
const char *  name 
)

Add a new fragment to the EFP subsystem.

Parameters
[in]efpThe efp structure.
[in]nameFragment name, zero terminated string.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_prepare()

enum efp_result efp_prepare ( struct efp efp)

Prepare the calculation.

New fragments must NOT be added after a call to this function.

Parameters
[in]efpThe efp structure.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_skip_fragments()

enum efp_result efp_skip_fragments ( struct efp efp,
size_t  i,
size_t  j,
int  value 
)

Skip interactions between the fragments.

Parameters
[in]efpThe efp structure.
[in]iIndex of the first fragment.
[in]jIndex of the second fragment.
[in]valueSpecifies whether to skip i-j interactions (true/false).
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_set_electron_density_field_fn()

enum efp_result efp_set_electron_density_field_fn ( struct efp efp,
efp_electron_density_field_fn  fn 
)

Set the callback function which computes electric field from electrons in ab initio subsystem.

Parameters
[in]efpThe efp structure.
[in]fnThe callback function. See efp_electron_density_field_fn.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_set_electron_density_field_user_data()

enum efp_result efp_set_electron_density_field_user_data ( struct efp efp,
void *  user_data 
)

Set user data to be passed to efp_electron_density_field_fn.

Parameters
[in]efpThe efp structure.
[in]user_dataUser data which will be passed as a last parameter to efp_electron_density_field_fn.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_set_point_charges()

enum efp_result efp_set_point_charges ( struct efp efp,
size_t  n_ptc,
const double *  ptc,
const double *  xyz 
)

Setup arbitrary point charges interacting with EFP subsystem.

This can be used to compute contributions from ab initio nuclei.

Parameters
[in]efpThe efp structure.
[in]n_ptcNumber of point charges.
[in]ptcArray of n_ptc elements with charge values.
[in]xyzArray of [3 * n_ptc] elements with x y z coordinates of charge positions.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_point_charge_count()

enum efp_result efp_get_point_charge_count ( struct efp efp,
size_t *  n_ptc 
)

Get the number of currently set point charges.

Parameters
[in]efpThe efp structure.
[out]n_ptcNumber of point charges.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_point_charge_values()

enum efp_result efp_get_point_charge_values ( struct efp efp,
double *  ptc 
)

Get values of currently set point charges.

Parameters
[in]efpThe efp structure.
[out]ptcArray of n_ptc elements where charges will be stored.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_set_point_charge_values()

enum efp_result efp_set_point_charge_values ( struct efp efp,
const double *  ptc 
)

Set values of point charges.

Parameters
[in]efpThe efp structure.
[in]ptcArray of n_ptc elements with charge values.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_point_charge_coordinates()

enum efp_result efp_get_point_charge_coordinates ( struct efp efp,
double *  xyz 
)

Get coordinates of currently set point charges.

Parameters
[in]efpThe efp structure.
[out]xyzArray where x y z coordinates of point charges will be stored. The size of the array must be at least [3 * n] elements, where n is the total number of point charges.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_set_point_charge_coordinates()

enum efp_result efp_set_point_charge_coordinates ( struct efp efp,
const double *  xyz 
)

Set coordinates of point charges.

Parameters
[in]efpThe efp structure.
[in]xyzArray with x y z coordinates of point charges. The size of the array must be at least [3 * n] elements, where n is the total number of point charges.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_point_charge_gradient()

enum efp_result efp_get_point_charge_gradient ( struct efp efp,
double *  grad 
)

Get gradient on point charges from EFP subsystem.

Parameters
[in]efpThe efp structure.
[out]gradFor each point charge x y z components of energy gradient are stored. The size of this array must be at least [3 * n] elements, where n is the total number of point charges.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_set_coordinates()

enum efp_result efp_set_coordinates ( struct efp efp,
enum efp_coord_type  coord_type,
const double *  coord 
)

Update positions and orientations of effective fragments.

Parameters
[in]efpThe efp structure.
[in]coord_typeSpecifies the type of coordinates in the coord array (see efp_coord_type).
[in]coordArray of fragment coordinates.

If coord_type is EFP_COORD_TYPE_XYZABC then for each fragment the coord array should contain x y z components of the center of mass position and three Euler rotation angles representing orientation of a fragment. The size of the coord array must be at least [6 * n] elements, where n is the number of fragments.

If coord_type is EFP_COORD_TYPE_POINTS then for each fragment the coord array should contain the coordinates of 3 points in space. For each fragment point 1 and first atom of fragment are made to coincide. The vector connecting points 1 and 2 is aligned with the corresponding vector connecting fragment atoms. The plane defined by points 1, 2, and 3 is made to coincide with the corresponding fragment plane. The size of the coord array must be at least [9 * n] elements, where n is the number of fragments.

If coord_type is EFP_COORD_TYPE_ROTMAT then for each fragment the coord array should contain x y z components of the center of mass position and nine elements of the rotation matrix representing orientation of a fragment. The size of the coord array must be at least [12 * n] elements, where n is the number of fragments.

Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_set_frag_coordinates()

enum efp_result efp_set_frag_coordinates ( struct efp efp,
size_t  frag_idx,
enum efp_coord_type  coord_type,
const double *  coord 
)

Update position and orientation of the specified effective fragment.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[in]coord_typeSpecifies the type of coordinates in the coord array (see efp_coord_type).
[in]coordArray of coordinates specifying fragment position and orientation.

If coord_type is EFP_COORD_TYPE_XYZABC then the coord array should contain x y z components of the center of mass position and three Euler rotation angles representing orientation of a fragment. The coord array must contain a total of 6 elements.

If coord_type is EFP_COORD_TYPE_POINTS then the coord array should contain the coordinates of 3 points in space. Point 1 and first atom of fragment are made to coincide. The vector connecting points 1 and 2 is aligned with the corresponding vector connecting fragment atoms. The plane defined by points 1, 2, and 3 is made to coincide with the corresponding fragment plane. The coord array must contain a total of 9 elements.

If coord_type is EFP_COORD_TYPE_ROTMAT then the coord array should contain x y z components of the center of mass position and nine elements of the rotation matrix representing orientation of a fragment. The coord array must contain a total of 12 elements.

Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_coordinates()

enum efp_result efp_get_coordinates ( struct efp efp,
double *  xyzabc 
)

Get center of mass positions and Euler angles of the effective fragments.

Parameters
[in]efpThe efp structure.
[out]xyzabcUpon return the coordinates of the center of mass and Euler rotation angles for each fragment will be written to this array. The size of the xyzabc array must be at least [6 * n] elements, where n is the total number of fragments.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_frag_xyzabc()

enum efp_result efp_get_frag_xyzabc ( struct efp efp,
size_t  frag_idx,
double *  xyzabc 
)

Get center of mass position and Euler angles of a fragment.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[out]xyzabcUpon return the coordinates of the center of mass and Euler rotation angles for the fragment will be written to this array. The size of the xyzabc array must be at least [6] elements.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_set_periodic_box()

enum efp_result efp_set_periodic_box ( struct efp efp,
double  x,
double  y,
double  z 
)

Setup periodic box size.

Parameters
[in]efpThe efp structure.
[in]xBox size in x dimension.
[in]yBox size in y dimension.
[in]zBox size in z dimension.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_stress_tensor()

enum efp_result efp_get_stress_tensor ( struct efp efp,
double *  stress 
)

Get the stress tensor.

Parameters
[in]efpThe efp structure.
[out]stressArray of 9 elements where the stress tensor will be stored.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_ai_screen()

enum efp_result efp_get_ai_screen ( struct efp efp,
size_t  frag_idx,
double *  screen 
)

Get the ab initio screening parameters.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[out]screenArray of N elements where screening parameters will be stored. N is the total number of multipole points.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_set_orbital_energies()

enum efp_result efp_set_orbital_energies ( struct efp efp,
size_t  n_core,
size_t  n_act,
size_t  n_vir,
const double *  oe 
)

Set ab initio orbital energies.

Parameters
[in]efpThe efp structure.
[in]n_coreNumber of core orbitals.
[in]n_actNumber of active orbitals.
[in]n_virNumber of virtual orbitals.
[in]oeArray of orbital energies. The size of this array must be (n_core + n_act + n_vir) elements.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_set_dipole_integrals()

enum efp_result efp_set_dipole_integrals ( struct efp efp,
size_t  n_core,
size_t  n_act,
size_t  n_vir,
const double *  dipint 
)

Set ab initio dipole integrals.

Parameters
[in]efpThe efp structure.
[in]n_coreNumber of core orbitals.
[in]n_actNumber of active orbitals.
[in]n_virNumber of virtual orbitals.
[in]dipintDipole integral matrices for x,y,z axes. The total size of this array must be 3 * (n_core + n_act + n_vir) ^ 2 elements.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_wavefunction_dependent_energy()

enum efp_result efp_get_wavefunction_dependent_energy ( struct efp efp,
double *  energy 
)

Update wave function dependent energy terms.

This function must be called during ab initio SCF.

Parameters
[in]efpThe efp structure.
[out]energyWave function dependent EFP energy.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_compute()

enum efp_result efp_compute ( struct efp efp,
int  do_gradient 
)

Perform the EFP computation.

Parameters
[in]efpThe efp structure.
[in]do_gradientIf nonzero value is specified in addition to energy compute the gradient.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_frag_charge()

enum efp_result efp_get_frag_charge ( struct efp efp,
size_t  frag_idx,
double *  charge 
)

Get total charge of a fragment.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[out]chargeTotal charge of a fragment.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_frag_multiplicity()

enum efp_result efp_get_frag_multiplicity ( struct efp efp,
size_t  frag_idx,
int *  mult 
)

Get spin multiplicity of a fragment.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[out]multSpin multiplicity of a fragment.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_frag_multipole_count()

enum efp_result efp_get_frag_multipole_count ( struct efp efp,
size_t  frag_idx,
size_t *  n_mult 
)

Get number of electrostatic multipole points for a particular fragment.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[out]n_multNumber of electrostatic multipole points.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_multipole_count()

enum efp_result efp_get_multipole_count ( struct efp efp,
size_t *  n_mult 
)

Get total number of multipoles from EFP electrostatics.

Parameters
[in]efpThe efp structure.
[out]n_multNumber of electrostatics multipoles.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_multipole_coordinates()

enum efp_result efp_get_multipole_coordinates ( struct efp efp,
double *  xyz 
)

Get coordinates of electrostatics multipoles.

Parameters
[in]efpThe efp structure.
[out]xyzArray where coordinates of EFP electrostatics multipoles will be stored. Size of the xyz array must be at least [3 * n_mult] elements, where n_mult is the value returned by the efp_get_multipole_count function.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_multipole_values()

enum efp_result efp_get_multipole_values ( struct efp efp,
double *  mult 
)

Get electrostatics multipoles from EFP fragments.

Parameters
[in]efpThe efp structure.
[out]multArray where charges, dipoles, quadrupoles, and octupoles for each point will be stored.

The size of the mult array must be at least [(1 + 3 + 6 + 10) * n_mult] elements (charges + dipoles + quadrupoles + octupoles), where n_mult is the value returned by the efp_get_multipole_count function.

Quadrupoles are stored in the following order: xx, yy, zz, xy, xz, yz

Octupoles are stored in the following order: xxx, yyy, zzz, xxy, xxz, xyy, yyz, xzz, yzz, xyz

Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_induced_dipole_count()

enum efp_result efp_get_induced_dipole_count ( struct efp efp,
size_t *  n_dip 
)

Get the number of polarization induced dipoles.

Parameters
[in]efpThe efp structure.
[out]n_dipNumber of polarization induced dipoles.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_induced_dipole_coordinates()

enum efp_result efp_get_induced_dipole_coordinates ( struct efp efp,
double *  xyz 
)

Get coordinates of induced dipoles.

Parameters
[in]efpThe efp structure.
[out]xyzArray where the coordinates of polarizable points will be stored. The size of the xyz array must be at least [3 * n_dip] elements.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_induced_dipole_values()

enum efp_result efp_get_induced_dipole_values ( struct efp efp,
double *  dip 
)

Get values of polarization induced dipoles.

Parameters
[in]efpThe efp structure.
[out]dipArray where induced dipoles will be stored. The size of the array must be at least [3 * n_dip] elements.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_induced_dipole_conj_values()

enum efp_result efp_get_induced_dipole_conj_values ( struct efp efp,
double *  dip 
)

Get values of polarization conjugated induced dipoles.

Parameters
[in]efpThe efp structure.
[out]dipArray where induced dipoles will be stored. The size of the array must be at least [3 * n_dip] elements.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_lmo_count()

enum efp_result efp_get_lmo_count ( struct efp efp,
size_t  frag_idx,
size_t *  n_lmo 
)

Get the number of LMOs in a fragment.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[out]n_lmoNumber of LMOs.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_lmo_coordinates()

enum efp_result efp_get_lmo_coordinates ( struct efp efp,
size_t  frag_idx,
double *  xyz 
)

Get coordinates of LMO centroids.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[out]xyzArray where the coordinates of LMO centroids will be stored. The size of the xyz array must be at least [3 * n_lmo] elements.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_xrfit()

enum efp_result efp_get_xrfit ( struct efp efp,
size_t  frag_idx,
double *  xrfit 
)

Get parameters of fitted exchange-repulsion.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[out]xrfitArray where the parameters will be stored. The size of the xrfit array must be at least [4 * n_lmo] elements.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_energy()

enum efp_result efp_get_energy ( struct efp efp,
struct efp_energy energy 
)

Get computed energy components.

Parameters
[in]efpThe efp structure.
[out]energyComputed EFP energy components (see efp_energy).
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_gradient()

enum efp_result efp_get_gradient ( struct efp efp,
double *  grad 
)

Get computed EFP energy gradient.

Parameters
[in]efpThe efp structure.
[out]gradFor each fragment x y z components of negative force and torque will be written to this array. The size of this array must be at least [6 * n] elements, where n is the total number of fragments.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_atomic_gradient()

enum efp_result efp_get_atomic_gradient ( struct efp efp,
double *  grad 
)

Get computed EFP energy gradient on individual atoms.

Parameters
[in]efpThe efp structure.
[out]gradFor each atom, x y z components of negative force will be added to this array. The size of this array must be at least [3 * n] elements, where n is the total number of atoms from all fragments. An atom is a point with non-zero mass inside a fragment. Any initial gradient from this array will be gathered on fragments at the beginning and then redistributed back to the atoms. This can be used to account for other interactions, e.g., bonded forces from MM forcefield.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_frag_count()

enum efp_result efp_get_frag_count ( struct efp efp,
size_t *  n_frag 
)

Get the number of fragments in this computation.

Parameters
[in]efpThe efp structure.
[out]n_fragTotal number of fragments in this simulation.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_frag_name()

enum efp_result efp_get_frag_name ( struct efp efp,
size_t  frag_idx,
size_t  size,
char *  frag_name 
)

Get the name of the specified effective fragment.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[in]sizeSize of a frag_name buffer.
[out]frag_nameA buffer where name of the fragment will be stored.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_frag_mass()

enum efp_result efp_get_frag_mass ( struct efp efp,
size_t  frag_idx,
double *  mass_out 
)

Get total mass of a fragment.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. This must be a value between zero and the total number of fragments minus one.
[out]mass_outOutput mass value.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_frag_inertia()

enum efp_result efp_get_frag_inertia ( struct efp efp,
size_t  frag_idx,
double *  inertia_out 
)

Get fragment principal moments of inertia.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[out]inertia_outArray of 3 elements where principal moments of inertia of a fragment will be stored.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_frag_atom_count()

enum efp_result efp_get_frag_atom_count ( struct efp efp,
size_t  frag_idx,
size_t *  n_atoms 
)

Get the number of atoms in the specified fragment.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[out]n_atomsTotal number of atoms in the fragment.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_frag_atoms()

enum efp_result efp_get_frag_atoms ( struct efp efp,
size_t  frag_idx,
size_t  size,
struct efp_atom atoms 
)

Get atoms comprising the specified fragment.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[in]sizeSize of the atoms array. Must be greater than or equal to the size returned by the efp_get_frag_atom_count function.
[out]atomsArray where atom information will be stored.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_get_electric_field()

enum efp_result efp_get_electric_field ( struct efp efp,
size_t  frag_idx,
const double *  xyz,
double *  field 
)

Get electric field for a point on a fragment.

Parameters
[in]efpThe efp structure.
[in]frag_idxIndex of a fragment. Must be a value between zero and the total number of fragments minus one.
[in]xyzCoordinates of a point for which electric field should be computed.
[out]fieldElectric field x y z components in atomic units.
Returns
EFP_RESULT_SUCCESS on success or error code otherwise.

§ efp_torque_to_derivative()

void efp_torque_to_derivative ( const double *  euler,
const double *  torque,
double *  deriv 
)

Convert rigid body torque to derivatives of energy by Euler angles.

Parameters
[in]eulerArray of 3 elements containing the values of Euler angles for the current orientation of the rigid body.
[in]torqueArray of 3 elements containing torque components.
[out]derivArray of 3 elements where derivatives of energy by Euler angles will be stored. This can point to the same memory location as the torque argument.

§ efp_shutdown()

void efp_shutdown ( struct efp efp)

Release all resources used by this efp.

Parameters
[in]efpThe efp structure to be released.

§ efp_result_to_string()

const char* efp_result_to_string ( enum efp_result  res)

Convert efp_result to a human readable message.

Parameters
resResult value to be converted to string.
Returns
Human readable string with the description of the result, zero-terminated.