Interfacing a QM program and PCMSolver¶
For the impatients: tl;dr¶
In these examples, we want to show how every function in the API works. If your program is written in Fortran, head over to Interfacing with a Fortran host If your program is written in C/C++, head over to Interfacing with a C host
How PCMSolver handles potentials and charges: surface functions¶
Electrostatic potential vectors and the corresponding apparent surface charge vectors are handled internally as surface functions. The actual values are stored into Eigen vectors and saved into a map. The mapping is between the name of the surface function, given by the programmer writing the interface to the library, and the vector holding the values.
What you should care about: API functions¶
These are the contents of the pcmsolver.h
file defining
the public API of the PCMSolver library. The Fortran bindings
for the API are in the pcmsolver.F90
file.
The indexing of symmetry operations and their mapping to a bitstring
is explained in the following Table. This is important when passing
symmetry information to the pcmsolver_new()
function.
Index | zyx | Generator | Parity |
---|---|---|---|
0 | 000 | E | 1.0 |
1 | 001 | Oyz | -1.0 |
2 | 010 | Oxz | -1.0 |
3 | 011 | C2z | 1.0 |
4 | 100 | Oxy | -1.0 |
5 | 101 | C2y | 1.0 |
6 | 110 | C2x | 1.0 |
7 | 111 | i | -1.0 |
Typedefs
-
typedef bool
pcmsolver_bool_t
¶
-
typedef
pcmsolver_context_t
¶ Workaround to have pcmsolver_context_s available to C
Enums
Functions
-
void
host_writer
(const char *message, int message_length)¶ Flushes module output to host program.
- Parameters
message
-contents of the module output
message_length
-length of the passed message This function must be defined by the host program
-
pcmsolver_context_t *
pcmsolver_new
(pcmsolver_reader_t input_reading, int nr_nuclei, double charges[], double coordinates[], int symmetry_info[], struct PCMInput *host_input)¶ Creates a new PCM context object.
The molecular point group information is passed as an array of 4 integers: number of generators, first, second and third generator respectively. Generators map to integers as in table :ref:
symmetry-ops
- Parameters
input_reading
-input processing strategy
nr_nuclei
-number of atoms in the molecule
charges
-atomic charges
coordinates
-atomic coordinates
symmetry_info
-molecular point group information
host_input
-input to the module, as read by the host
-
void
pcmsolver_delete
(pcmsolver_context_t *context)¶ Deletes a PCM context object.
- Parameters
context
-the PCM context object to be deleted
-
pcmsolver_bool_t
pcmsolver_is_compatible_library
(void)¶ Whether the library is compatible with the header file Checks that the compiled library and header file version match. Host should abort when that is not the case.
- Warning
- This function should be called before instantiating any PCM context objects.
-
void
pcmsolver_print
(pcmsolver_context_t *context)¶ Prints citation and set up information.
- Parameters
context
-the PCM context object
-
int
pcmsolver_get_cavity_size
(pcmsolver_context_t *context)¶ Getter for the number of finite elements composing the molecular cavity.
- Return
- the size of the cavity
- Parameters
context
-the PCM context object
-
int
pcmsolver_get_irreducible_cavity_size
(pcmsolver_context_t *context)¶ Getter for the number of irreducible finite elements composing the molecular cavity.
- Return
- the number of irreducible finite elements
- Parameters
context
-the PCM context object
-
void
pcmsolver_get_centers
(pcmsolver_context_t *context, double centers[])¶ Getter for the centers of the finite elements composing the molecular cavity.
- Parameters
context
-the PCM context object
centers
-array holding the coordinates of the finite elements centers
-
void
pcmsolver_get_center
(pcmsolver_context_t *context, int its, double center[])¶ Getter for the center of the i-th finite element.
- Parameters
context
-the PCM context object
its
-index of the finite element
center
-array holding the coordinates of the finite element center
-
void
pcmsolver_get_areas
(pcmsolver_context_t *context, double areas[])¶ Getter for the areas/weights of the finite elements.
- Parameters
context
-the PCM context object
areas
-array holding the weights/areas of the finite elements
-
void
pcmsolver_compute_asc
(pcmsolver_context_t *context, const char *mep_name, const char *asc_name, int irrep)¶ Computes ASC given a MEP and the desired irreducible representation.
- Parameters
context
-the PCM context object
mep_name
-label of the MEP surface function
asc_name
-label of the ASC surface function
irrep
-index of the desired irreducible representation The module uses the surface function concept to handle potentials and charges. Given labels for each, this function retrieves the MEP and computes the corresponding ASC.
-
void
pcmsolver_compute_response_asc
(pcmsolver_context_t *context, const char *mep_name, const char *asc_name, int irrep)¶ Computes response ASC given a MEP and the desired irreducible representation.
- Parameters
context
-the PCM context object
mep_name
-label of the MEP surface function
asc_name
-label of the ASC surface function
irrep
-index of the desired irreducible representation If
Nonequilibrium = True
in the input, calculates a response ASC using the dynamic permittivity. Falls back to the solver with static permittivity otherwise.
-
double
pcmsolver_compute_polarization_energy
(pcmsolver_context_t *context, const char *mep_name, const char *asc_name)¶ Computes the polarization energy.
- Return
- the polarization energy This function calculates the dot product of the given MEP and ASC vectors.
- Parameters
context
-the PCM context object
mep_name
-label of the MEP surface function
asc_name
-label of the ASC surface function
-
void
pcmsolver_get_surface_function
(pcmsolver_context_t *context, int size, double values[], const char *name)¶ Retrieves data wrapped in a given surface function.
- Parameters
context
-the PCM context object
size
-the size of the surface function
values
-the values wrapped in the surface function
name
-label of the surface function
-
void
pcmsolver_set_surface_function
(pcmsolver_context_t *context, int size, double values[], const char *name)¶ Sets a surface function given data and label.
- Parameters
context
-the PCM context object
size
-the size of the surface function
values
-the values to be wrapped in the surface function
name
-label of the surface function
-
void
pcmsolver_save_surface_functions
(pcmsolver_context_t *context)¶ Dumps all currently saved surface functions to NumPy arrays in .npy files.
- Parameters
context
-the PCM context object
-
void
pcmsolver_save_surface_function
(pcmsolver_context_t *context, const char *name)¶ Dumps a surface function to NumPy array in .npy file.
- Parameters
context
-the PCM context object
name
-label of the surface function
-
void
pcmsolver_load_surface_function
(pcmsolver_context_t *context, const char *name)¶ Loads a surface function from a .npy file.
- Parameters
context
-the PCM context object
name
-label of the surface function
-
void
pcmsolver_write_timings
(pcmsolver_context_t *context)¶ Writes timing results for the API.
- Parameters
context
-the PCM context object
Host input forwarding¶
-
struct
PCMInput
¶ Data structure for host-API input communication.
Forward-declare PCMInput input wrapping struct
Public Members
-
char
cavity_type
[8]¶ Type of cavity requested.
-
int
patch_level
¶ Wavelet cavity mesh patch level.
-
double
coarsity
¶ Wavelet cavity mesh coarsity.
-
double
area
¶ Average tesserae area.
-
char
radii_set
[8]¶ The built-in radii set to be used.
-
double
min_distance
¶ Minimal distance between sampling points.
-
int
der_order
¶ Derivative order for the switching function.
-
pcmsolver_bool_t
scaling
¶ Whether to scale or not the atomic radii.
-
char
restart_name
[20]¶ Name of the .npz file for GePol cavity restart.
-
double
min_radius
¶ Minimal radius for the added spheres.
-
char
solver_type
[7]¶ Type of solver requested.
-
double
correction
¶ Correction in the CPCM apparent surface charge scaling factor.
-
char
solvent
[16]¶ Name of the solvent.
-
double
probe_radius
¶ Radius of the spherical probe mimicking the solvent.
-
char
equation_type
[11]¶ Type of the integral equation to be used.
-
char
inside_type
[7]¶ Type of Green’s function requested inside the cavity.
-
double
outside_epsilon
¶ Value of the static permittivity outside the cavity.
-
char
outside_type
[22]¶ Type of Green’s function requested outside the cavity.
-
char
Internal details of the API¶
Warning
doxygenclass: Cannot find class “Meddle” in doxygen xml output for project “PCMSolver” from directory: xml