CosmoSolventSurface¶

class CosmoSolventSurface(configuration, grid_spacing=None, atomic_radii=None, atom_grid_density=None, hydrogen_grid_density=None, refine_cosmo_grid_points=None, minimum_grid_point_area=None)¶

Create a surface suitable for a COSMO calculation.

Parameters:

configuration (MoleculeConfiguration | SurfaceConfiguration) – The configuration the grid is being created for.
grid_spacing (PhysicalQuantity of type length) – The spacing of the grid used to map the curvature of the cavity.
Default: 0.3 Angstrom
atomic_radii (dict) – A dictionary with custom atomic radii to use for different elements. Keys and values are PeriodicTableElements and PhysicalQuantity respectively.
atom_grid_density (int) – The density of points used to generate the COSMO surface segments for non-hydrogen atoms. The total number of grid points is given as \(10n^2 + 2\).
Default: 4, which corresponds to 162 grid points.
hydrogen_grid_density (int) – The density of points used to generate the COSMO surface segments for hydrogen atoms. The total number of grid points is given as \(10n^2 + 2\).
Default: 3, which corresponds to 92 grid points.
refine_cosmo_grid_points (bool) – Whether or not grid points are placed exactly on the pseudo-isodensity surface.
Default: False
minimum_grid_point_area (PhysicalQuantity of type area) – The minimum allowed area for a single cavity grid point. Points below this area are combined with other points.
Default: 0.001 Angstrom**2

cavitySurfaceArea()¶

Returns:: The cavity surface area.
Return type:: PhysicalQuantity of type area

cavityVolume()¶

Returns:: The cavity volume.
Return type:: PhysicalQuantity of type volume

constructSurface(fast_calc=True)¶

Construct the tessellated and COSMO surface grids based on the internal parameters.

Parameters:: fast_calc (bool) – Whether or not fast approximate pseudo-density calculation is used.

cosmoGridAreas()¶

Returns:: The surface area of each COSMO surface segment.
Return type:: PhysicalQuantity of type square distance.

cosmoGridAtomMap()¶

Returns:: The index of the atom that each COSMO grid point is associated with.
Return type:: ndarray

cosmoGridCenters()¶

Returns:: The points that define the center of each COSMO surface segment.
Return type:: PhysicalQuantity of type distance.

cosmoGridChargeDensities()¶

Returns:: The COSMO charge densities at each point on the surface.
Return type:: PhysicalQuantity of type charge per area

cosmoGridCharges()¶

Returns:: The COSMO charges at each point on the surface.
Return type:: PhysicalQuantity of type charge

cosmoGridNormals()¶

Returns:: The normal vector pointing out of the cavity.
Return type:: ndarray

cosmoGridPotentials()¶

Returns:: The electrostatic potential from the molecule at the surface.
Return type:: PhysicalQuantity of type energy per charge

elementalSurfaceArea()¶

Returns:: Return a dictionary listing the surface area assigned to each atom
Return type:: dict

minimumGridPointArea()¶

Returns:: The minimum grid point area allowed in constructing the grid.
Return type:: PhysicalQuantity of type area

numberOfCosmoPoints()¶

Returns:: The number of COSMO grid points that maps the surface.
Return type:: int

numberOfTesserae()¶

Returns:: The number of tesserae that maps the surface.
Return type:: int

tesserae()¶

Returns:: The tesserae that define the surface as an N,3,3 array. N is the number of tesserae. The array is indexed by tesserae, then point in the triangle, then Cartesian coordinate.
Return type:: PhysicalQuantity of type distance.

tesseraeAreas()¶

Returns:: The surface area of each tessera.
Return type:: PhysicalQuantity of type square distance.

tesseraeCenters()¶

Returns:: The points that define the center of each tessera.
Return type:: PhysicalQuantity of type distance.

tesseraeChargeDensities(corners=False)¶

The charge density assigned to the tessellated surface.

Parameters:: corners (bool) – Whether to work with the corners of the tesserae or the center.
Returns:: The charge densities of tesserae, based on the density at the closest grid point.
Return type:: PhysicalQuantity of type charge per area

tesseraeNormals()¶

Returns:: The unit normal of each tesserae in the cavity
Return type:: ndarray

uniqueString()¶: Return a unique string representing the state of the object.

Notes¶

The CosmoSolventSurface object creates the grid of surface points used in the COSMO solvation model. The method used to construct the surface follows the method outlined by Klamt and Diedenhofen[1]. In this method a pseudo-density isosurface around the molecule is first created. The pseudo-density includes terms that smooths the surface between atoms and avoids the cusps that are typically formed when just spheres are used. The isosurface is created by calculating the pseudo-density on a grid around the molecule which is then used to create tessellations that define the surface. To define the actual COSMO grid, a spherical grid of points centered on each atom is projected out to the atomic radius. The tessellations of the pseudo-density grid are then used to assign surface area to each of these points. Each tesserae is assigned to the closest COSMO grid point. Points that have no associated area, often because they are inside the cavity, are removed from the grid. Each projected point is also moved to the center of the tesserae that are assigned to it.

Solvent surfaces can also be created for bulk slabs in a BulkConfiguration or a surface in a SurfaceConfiguration. In both cases the surface is assumed to be aligned with the C direction of the unit cell. The same general algorithm can be used for surfaces, with the 2D periodicity of the structure also being taken into account. In bulk slabs a solvent surface is only created on the top side of the surface. The bottom side is assumed to be modelling the effect of the bulk material, and is therefore not solvated.

The construction of COSMO solvent cavity can be modified in a number of ways. The spacing of the grid used to calculate the initial pseudo-density is given with the argument grid_spacing. Lowering the distance between grid points places the calculated isodensity surface closer to the true isosurface, at the cost of more computation time and memory. The default value is sufficient for most COSMO calculations. The atomic radii, which determines the size of the COSMO cavity, can also be specified with the atomic_radii argument. This takes a dictionary of elements and corresponding atomic radii for the elements whose radii are to be modified. Here again the default radii are optimized for the COSMO method and are suitable for most calculations [2].

The number of these projected points can be set, altering their density on the surface. Different densities are allowed for hydrogen and non-hydrogen atoms, as hydrogen is significantly smaller than other atoms. The arguments to set the number of points are hydrogen_grid_density and atom_grid_density. These each take an integer that specifies how many times the atomic grid is divided. For a given number \(n\), the number of grid points is \(10n^2 + 2\). For hydrogen and non-hydrogen atoms the defaults are 3 and 4 respectively, which corresponds to 92 and 162 points. Increasing the grid density increases the accuracy of the surface charge distribution at the cost of more memory and computational time. As with the other parameters, the defaults here should be sufficient for most calculations. When the points are projected from the atoms, they are assigned a surface area based on the segments of the pseudo-density surface that are closest to the point. Points with a surface area below a set limit are removed, and their surface area is assigned to surrounding grid points. This limit can be set with the argument minimum_grid_point_araea.

To create a CosmoSolventSurface a molecule or surface must be included which defines the configuration that the surface is created for. Building the surface geometry is done by calling the constructSurface method on the object. This creates both the tessellated and COSMO grids, but does not add any information about surface charges. These are added during a DFT calculation with the COSMO model. Once the surface is defined and DFT surface charge information is added, the details of the surface can be queried using a number reader methods. These include details such as grid positions, charges, surface areas, surface normals and atom assoiciated with each grid point.

The CosmoSolventSurface used in a COSMO DFT calculation can be obtained from an updated configuration using the SolventSurface analysis object. This extracts and saves the surface used in the calculation. This surface includes the DFT based information such as surface charges. The CosmoSolventSurface object can also be added to the Viewer, allowing the visualization of the surface.