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.

property intermolecular

Whether the contact is inter- or intra-molecular.

property symmetry_operators

The symmetry operators by which the atoms of the contact are related.

property type

The type of contact.

class Disorder(csv)

A class to represent disorder in the crystal structure.

class Assembly(csv, assembly)

Represents a disorder assembly.

property active

The active disorder group of this assembly.

Returns:

A ccdc.crystal.Crystal.Disorder.Group object.

property groups

The disorder groups in this assembly.

Returns:

A tuple of ccdc.crystal.Crystal.Disorder.Group objects.

property id

The identifier of the disorder assembly.

class Group(csv, assembly, group)

Represents a disorder group in a disorder assembly.

activate()

Set this disorder group as active.

property atoms

The list of atoms in this disorder group.

Returns:

A list of ccdc.molecule.Atom objects.

property id

The identifier of this disorder group.

property occupancy

The occupancy of this disorder group.

property assemblies

The disorder assemblies in the crystal structure.

Returns:

A tuple of ccdc.crystal.Crystal.Disorder.Assembly objects.

property combinations

Yield combination of disorder groups.

Note that the crystal is updated with the yielded disorder groups.

property is_suppressed

Return True if disorder is suppressed, False if disorder is analysed.

If the disorder is suppressed, all of the minority occupancy, that is, suppressed, atoms are contained in a single disorder assembly. (The majority occupancy atoms are always bonded and so are not included in the disorder object.) The disorder assembly contains two disorder groups. The first one includes all the suppressed atoms, and the second none of them. The second group is by default the active group, which describes a molecule with just the majority occupancy atoms and none of the minority occupancy atoms.

If the disorder is not suppressed, it is fully represented. Assemblies exist for every independent area of disorder in the crystal. And multiple groups exist in each assembly.

class HBond(_view, _contact)

A crystallographic hydrogen bond.

property intermolecular

Whether the contact is inter- or intra-molecular.

property symmetry_operators

The symmetry operators by which the atoms of the contact are related.

property type

The type of contact.

class MillerIndices(h, k, l, crystal, _cell=None)

Represents the family of planes subtended by Miller indices.

property hkl

The indices.

property order

The order for improper Miller indices.

property plane

The plane intersecting the unit cell.

property proper

The proper, relatively prime Miller indices.

class ReducedCell(_cell)

The reduced cell of a crystal.

property cell_angles

The cell angles of the reduced cell.

property cell_lengths

The cell lengths of the reduced cell.

property volume

The volume of the reduced cell.

add_hydrogens(mode='all', add_sites=True)

Add hydrogen atoms to the crystal.

This method adds hydrogens to a crystal (as opposed to a molecule). Unlike the associated Molecule method add_hydrogens() this version adds to the crystal and is more crystallographically aware (trying to account for possible disorder and also the crystalline environment when adding sites.)

Parameters:

• mode – ‘all’ to generate all hydrogens (throws away existing hydrogens) or ‘missing’ to generate hydrogens deemed to be missing.

• add_sites – ‘True’ to generate 3D coordinates for hydrogens (default) ‘False’ to only generate siteless atoms

Raises:

RuntimeError if any heavy atom has no site.

Raises:

RuntimeError if any atoms are of unknown type.

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.

property 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.

property calculated_density

Calculated density of the crystal.

property 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

property 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

property 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

copy()

Return a deep copy of the crystal.

property crystal_system

The space group system of the crystal.

property disorder

The disorder object of the crystal.

Returns None if crystal structure has no disorder.

Returns:

A ccdc.crystal.Crystal.Disorder object.

property disordered_molecule

The underlying molecule with disordered atoms represented.

property formula

Return the chemical formula of the molecule in the crystal.

property fractional_to_orthogonal

Return the transformation mapping fractional to orthogonal coordinates in the crystal cell.

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’, ‘cif’, ‘mmcif’ or ‘smiles’

Returns:

a ccdc.crystal.Crystal

Raises:

TypeError if the format string is not ‘’, ‘mol2’, ‘sdf’, ‘mol’, ‘cif’ or ‘smiles’.

Raises:

RuntimeError if the string representation is incorrectly formatted

generate_inchi(include_stereo=True, add_hydrogens=True)

Return a ccdc.descriptors.MolecularDescriptors.InChIGenerator.InChI object for the molecule

Parameters:

• include_stereo – include stereochemistry (True, default) or ignore stereochemistry (False) when generating the InChI object

• add_hydrogens – add hydrogens (True, default) or not add hydrogens (False) when generating the InChI object

Returns:

a ccdc.descriptors.MolecularDescriptors.InChIGenerator.InChI object

static generate_reduced_crystal(crystal)

This generates a copy of crystal in Niggli reduced cell form.

Parameters:

crystal – input ccdc.crystal.Crystal

Returns:

ccdc.crystal.Crystal in Niggli reduced cell form

property 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

property identifier

The string identifier of the crystal, e.g. ‘ABEBUF’.

property inverted_structure

Return an inverted crystal structure

Returns:

a ccdc.crystal.Crystal instance with inverted structure

Raises:

RuntimeError if unable to invert crystal structure

property is_centrosymmetric

Whether or not the crystal is centrosymmetric.

property is_sohncke

Whether or not the crystal is in a Sohncke spacegroup.

property 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=[], include_central=False)

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.

• include_central – if True the returned shell will contain the central molecules, otherwise they are excluded.

Returns:

ccdc.molecule.Molecule containing the atoms within the distance cutoff.

property molecule

The underlying molecule.

Note that a molecule can have several components, and, where present, this takes into account the disorder selection.

property orthogonal_to_fractional

Return the transformation mapping orthogonal to fractional coordinates in the crystal cell.

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.

property 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.

Parameters:

• atoms – an iterable of ccdc.molecule.Atom instances whose polymeric bonds are to be expanded.

• repetitions – the number of expansions to be performed.

Returns:

ccdc.molecule.Molecule instance.

reduce_symmetry()

This generates a copy of the crystal in reduced symmetry form, that is a reduced spacegroup symmetry form so that no molecules occupy special positions

Parameters:

crystal – input ccdc.crystal.Crystal

Returns:

ccdc.crystal.Crystal in reduced symmetry form

property reduced_cell

The reduced cell of the crystal.

remove_hydrogens()

Remove all hydrogen atoms from this 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.

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

Non standard spacegroup numbers, those above 230, will be returned with setting number 0. Unrecognised spacegroups will raise a RuntimeError.

property 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.

property 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’, ‘cif’, ‘mmcif’ or ‘smiles’

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.3

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

property z_prime

The number of molecules in the asymmetric unit.

property 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.

property 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

property packing_shell_size

Number of molecules in the packing shell.

property rmsd

RMSD of the reference and the target.

class Settings(_settings=None)

Settings for Packing similarity.

property allow_artificial_inversion

Whether or not to invert a structure where there is no inversion symmetry.

property allow_molecular_differences

Whether different compounds may be compared.

property angle_tolerance

Maximum difference between reference and target angles.

property distance_tolerance

Maximum difference between reference and target distances as a decimal fraction.

property ignore_bond_counts

Whether or not to take account of bond counts.

property ignore_bond_types

Whether or not to take account of bond types.

property ignore_hydrogen_counts

Whether or not to ignore hydrogen counts.

property ignore_hydrogen_positions

Whether or not H positions should be ignored.

property ignore_smallest_components

Whether or not to take account of solvents.

property match_entire_packing_shell

Whether or not all molecules of the shell have to be matched.

property molecular_similarity_threshold

Do not compare structures whose similarity is lower than this value.

property packing_shell_size

The number of molecules in the packing shell.

property show_highest_similarity_result

Control number of results.

For structures with Z’ > 1 there will be more than one result.

property skip_when_identifiers_equal

Do not compare structures with the same identifier.

property timeout_ms

A timeout for the packing similarity calculation. 0 means no timeout.

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