Particle API

Introduction

The ccdc.particle contains classes for particle surface analysis and slip planes calculation.

The ccdc.particle module contains two classes ccdc.particle.Surface and ccdc.particle.SlipPlanes .

The ccdc.particle.Surface class contains attributes relating to the chemistry and topology of a particle surface.

>>> from ccdc import io
>>> from ccdc.particle import Surface
>>> crystal = io.CrystalReader('CSD').crystal('DEBXIT')
>>> particle_surface = Surface(crystal, (1,0,0))
>>> len(particle_surface.slab.atoms)
414
>>> particle_surface.slab.atoms[0].is_acceptor
False
>>> particle_surface.miller_indices.plane
Plane(normal=Vector(1.000, -0.000, -0.000), distance=22.512)
>>> round(len(list(particle_surface.topology.nodes)), -3)
4000
>>> tuple(round(x,0) for x in list(particle_surface.topology.nodes)[0])
(23.0, -0.0, -0.0)
>>> round(len(list(particle_surface.topology.triangles)), -3)
8000
>>> tuple(round(x,0) for x in list(particle_surface.topology.triangles)[0][0])
(23.0, 0.0, -0.0)
>>> particle_surface.descriptors.projected_area
165.167
>>> particle_surface.descriptors.rugosity
1.375
>>> particle_surface.descriptors.rmsd
1.642
>>> particle_surface.descriptors.skewness
0.777
>>> particle_surface.descriptors.kurtosis
2.793
>>> particle_surface.descriptors.hb_acceptors
0.024
>>> particle_surface.descriptors.hb_donors
0.048
>>> particle_surface.descriptors.unsatisfied_hb_donors
0.012
>>> particle_surface.descriptors.aromatic_bonds
0.145

The ccdc.particle.SlipPlanes class contains attributes relating to the position of possible slip planes within a unit cell.

>>> from ccdc import io
>>> from ccdc.particle import SlipPlanes
>>> crystal = io.EntryReader('CSD').crystal("SCCHRN")
>>> planes = SlipPlanes(crystal)
>>> len(planes)
1
>>> round(planes[0].slab_separation, 3)
1.095
>>> [round(plane.slab_separation, 3) for plane in planes]
[1.095]
>>> planes.set_separation_threshold(-2)
>>> [round(plane.slab_separation, 3) for plane in planes]
[1.095, -0.063, -0.219, -0.34, -0.348, -0.348, -0.677, -1.232, -1.528, -1.724, -1.801, -1.867, -1.928]
>>> planes[0].orientation
MillerIndices(1, 0, 0)
>>> planes[0].h_bonded
False
>>> planes[0].mid_plane
Plane(normal=Vector(0.971, -0.000, 0.239), distance=9.285)
>>> round(planes[0].offset, 3) + 0
0.0
>>> round(planes[0].repeat_distance, 3)
9.285

API

class ccdc.particle.Surface(crystal, miller_indices=None, thickness_factor=0, surface_size=(1, 1), probe_radius=1.2, grid_spacing=0.3, offset=0.0, slip_plane=None, hbond_criterion=None)[source]

A class to represent a particle surface.

Create a surface from a crystal and the given Miller indices or SlipPlane.

Parameters:

  • crystal (ccdc.crystal.Crystal) – The crystal whose surface we want to generate

  • miller_indices (tuple) – Miller indices as a tuple of three integers from -9 to 9

  • thickness_factor (float, optional) – slab thickness multiplier, defaults to automatic

  • surface_size (tuple, optional) – multiplier for u and v vectors, defaults to (1,1)

  • probe_radius (float, optional) – the probe radius for surface calculation, defaults to 1.2

  • grid_spacing (float, optional) – the grid spacing for surface calculation, defaults to 0.3

  • offset (float, optional) – attempt to create a surface displaced by this distance from the default surface (offset=0)

  • slip_plane (ccdc.particle.SlipPlane) – A pre-calculated slip plane defining where to generate the surface

  • hbond_criterion (ccdc.molecule.Molecule.HBondCriterion, optional) – A hydrogen bond criterion to use in the surface analysis, defaults to the Mercury default criterion

class AtomProperties(cssv, contacts, hbc)[source]

Atom properties of a surface.

property hb_acceptors

List of atoms that are hydrogen bond acceptors

property hb_donors

List of atoms that are hydrogen bond donors

property unsatisfied_hb_donors

List of atoms that are unsatisfied hydrogen bond donors

class Descriptors(surface, csv, cssv, contacts, hbc)[source]

Descriptors of a surface.

property aromatic_bonds

Aromatic bond density (count per Angstrom squared).

property hb_acceptors

Hydrogen bond acceptor density (count per Angstrom squared).

property hb_donors

Hydrogen bond donor density (count per Angstrom squared).

property kurtosis

Pearson Kurtosis - a measure of the flatness of distribution.

property projected_area

Reticular area of the surface (in Angstrom squared).

property rmsd

Root mean squared deviation of the surface (in Angstrom)

property rugosity

Ratio between surface area and projected area.

property skewness

Measure of height deviation symmetry, where 0 is a symmetric distribution of peaks and valleys.

property surface_area

Topological surface area (in Angstrom squared).

property unsatisfied_hb_donors

Unsatisfied Hydrogen bond donor density (count per Angstrom squared). Where an unsatisfied hydrogen bond donor is defined as a donor with a hydrogen atom that is surface terminating and not forming a hydrogen bond to the slab.

class Topology(topology)[source]

The topology of the surface, given by a collection of nodes in triangular mesh.

property nodes

Generator of nodes in the surface.

A node is a tuple of three floats.

property triangles

Generator of triangles in the surface.

A triangle is a tuple of three nodes.

property atom_surface_node_contacts

Return a dict mapping ccdc.molecule.Atom to a list of contacting surface node positions.

property descriptors

A ccdc.particle.Surface.Descriptors object.

property miller_indices

The Miller plane indices used to define the particle Surface.

property offset

The offset is the distance translated along the surface normal (in Angstroms).

property periodic_vectors

Returns the UVW vectors for constructing the periodic surface.

property slab

The particle slab represented as a single ccdc.molecule.Molecule.

property slab_molecules

The particle slab represented as a list of the constituent Molecules.

property slicing_plane_distance

Distance from origin of reference plane (hkl and offset, or, SlipPlane) defining the Surface (in Angstroms).

property surface_atoms

Returns a list of atoms found within VDW plus grid_spacing of the topology.

property surface_node_atom_contacts

Return a dict mapping surface node positions to a list of contacting ccdc.molecule.Atom.

property topology

A ccdc.particle.Surface.Topology object.

class ccdc.particle.SlipPlanes(crystal, hbond_criterion=None)[source]

A list-like class to represent the slip planes in a crystal. The individual slip planes can be accessed by list-like index, slice or iteration.

The initial separation threshold is 0.0.

Parameters:
class SlipPlane(parent_planes, plane)[source]

A class to represent a slip plane in a crystal.

as_dict()[source]

Return properties of this slip plane as a dict.

property h_bonded

Returns whether or not intermolecular hydrogen bonds cross the slip plane.

property mid_plane

Returns the slip plane as a ccdc.descriptors.GeometricDescriptors.Plane.

property offset

Returns the perpendicular distance from this slip plane to the parallel Miller plane (in Angstroms).

property orientation

Returns the indices of the Miller plane that sits parallel to the slip plane.

property perpendicular_slip_planes

Returns a list of slip planes with orientations perpendicular to this one.

property repeat_distance

Returns the perpendicular distance to the next equivalent slip plane (in Angstroms).

property slab_separation

Returns the shortest distance (in Angstroms) between the slabs of molecules on either side of the slip plane. A negative value indicates an overlap of the two slabs of molecules.

as_dict()[source]

Return the properties of the slip planes as a dict of lists of values.

property hbond_dimensionality

Return the hydrogen bond dimensionality as an integer.

Returns:

-1 no hydrogen bonds, 0 0D discrete, 1 1D chain, 2 2D sheet, 3 3D network

separation_threshold()[source]

Return the current separation threshold.

set_separation_threshold(minimum_separation)[source]

Set the separation threshold (in Angstroms), thereby affecting the set of slip planes visible.

slip_planes_with_orientation(miller_indices)[source]

Return all slip planes aligned with the given Miller plane, ordered by greatest separation first.