Input description¶
PCMSolver needs a number of input parameters at runtime. The API provides two ways of providing them:
- by means of an additional input file, parsed by the
pcmsolver.py
script; - by means of a special section in the host program input.
Method 1 is more flexible: all parameters that can be modified by the user are available. The host program needs only copy the additional input file to the scratch directory before execution. Method 2 just gives access to the core parameters.
In this page, input style and input parameters available in Method 1 will be documented.
Input style¶
The input for PCMSolver is parsed through the Getkw library written by Jonas Juselius
and is organized in sections and keywords. Input reading is
case-insensitive. An example input structure is shown below, there are also
some working examples in the directory examples
. A general input
parameter has the following form (Keyword = [Data type]):
Units = [String]
CODATA = [Integer]
Cavity {
Type = [String]
NpzFile = [String]
Area = [Double]
Scaling = [Bool]
RadiiSet = [String]
MinRadius = [Double]
Mode = [String]
Atoms = [Array of Integers]
Radii = [Array of Doubles]
Spheres = [Array of Doubles]
}
Medium {
Solvent = [String]
SolverType = [String]
MatrixSymm = [Bool]
Correction = [Double]
ProbeRadius = [Double]
Green<GreenTag> {
Type = [String]
Der = [String]
Eps = [Double]
EpsDyn = [Double]
Eps1 = [Double]
EpsDyn1 = [Double]
Eps2 = [Double]
EpsDyn2 = [Double]
Center = [Double]
Width = [Double]
InterfaceOrigin = [Array of Doubles]
MaxL = [Integer]
}
}
Array-valued keywords will expect the array to be given in comma-separated format and enclosed in square brackets. The purpose of tags is to distinguish between cases in which multiple instances of the same kind of object can be managed by the program. There exist only certain legal tagnames and these are determined in the C++ code. Be aware that the input parsing script does not check the correctness of tags.
Input parameters¶
Available sections:
- top section: sets up parameters affecting the module globally;
- Cavity: sets up all information needed to form the cavity and discretize its surface;
- Medium: sets up the solver to be used and the properties of the medium, i.e. the Green’s functions inside and outside the cavity;
- Green, subsection of medium. Sets up the Green’s function inside and outside the cavity.
Warning
Work in Progress!!
Top section keywords¶
- Units
Units of measure used in the input file. If Angstrom is given, all relevant input parameters are first converted in au and subsequently parsed.
- Type: string
- Valid values: AU | Angstrom
- Default: No Default
- CODATA
Set of fundamental physical constants to be used in the module.
- Type: integer
- Valid values: 2010 | 2006 | 2002 | 1998
- Default: 2010
Cavity section keywords¶
- Type
The type of the cavity. Completely specifies type of molecular surface and its discretization. Only one type is allowed. Restart cavity will read the file specified by NpzFile keyword and create a GePol cavity from that.
- Type: string
- Valid values: GePol | Restart
- Default: none
- NpzFile
The name of the
.npz
file to be used for the GePol cavity restart.- Type: string
- Default: empty string
- Area
Average area (weight) of the surface partition for the GePol (TsLess) cavity.
- Type: double
- Valid values: \(d \geq 0.01\,\text{a.u.}^2\)
- Valid for: GePol cavity
- Default value: \(0.3\,\text{a.u.}^2\)
- Scaling
If true, the radii for the spheres will be scaled by 1.2. For finer control on the scaling factor for each sphere, select explicit creation mode.
- Type: bool
- Valid for: all cavities except Restart
- Default value: True
- RadiiSet
Select set of atomic radii to be used. Currently Bondi-Mantina [Bondi1964][Mantina2009] and UFF [Rappe1992] sets available.
- Type: string
- Valid values: Bondi | UFF
- Valid for: all cavities except Restart
- Default value: Bondi
- MinRadius
Minimal radius for additional spheres not centered on atoms. An arbitrarily big value is equivalent to switching off the use of added spheres, which is the default.
- Type: double
- Valid values: \(d \geq 0.4\,\text{a.u.}\)
- Valid for: GePol cavity
- Default value: \(100.0\,\text{a.u.}\)
- Mode
How to create the list of spheres for the generation of the molecular surface:
- in Implicit mode, the atomic coordinates and charges will be obtained from the QM host program. Spheres will be centered on the atoms and the atomic radii, as specified in one the built-in sets, will be used. Scaling by 1.2 will be applied according to the keyword Scaling;
- in Atoms mode, the atomic coordinates and charges will be obtained from the QM host program. For the atoms specified by the array given in keyword Atoms, the built-in radii will be substituted by the radii provided in the keyword Radii. Scaling by 1.2 will be applied according to the keyword Scaling;
- in Explicit mode, both centers and radii of the spheres are to be specified in the keyword Spheres. The user has full control over the generation of the list of spheres. Scaling by 1.2 is not applied, regardless of the value of the Scaling keyword.
- Type: string
- Valid values: Implicit | Atoms | Explicit
- Valid for: all cavities except Restart
- Default value: Implicit
- Atoms
Array of atoms whose radius has to be substituted by a custom value.
- Type: array of integers
- Valid for: all cavities except Restart
- Radii
Array of radii replacing the built-in values for the selected atoms.
- Type: array of doubles
- Valid for: all cavities except Restart
- Spheres
Array of coordinates and centers for construction of the list of spheres in explicit mode. Format is \([\ldots, x_i, y_i, z_i, R_i, \ldots]\)
- Type: array of doubles
- Valid for: all cavities except Restart
Medium section keywords¶
- Solver
Type of solver to be used. All solvers are based on the Integral Equation Formulation of the Polarizable Continuum Model [Cances1998]
- IEFPCM. Collocation solver for a general dielectric medium
- CPCM. Collocation solver for a conductor-like approximation to the dielectric medium
- Type: string
- Valid values: IEFPCM | CPCM
- Default value: IEFPCM
- Nonequilibrium
Initializes an additional solver using the dynamic permittivity. To be used in response calculations.
- Type: bool
- Valid for: all solvers
- Default value: False
- Solvent
Specification of the dielectric medium outside the cavity. This keyword must always be given a value. If the solvent name given is different from Explicit any other settings in the Green’s function section will be overridden by the built-in values for the solvent specified. See Table Available solvents for details.
Solvent = Explicit
, triggers parsing of the Green’s function sections.Type: string
Valid values:
- Water , H2O;
- Methanol , CH3OH;
- Ethanol , CH3CH2OH;
- Chloroform , CHCL3;
- Methylenechloride , CH2CL2;
- 1,2-Dichloroethane , C2H4CL2;
- Carbon Tetrachloride, CCL4;
- Benzene , C6H6;
- Toluene , C6H5CH3;
- Chlorobenzene , C6H5CL;
- Nitromethane , CH3NO2;
- N-heptane , C7H16;
- Cyclohexane , C6H12;
- Aniline , C6H5NH2;
- Acetone , C2H6CO;
- Tetrahydrofurane , THF;
- Dimethylsulfoxide , DMSO;
- Acetonitrile , CH3CN;
- Explicit.
- MatrixSymm
If True, the PCM matrix obtained by the IEFPCM collocation solver is symmetrized \(\mathbf{K} := \frac{\mathbf{K} + \mathbf{K}^\dagger}{2}\)
- Type: bool
- Valid for: IEFPCM solver
- Default: True
- Correction
Correction, \(k\) for the apparent surface charge scaling factor in the CPCM solver \(f(\varepsilon) = \frac{\varepsilon - 1}{\varepsilon + k}\)
- Type: double
- Valide values: \(k > 0.0\)
- Valid for: CPCM solver
- Default: 0.0
- ProbeRadius
Radius of the spherical probe approximating a solvent molecule. Used for generating the solvent-excluded surface (SES) or an approximation of it. Overridden by the built-in value for the chosen solvent.
- Type: double
- Valid values: \(d \in [0.1, 100.0]\,\text{a.u.}\)
- Valid for: all solvers
- Default: 1.0
Green section keywords¶
If Solvent = Explicit
, two Green’s functions sections must be specified
with tags inside
and outside
, i.e. Green<inside>
and
Green<outside>
. The Green’s function inside will always be the vacuum,
while the Green’s function outside might vary.
- Type
Which Green’s function characterizes the medium.
- Type: string
- Valid values: Vacuum | UniformDielectric | SphericalDiffuse
- Default: Vacuum
- Der
How to calculate the directional derivatives of the Green’s function:
- Numerical, perform numerical differentiation debug option;
- Derivative, use automatic differentiation to get the directional derivative;
- Gradient, use automatic differentiation to get the full gradient debug option;
- Hessian, use automatic differentiation to get the full hessian debug option;
- Type: string
- Valid values: Numerical | Derivative | Gradient | Hessian
- Default: Derivative
Note
The spherical diffuse Green’s function always uses numerical differentiation.
- Eps
Static dielectric permittivity of the medium
- Type: double
- Valid values: \(\varepsilon \geq 1.0\)
- Default: 1.0
- EpsDyn
Dynamic dielectric permittivity of the medium
- Type: double
- Valid values: \(\varepsilon \geq 1.0\)
- Default: 1.0
- rofile
Functional form of the dielectric profile
- Type: string
- Valid values: Tanh | Erf
- Valid for: SphericalDiffuse
- Default: Tanh
- Eps1
Static dielectric permittivity inside the interface
- Type: double
- Valid values: \(\varepsilon \geq 1.0\)
- Default: 1.0
- EpsDyn1
Dynamic dielectric permittivity inside the interface
- Type: double
- Valid values: \(\varepsilon \geq 1.0\)
- Default: 1.0
- Eps2
Static dielectric permittivity outside the interface
- Type: double
- Valid values: \(\varepsilon \geq 1.0\)
- Default: 1.0
- EpsDyn2
Dynamic dielectric permittivity outside the interface
- Type: double
- Valid values: \(\varepsilon \geq 1.0\)
- Default: 1.0
- Center
Center of the interface layer. This corresponds to the radius of the spherical droplet.
- Type: double
- Valid for: SphericalDiffuse
- Default: 100.0 a.u.
- Width
Physical width of the interface layer. This value is divided by 6.0 internally.
- Type: double
- Valid for: SphericalDiffuse
- Default: 5.0 a.u.
Warning
Numerical instabilities may arise if a too small value is selected.
- InterfaceOrigin
Center of the spherical droplet
- Type: array of doubles
- Valid for: SphericalDiffuse
- Default: \([0.0, 0.0, 0.0]\)
- MaxL
Maximum value of the angular momentum in the expansion of the Green’s function for the spherical diffuse Green’s function
- Type: integer
- Valid for: SphericalDiffuse
- Default: 30
Molecule section keywords¶
It is possible to run the module standalone and use a classical charge
distribution as specified in this section of the input.
The run_pcm.x
executable has to be compiled for a standalone run with:
python pcmsolver.py -x molecule.inp
where the molecule.inp
input file looks like:
units = angstrom
codata = 2002
medium
{
solvertype = cpcm
correction = 0.5
solvent = cyclohexane
}
cavity
{
type = gepol
area = 0.6
radiiset = uff
mode = implicit
}
molecule
{
# x, y, z, q
geometry = [0.000000000, 0.00000000, 0.08729478, 9.0,
0.000000000, 0.00000000, -1.64558444, 1.0]
}
- Geometry
Coordinates and charges of the molecular aggregate. Format is \([\ldots, x_i, y_i, z_i, Q_i, \ldots]\) Charges are always assumed to be in atomic units
- Type: array of doubles
Available solvents¶
The macroscopic properties for the built-in list of solvents are:
- static permittivity, \(\varepsilon_s\)
- optical permittivity, \(\varepsilon_\infty\)
- probe radius, \(r_\mathrm{probe}\) in Angstrom.
The following table summarizes the built-in solvents and their properties. Solvents are ordered by decreasing static permittivity.
Name Formula \(\varepsilon_s\) \(\varepsilon_\infty\) \(r_\mathrm{probe}\) Water H2O 78.39 1.776 1.385 Dimethylsulfoxide DMSO 46.7 2.179 2.455 Nitromethane CH3NO2 38.20 1.904 2.155 Acetonitrile CH3CN 36.64 1.806 2.155 Methanol CH3OH 32.63 1.758 1.855 Ethanol CH3CH2OH 24.55 1.847 2.180 Acetone C2H6CO 20.7 1.841 2.38 1,2-Dichloroethane C2H4Cl2 10.36 2.085 2.505 Methylenechloride CH2Cl2 8.93 2.020 2.27 Tetrahydrofurane THF 7.58 1.971 2.9 Aniline C6H5NH2 6.89 2.506 2.80 Chlorobenzene C6H5Cl 5.621 2.320 2.805 Chloroform CHCl3 4.90 2.085 2.48 Toluene C6H5CH3 2.379 2.232 2.82 Benzene C6H6 2.247 2.244 2.630 Carbon tetrachloride CCl4 2.228 2.129 2.685 Cyclohexane C6H12 2.023 2.028 2.815 N-heptane C7H16 1.92 1.918 3.125