# 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.

Symmetry operations indexing within the module
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

Defines

PCMSolver_EXPORT

PCMSolver, an API for the Polarizable Continuum Model Copyright (C) 2017 Roberto Di Remigio, Luca Frediani and collaborators.

This file is part of PCMSolver.

PCMSolver 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.

PCMSolver 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 PCMSolver. If not, see http://www.gnu.org/licenses/.

For information on the complete list of contributors to the PCMSolver API, see: http://pcmsolver.readthedocs.io/

pcmsolver_bool_t_DEFINED

Typedefs

typedef bool pcmsolver_bool_t
typedef pcmsolver_context_t

Workaround to have pcmsolver_context_t available to C

typedef HostWriter

Flushes module output to host program

Parameters
• message: contents of the module output

Enums

enum pcmsolver_reader_t

Input processing strategies.

Values:

PCMSOLVER_READER_OWN

Module reads input on its own

PCMSOLVER_READER_HOST

Functions

pcmsolver_context_t *pcmsolver_new(pcmsolver_reader_t input_reading, int nr_nuclei, double charges[], double coordinates[], int symmetry_info[], struct PCMInput *host_input, HostWriter writer)

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

double pcmsolver_get_asc_dipole(pcmsolver_context_t *context, const char *asc_name, double dipole[])

Getter for the ASC dipole.

Return
the ASC dipole, i.e. { ^2}
Parameters
• context: the PCM context object
• asc_name: label of the ASC surface function
• dipole: the Cartesian components of the ASC dipole moment

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_print_surface_function(pcmsolver_context_t *context, const char *name)

Prints surface function contents to host output.

Parameters
• context: the PCM context object
• 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

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.

## Internal details of the API¶

Warning

doxygenclass: Cannot find class “Meddle” in doxygen xml output for project “PCMSolver” from directory: xml