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

Descriptive crystal documentation.

API

class ccdc.crystal.Crystal(crystal, identifier)

Represents a crystal.

class Contact(_view, _contact)

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)

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)

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)

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()

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)

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.

centre_molecule()

Ensures that the molecule of the crystal lies within the unit cell.

contact_network(intermolecular='Any', distance_range=(-5.0, 0.0), vdw_corrected=True, path_length_range=(4, 999), repetitions=1)

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))

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) - q

where 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='')

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:

a ccdc.crystal.Crystal

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)

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.

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)

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 or None. If not None 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)

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=[])

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')

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)

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)

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')

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)

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)

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)

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)

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')

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')

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 ccdc.crystal.PackingSimilarity(settings=None)

Compare crystal packing similarities.

The crystal packing similarity feature is available only to CSD-Materials and CSD-Enterprise users.

class Comparison(_comp, reference, target)

The result of a comparison.

nmatched_molecules

The number of molecules of the crystal matched.

overlay_molecules()

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)

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)

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 or None if no comparison was possible