Crystal API¶
Introduction¶
The main class of the ccdc.crystal
module is ccdc.crystal.Crystal
.
ccdc.crystal.Crystal
contains attributes and functions that relate
to crystallography. An example of a crystallographic attribute is the
ccdc.crystal.Crystal.cell_volume
.
>>> from ccdc.io import CrystalReader
>>> csd_crystal_reader = CrystalReader('CSD')
>>> first_csd_crystal = csd_crystal_reader[0]
>>> round(first_csd_crystal.cell_volume, 3)
769.978
See also
API¶
-
class
ccdc.crystal.
Crystal
(crystal, identifier)[source]¶ Represents a crystal.
-
class
Contact
(_view, _contact)[source]¶ A crystallographic contact.
-
intermolecular
¶ Whether the contact is inter- or intra-molecular.
-
symmetry_operators
¶ The symmetry operators by which the atoms of the contact are related.
-
type
¶ The type of contact.
-
-
class
HBond
(_view, _contact)[source]¶ A crystallographic hydrogen bond.
-
intermolecular
¶ Whether the contact is inter- or intra-molecular.
-
symmetry_operators
¶ The symmetry operators by which the atoms of the contact are related.
-
type
¶ The type of contact.
-
-
class
MillerIndices
(h, k, l, crystal, _cell=None)[source]¶ Represents the family of planes subtended by Miller indices.
-
hkl
¶ The indices.
-
order
¶ The order for improper Miller indices.
-
plane
¶ The plane intersecting the unit cell.
-
proper
¶ The proper, relatively prime Miller indices.
-
-
class
ReducedCell
(_cell)[source]¶ The reduced cell of a crystal.
-
cell_angles
¶ The cell angles of the reduced cell.
-
cell_lengths
¶ The cell lengths of the reduced cell.
-
volume
¶ The volume of the reduced cell.
-
-
assign_bonds
()[source]¶ Detect and assign bond types in the crystal.
This function will ignore any existing bond information and will use the geometry of the crystal to detect and assign bond types.
-
asymmetric_unit_molecule
¶ The molecular representation of the asymmetric unit.
-
atoms_on_special_positions
(symmetry_operator=None)[source]¶ The tuple of atoms lying on symmetry axes.
Parameters: symmetry_operator – a symmetry operator, or None
to get atoms on any symmetry axis.Returns: a set of ccdc.molecule.Atom
instances.
-
calculated_density
¶ Calculated density of the crystal.
-
cell_angles
¶ Tuple containing the cell angles; (alpha, beta, gamma).
Note that the angles are reported in degrees. The returned value may be addressed by index or by key:
>>> a = CellAngles(90.0, 45.0, 33.3) >>> a.alpha 90.0 >>> a[1] 45.0
-
cell_lengths
¶ Tuple containing the cell axis lengths: (a, b, c).
The returned value may be addressed by index or key:
>>> l = CellLengths(1, 2, 3) >>> l[0] 1 >>> l.b 2
-
cell_volume
¶ Volume of the unit cell.
-
contact_network
(intermolecular='Any', distance_range=(-5.0, 0.0), vdw_corrected=True, path_length_range=(4, 999), repetitions=1)[source]¶ The molecule resulting from expanding all crystallographic contacts of the crystal.
A crystallographic contact may span two symmetry related molecules of the crystal.
Parameters: - intermolecular – ‘Intramolecular’, ‘Intermolecular’ or ‘Any’.
- distance_range – Minimum and maximum distances considered acceptable for a contact to be formed.
- vdw_corrected – Whether the distances are relative to the Van der Waals radius of the atoms.
- path_length_range – Minimum and maximum values for length of path between the contact atoms
Returns: a tuple of
ccdc.crystal.Crystal.Contact
-
contacts
(intermolecular='Any', distance_range=(-5.0, 0.0), path_length_range=(4, 999))[source]¶ The collection of crystallographic contacts in this crystal structure.
A crystallographic contact may span two symmetry related molecules of the crystal.
Distance limits for nonbonded contacts are defined as distances relative to the sum of van der Waals Radii, i.e.:
v(X) + v(Y) - p < d(X…Y) < v(X) + v(Y) - qwhere v(X) and v(Y) are the vdW radii of X and Y respectively and p and q are user-specified values in Angstroms (e.g., if p = 0.5 and q = 0.1, the contact must be at least 0.1 Angstroms shorter than the sum of vdW radii but no more than 0.5 Angstroms shorter).
Standard van der Waals radii are assigned to the common elements. They are taken from Bondi, J.Phys.Chem., 68, 441, 1964. Other elements are assigned van der Waals radii of 2.0 Angstroms.
Parameters: - intermolecular – ‘Intramolecular’, ‘Intermolecular’ or ‘Any’.
- distance_range – Minimum and maximum distances considered acceptable for a contact to be formed (Angstroms).
- path_length_range – Minimum and maximum values for length of path between the contact atoms
Returns: a tuple of
ccdc.crystal.Crystal.Contact
-
crystal_system
¶ The space group system of the crystal.
-
disordered_molecule
¶ The underlying molecule with disordered atoms represented.
-
formula
¶ Return the chemical formula of the molecule in the crystal.
-
static
from_string
(s, format='')[source]¶ Create a crystal from a string representation.
The format will be auto-detected if not specified.
Parameters: - s – string representation of a crystal or molecule
- format – one of ‘mol2’, ‘sdf’, ‘mol’ or ‘cif’
Returns: Raises: TypeError if the format string is not ‘’, ‘mol2’, ‘sdf’, ‘mol’ or ‘cif’.
Raises: RuntimeError if the string representation is incorrectly formatted
-
has_disorder
¶ Whether or not the crystal has disorder.
-
hbond_network
(hbond_criterion=None, repetitions=1)[source]¶ The molecule that results from expanding all hbonds in the crystal.
Parameters: - hbond_criterion – a
ccdc.molecule.Molecule.HBondCriterion
instance. - repetitions – the number of times hbond contacts will be expanded.
- hbond_criterion – a
-
hbonds
(intermolecular='Any', distance_range=(-5.0, 0.0), angle_tolerance=120.0, vdw_corrected=True, require_hydrogens=True, path_length_range=(4, 999), hbond_criterion=None, unique=True)[source]¶ The collection of crystallographic hydrogen bonds in this crystal structure.
A crystallographic hydrogen bond may span two symmetry related molecules of the crystal.
The definition of a hydrogen bond (D-H…A) is a contact meeting the following criteria:
- The donor (D) must be a nitrogen, oxygen or sulphur atom covalently bound to at least one hydrogen.
- The acceptor (A) must be a nitrogen, oxygen, sulphur or halogen with at least one available lone pair (e.g., pyramidal trigonal nitrogen is regarded as an acceptor but planar trigonal nitrogen is not).
- The distance must be within the specified range (distance_range) relative to the sum of van der Waals Radii of the atoms involed in the H-bond (vdw_corrected is True) or within the absolute specified range (vdw_corrected is False) in Angstroms. If require_hydrogens is True, the distance constraint refers to the H…A distance; otherwise it refers to the D…A distance.
- The D-H…A angle must be within the specified angle_tolerance range.
- The contact may be intermolecular and/or intramolecular involving donor and acceptor atoms separated with covalent bonds within the specified path length.
If hydrogens are not required, they will not appear in the returned
ccdc.molecule.Molecule.HBond.atoms
.Parameters: - intermolecular – ‘Intramolecular’, ‘Intermolecular’ or ‘Any’.
- distance_range – Minimum and maximum distances considered acceptable for a hydrogen bond to be formed (Angstroms).
- vdw_corrected – Whether the distances are relative to the Van der Waals radius of the atoms.
- angle_tolerance – Acceptable range for a hydrogen Donor-Hydrogen-Acceptor angle (degrees).
- require_hydrogens – Whether hydrogens are necessary for the hydrogen bond.
- path_length_range – Minimum and maximum values for length of path between donor and acceptor atom
- hbond_criterion – an instance of
ccdc.molecule.Molecule.HBondCriterion
orNone
. If notNone
the definitions there will override any other specified argument. - unique – bool. If True, the crystallographically unique HBonds will be returned; if
False
the full set of HBonds will be returned. These may include some symmetry copies.
Returns: a tuple of
ccdc.crystal.Crystal.HBond
-
identifier
¶ The string identifier of the crystal, e.g. ‘ABEBUF’.
-
is_centrosymmetric
¶ Whether or not the crystal is centrosymmetric.
-
is_sohncke
¶ Whether or not the crystal is in a Sohncke spacegroup.
-
lattice_centring
¶ The lattice centring of this crystal.
-
miller_indices
(h, k, l)[source]¶ The
ccdc.crystal.Crystal.MillerIndices
instance corresponding to integers h, k, l.Parameters: - h – Miller index
- k – Miller index
- l – Miller index
Returns: ccdc.crystal.Crystal.MillerIndices
instance.Raises: TypeError if Miller indices are 0, 0, 0.
-
molecular_shell
(distance_type='actual', distance_range=(0.0, 3.0), atom_selection=[])[source]¶ Return a molecule containing the atoms within a distance cutoff.
A subset of atoms to base the expansion on can be provided using the atom_selection argument.
If the distance type is VdW then the min to max range is relative to the sum of the vdW radii.
Parameters: - distance_type – ‘vdw’ or ‘actual’.
- distance_range – Minimum and maximum distances for the contact distance range.
- atom_selection – list of atoms to base the expansion on.
Returns: ccdc.molecule.Molecule
containing the atoms within the distance cutoff excluding any atoms from the molecules defined in the atom selection.
-
molecule
¶ The underlying molecule.
Note that a molecule can have several components.
-
packing
(box_dimensions=((0, 0, 0), (1, 1, 1)), inclusion='CentroidIncluded')[source]¶ A molecule which fills some multiple of the unit cell of the crystal.
The atoms to include are specified with:
- ‘CentroidIncluded’ where whole molecules will be included if their centroid is within the box dimensions,
- ‘AllAtomsIncluded’ where whole molecules will be included only if all atoms of the molecule lie within the box,
- ‘AnyAtomIncluded’ where whole molecules will be included if any atom of the molecule lies within the box,
- ‘OnlyAtomsIncluded’ where all and only the atoms lying within the box will be included.
The default is to fill the unit cell.
Parameters: - box_dimensions – a pair of triples being the minimum and maximum multipliers of the unit cell axes to fill with the crystal’s molecules.
- inclusion – one of ‘CentroidIncluded’, ‘AllAtomsIncluded’, ‘AnyAtomIncluded’, or ‘OnlyAtomsIncluded’ where all and only the atoms lying within the box will be included.
Returns: a
ccdc.molecule.Molecule
instance.
-
packing_coefficient
¶ The packing coefficient of the crystal.
Measures the proportion of the unit cell occupied by atoms. It is a fraction between zero and one; going from unoccupied to completely filled.
-
packing_shell
(packing_shell_size=15)[source]¶ Create a packing shell of the crystal.
This method is available only to CSD-Materials and CSD-Enterprise users.
Parameters: packing_shell_size – the required number of molecules in the packing shell Returns: a ccdc.molecule.Molecule
containing packing_shell_size replicas of the crystal.
-
polymer_expansion
(atoms=None, repetitions=1)[source]¶ The molecule resulting from the expansion of polymeric bonds in the crystal. :parameter atoms: an iterable of
ccdc.molecule.Atom
instances whose polymeric bonds are to be expanded. :parameter repetitions: the number of expansions to be performed. :returns:ccdc.molecule.Molecule
instance.
-
reduced_cell
¶ The reduced cell of the crystal.
-
slicing
(plane, thickness=10.0, width=20.0, displacement=0.0, inclusion='CentroidIncluded')[source]¶ The molecules of the crystal subtended by slicing along a plane.
Parameters: - plane – a slicing plane.
- thickness – the thickness of the slicing view.
- width – the width of the slicing view.
- displacement – the displacement of the slicing view.
- inclusion – one of ‘CentroidIncluded’, ‘AllAtomsIncluded’, ‘AnyAtomIncluded’, or ‘OnlyAtomsIncluded’.
Returns: a
ccdc.molecule.Molecule
instance.
-
spacegroup_number_and_setting
¶ The number in international tables and setting of the crystal’s space group.
>>> from ccdc.io import CrystalReader >>> csd_crystal_reader = CrystalReader('CSD') >>> crystal = csd_crystal_reader.crystal('AABHTZ') >>> crystal.spacegroup_number_and_setting (2, 1)
-
spacegroup_symbol
¶ The space group symbol of the crystal.
-
symmetric_molecule
(symmop, translate=None, force=False)[source]¶ Generate a symmetry related copy of the molecule.
This method may be used to build multi-molecular crystals for visualisation and other purposes.
Parameters: - symmop – a string representation of the symmetry operation, such as ‘-x,1/2+y,1/2-z’ representing a 2-fold screw axis.
- translate – a sequence of three integers representing the translational component to be applied to the symmetry operation. If this is None, then the symmetry operator will contain the unit cell translation parameters, e.g. of the form ‘1-x,2-y,-1+z’.
- force – a boolean value to allow symmetry operators not supported by the crystal to be applied.
Returns: a
ccdc.molecule.Molecule
derived from this crystal with the symmetry operation applied.Raises: TypeError if the symmetry operator is not in the symmetry operators of this crystal and force is not True.
-
static
symmetry_operator_description
(symmetry_operator)[source]¶ A textual description of the symmetry operator.
-
symmetry_operators
¶ The symmetry operators pertaining to this crystal.
Returns: a tuple of string representations of the symmetry operators
-
static
symmetry_rotation
(operator)[source]¶ The rotational component of the symmetry operator.
Parameters: operator – a string representation of a symmetry operator Returns: a tuple of 9 integer values representing the 3x3 rotation matrix of the operator
-
static
symmetry_translation
(operator)[source]¶ The translational component of the symmetry operator.
Parameters: operator – a string representation of a symmetry operator Returns: a tuple of three floats representing the translational component of the operator
-
to_string
(format='mol2')[source]¶ Convert the crystal to a mol2 representation.
Parameters: format – ‘mol2’, ‘sdf’ or ‘cif’ Returns: string representation in the appropriate format Raises: TypeError if format is not as above.
-
void_volume
(probe_radius=1.2, grid_spacing=0.7, mode='contact')[source]¶ Determine the void volume of the crystal.
>>> from ccdc.io import EntryReader >>> entry_reader = EntryReader('CSD') >>> abawop_crystal = entry_reader.crystal('ABAWOP') >>> round(abawop_crystal.void_volume(), 2) 13.17
Parameters: - probe_radius – float, size of the probe
- grid_spacing – float, fineness of the grid on which the calculation is made
- mode – either ‘accessible’ or ‘contact’ according to whether the centre of the probe or the whole probe must be accomodated.
Returns: void volume as a percentage of the unit cell volume
-
z_prime
¶ The number of molecules in the asymmetric unit.
-
z_value
¶ The number of molecules in the unit cell.
-
class
-
class
ccdc.crystal.
PackingSimilarity
(settings=None)[source]¶ Compare crystal packing similarities.
The crystal packing similarity feature is available only to CSD-Materials and CSD-Enterprise users.
-
class
Comparison
(_comp, reference, target)[source]¶ The result of a comparison.
-
nmatched_molecules
¶ The number of molecules of the crystal matched.
-
overlay_molecules
()[source]¶ Return the overlayed molecules.
Returns: a pair of packing shells, the first of which has been overlayed on the second
-
packing_shell_size
¶ Number of molecules in the packing shell.
-
rmsd
¶ RMSD of the reference and the target.
-
-
class
Settings
(_settings=None)[source]¶ Settings for Packing similarity.
-
allow_artificial_inversion
¶ Whether or not to invert a structure where there is no inversion symmetry.
-
allow_molecular_differences
¶ Whether different compounds may be compared.
-
angle_tolerance
¶ Maximum difference between reference and target angles.
-
distance_tolerance
¶ Maximum difference between reference and target distances as a decimal fraction.
-
ignore_bond_counts
¶ Whether or not to take account of bond counts.
-
ignore_bond_types
¶ Whether or not to take account of bond types.
-
ignore_hydrogen_counts
¶ Whether or not to ignore hydrogen counts.
-
ignore_hydrogen_positions
¶ Whether or not H positions should be ignored.
-
ignore_smallest_components
¶ Whether or not to take account of solvents.
-
match_entire_packing_shell
¶ Whether or not all molecules of the shell have to be matched.
-
molecular_similarity_threshold
¶ Do not compare structures whose similarity is lower than this value.
-
packing_shell_size
¶ The number of molecules in the packing shell.
-
show_highest_similarity_result
¶ Control number of results.
For structures with Z’ > 1 there will be more than one result.
-
skip_when_identifiers_equal
¶ Do not compare structures with the same identifier.
-
-
compare
(reference, target)[source]¶ Compare two crystals.
Parameters: - reference –
ccdc.crystal.Crystal
- target –
ccdc.crystal.Crystal
Returns: ccdc.crystal.PackingSimilarity.Comparison
, a tuple of comparisons if there are more than one orNone
if no comparison was possible- reference –
-
class