Morphology API

Introduction

The ccdc.morphology module contains classes for crystal morphology.

The main classes in the ccdc.morphology module are:

• ccdc.morphology.MorphologyBase.

• ccdc.morphology.BFDHMorphology.

• ccdc.morphology.VisualHabitMorphology.

• ccdc.morphology.SymmetryAllowedMorphology.

• ccdc.morphology.SeedMorphology.

See also

Descriptive Morphology documentation and Descriptive VisualHabit documentation

API

class ccdc.morphology.MorphologyBase(crystal=None, morph=None)

The morphology of a crystal. This is a base class with methods to work with crystal morphologies in the CSD-Python API.

property bounding_box

The bounding box of the morphology.

A pair of ccdc.molecule.Coordinates representing the minimum and maximum corners of the box.

property centre_of_geometry

The centroid of the morphology.

check_morphology()

Helper func to check that the morphology has been calculated.

property facets

The facets making up the morphology. A facet which has “grown out” of the morphology will not be included here.

static from_file(file_name)

Creates a Morphology instance from a CIF file.

The CIF file should be those written by this class or Mercury, which includes a scaling for each of the perpendicular distances.

static from_growth_rates(crystal, growth_rates)

Creates a morphology from an iterable of growth rates.

Parameters:

• crystal – an instance of ccdc.crystal.Crystal.

• growth_rates – an iterable of pairs, ccdc.crystal.Crystal.MillerIndices and perpendicular distance, otherwise known as morphological importance.

property oriented_bounding_box

The minimum volume box of the morphology.

This will not necessarily be aligned to the orthonormal cartesian axes.

relative_area(miller_indices)

The relative area of the facet.

This is what is usually called the Morphological Importance of a facet.

property scale_factor

The factor by which the morphology is scaled.

property volume

The volume of the morphology.

This is calculated stochastically, rather than analytically, so has some error.

write(file_name, keep_all_indices=False)

Write this morphology to CIF file.

class ccdc.morphology.Facet(_facet, _perpendicular_distance, _miller_indices)

A facet expressed in the crystal morphology having an exposed surface area (morphological importance) greater than zero.

property area

The area of the polygon.

property centre_of_geometry

The centre of geometry of the facet.

property coordinates

The coordinates of the vertices of the facet.

property edges

The edges making up the facet.

property miller_indices

The Miller indices of the facet.

property perpendicular_distance

The perpendicular distance from the origin.

property plane

The plane of the facet.

This is a ccdc.descriptors.GeometricDescriptors.Plane instance.

class ccdc.morphology.BFDHMorphology(crystal)

Calculates a morphology according to the Bravai, Friedel, Dannay and harker method

class ccdc.morphology.VisualHabitMorphology(_results, crystal)

The morphological information of the VisualHabit calculation

class VisualHabitFacet(_facet, _perpendicular_distance, _miller_indices, _face_property)

One of the facets of a VisualHabit morphology.

property attachment_energy

Attachment energy of the facet in kJ/mol

property d_spacing

d-spacing of the facet in Angstroms.

property offset

The offset at which the energies are measured, in Angstroms.

property percentage_area

Percentage of the total surface area accounted for by this facet

property surface_energy

Surface energy of the facet in mJ/m^2

property facets

The facets making up the morphology

Returns:

A tuple of ccdc.morphology.VisualHabitMorphology.VisualHabitFacet instances

class ccdc.morphology.VisualHabit(settings=None)

Descriptors for VisualHabit.

class Results(crystal, _results)

Holds the results of a VisualHabit calculation.

All energy terms are given in kJ/mol.

class LatticeEnergy(_energies)

The lattice energy associated with a facet of the lattice.

property electrostatic: float

The electrostatic energy.

property h_bond: float

The total hydrogen bond energy.

property h_bond_attraction: float

The attractive hydrogen bond energy.

property h_bond_repulsion: float

The repulsive hydrogen bond energy.

property total: float

The total energy.

property vdw: float

The total Van der Waals energy.

property vdw_attraction: float

The attractive Van der Waals energy.

property vdw_repulsion: float

The repulsive Van der Waals energy.

class Synthon(_synthon, _results)

A synthon or molecular interaction within the crystal lattice.

property distance: float

The distance between the two molecules’s centroids in Angstroms.

property electrostatic: float

The electrostatic energy in kJ/mol.

property h_bond: float

The hydrogen bond energy in kJ/mol.

property molecule1: Molecule

Return the first molecule in the synthon.

property molecule2: Molecule

Return the second molecule in the synthon.

property symmetry_operator: str

Return a string representing the symmetry operator relating the two molecules.

property total: float

The total energy in kJ/mol.

property translation_vector

Return the unit cell translation vector between the two molecules.

property vdw: float

The Van der Waals energy in kJ/mol.

facet_energy(miller_indices: MillerIndices | tuple)

Return the facet for the miller indices with energy information, but no morphology geometry information.

Parameters:

miller_indices – a ccdc.crystal.Crystal.MillerIndices instance, or a tuple of (h,k,l).

Returns:

A ccdc.morphology.VisualHabitMorphology.VisualHabitFacet instance.

property lattice_energy: LatticeEnergy

The energies associated with the lattice.

Returns:

A ccdc.descriptors.CrystalDescriptors.VisualHabit.Results.LatticeEnergy instance

property morphology

The calculated morphology

Returns:

A ccdc.morphology.VisualHabitMorphology instance

property synthons

The synthons, or molecular interactions within the crystal.

Returns:

A tuple of ccdc.descriptors.CrystalDescriptors.VisualHabit.Results.Synthon instances.

class Settings

Settings for the VisualHabit runner.

property convergence_limiting_radius

The convergence limiting radius for the calculation.

The default is 30.0 Angstroms.

Setting it higher will significantly increase the time of calculation.

property electrostatic_correction

The electrostatic correction mode.

Set to None to turn this off. Default to Evjen.

property potential

The potential forcefield used for the calculation.

Set this to one of dreidingII (default), gavezzotti, momany, CLP or CSD-OPCS16.

calculate(crystal: Crystal) → Results

Calculate the habit of the crystal.

Parameters:

crystal – a ccdc.crystal.Crystal instance.

Returns:

a ccdc.morphology.VisualHabit.Results instance.

The calculation will not be possible if the crystal contains significant disorder or if some heavy atoms of the crystal have no coordinates.

class ccdc.morphology.SymmetryAllowedMorphology(crystal, settings: Settings = None)

Calculate a morphology made of facets with equal growth rates. Useful as a starting point for further calculations.

class Settings(maximum_hkl_integer: int = 3, minimum_d_spacing: float = 0.5)

Settings for the Symmetry Allowed Morphology calculation.

property maximum_hkl_integer: int

The maximum absolute value of the Miller indices to consider

property minimum_d_spacing: float

The minimum d-spacing to consider

class ccdc.morphology.SeedMorphology(crystal, settings=None)

Morphology based on Hartman-Perdok theory using Periodic Bond Chains (PBCs).

This class models crystal growth using a hierarchical structure:

• GrowthFace: A crystal face defined by Miller indices (hkl)

  • Layer: A repeating growth unit perpendicular to the face

    • StepEdge: A growth step along a PBC direction

      • EdgeRow: Individual molecular rows within the step

        • KinkSite: Attachment sites at row terminations

class GrowthFace(growth_face)

A crystal face defined by Miller indices.

Represents a growth face containing layers, step edges, edge rows and kink sites.

class EdgeRow(_edge_row)

An individual molecular row within a step edge.

Edge rows represent the fundamental growth units that are completed by kink site attachment during spiral growth.

property average_width_per_growth_unit: float

Return the average width per growth unit along the edge row.

property energies: GrowthEnergies

Return all energies for this edge row as a GrowthEnergies object. > Note - Kink and Reverse Kink energies are zero for edge rows

property growth_status: GrowthStatus

Return the calculation status for this edge row.

property kink_sites: Tuple[KinkSite, ...]

Return the kink sites of the edge row

property kink_sites_by_direction: List[List[KinkSite]]

Return a dictionary of kink sites by growth direction

property parent_face: GrowthFace

Return the parent growth face of the edge row - Nice to have

property parent_step_edge: StepEdge

Return the parent step edge of the edge row - Nice to have

property row_frac_normal: Tuple[float, float, float]

Return the fractional row normal of the edge row.

property row_orth_normal: Tuple[float, float, float]

Return the orthogonal row normal of the edge row.

property row_orth_vector: Tuple[float, float, float]

Return the vector representing one full growth cycle along the edge row in orthogonal coordinates.

property step_direction: Tuple[int, int, int]

Return the step direction of the edge row.

class GrowthStatus(status)

Status information for a growth calculation element.

property is_bad: bool

Return True if the status is bad.

property is_good: bool

Return True if the status is good.

property reason: str

Return the reason for a bad status.

property status: str

Return the status as a human-readable string.

class KinkSite(_kink_site)

A kink site on an edge row.

Kink sites are the primary attachment points for molecules during crystal growth. They represent positions where a molecule can attach with maximum coordination to the existing crystal surface.

property energies: GrowthEnergies

Return all energies for this kink site as a GrowthEnergies object. > Note - Internal energies are zero for Kink sites

property growing_row: PeriodicBondChain

Return the PBC of the growing edge row.

property growth_status: GrowthStatus

Return the calculation status for this kink site.

property kink_direction: str

The direction of the kink site with respect ot the parent edge row

property kink_direction_vector: Tuple[int, int, int]

Return the kink growth direction relative to the unit cell. (UVW)

property kink_vacancy_position: Tuple[float, float, float]

Return the kink vacancy centroid in orthogonal coordinates.

property offset_kink_x: float

Return the offset of the kink site in x direction

property parent_row: EdgeRow

Return the parent edge row of the kink site

property preceding_molecule: Molecule | None

Return the molecule preceding the kink vacancy in the growth direction.

class Layer(_layer)

A single growth layer within a crystal face.

Represents the fundamental repeating unit perpendicular to the face normal. Contains step edges that define the layer’s growth directions.

In the Hartman-Perdok theory, layers correspond to F-faces (flat faces) when they contain two or more non-parallel PBCs.

property centroid_z_position: float

Return the centroid of the layer - relative to the layer perpendicular

property energies: GrowthEnergies

Return all energies for this layer as a GrowthEnergies object. Note - Step Edge, Reverse Step edge, Kink, Reverse Kink energies are zero for edge rows.

property growth_status: GrowthStatus

Return the calculation status for this layer.

property max_z_position: float

Return the maximum z value of the layer - where z is perpendicular to the layer

property min_z_position: float

Return the minimum z value of the layer - where z is perpendicular to the layer

property molecules: List[Molecule]

Return the molecule addresses in the layer

property parent_face: GrowthFace

Return the parent growth face of the layer

property periodic_bond_chains: List[PeriodicBondChain]

Return the periodic_bond_chains of the growth face

step_edge_by_direction(direction: Tuple[int, int, int]) → StepEdge

Return the step edge for the given growth direction. This will look for the step perpendicular to the specified direction.

property step_edge_directions: List[Tuple[int, int, int]]

Return the step edge growth directions of the layer

property step_edges: Tuple[StepEdge, ...]

Return the step edges of the layer

class StepEdge(_step_edge)

A growth step along a PBC direction.

Step edges represent an incomplete layer. They contain edge rows which in turn contain kink sites.

property average_propagation_length: float

Return the average propagation length per row in the step edge growth direction (in Angstroms).

property average_width_per_growth_unit: float

Return the average distance between growth units along the step direction (in Angstroms).

property edge_rows: Tuple[EdgeRow, ...]

Return the edge rows of the step edge.

property energies: GrowthEnergies

Return all energies for this step edge as a GrowthEnergies object. > Note - Kink and Reverse Kink energies are zero for Step edges

property growth_status: GrowthStatus

Return the calculation status for this step edge.

property parent_layer: Layer

Return the parent edge row of the edge row - Nice to have

property step_direction: Tuple[int, int, int]

Return the crystallographic direction along the step edge.

property step_frac_normal: Tuple[float, float, float]

Return the vector normal to the step edge in fractional coordinates.

property step_growth_direction: Tuple[int, int, int]

Return the crystallographic direction normal to the step edge.

property step_orth_normal: Tuple[float, float, float]

Return the vector normal to the step edge in cartesian coordinates.

property average_height_per_layer: float

Return the average height per layer in Angstroms. In practice this may differ from the interplanar spacing.

property face_frac_normal: Tuple[float, float, float]

Return the fractional face normal of the growth face.

property face_orth_normal: Tuple[float, float, float]

Return the orthogonal face normal of the growth face.

get_layer_containing_molecule(mol: Molecule) → Layer | None

Return the layer containing the given molecule address

property interplanar_spacing: float

Return the interplanar spacing of the growth face in Angstroms.

property layers: Tuple[Layer, ...]

Return the layers of the growth face.

property miller_indices: Tuple[int, int, int]

Return the Miller indices of the growth face.

property num_symmetry_layers: int

Return the number of layers implied by space group symmetry

property periodic_bond_chains: Tuple[PeriodicBondChain, ...]

Return the periodic bond chains of the growth face.

property status: GrowthStatus

Return the calculation status for this growth face.

class SeedFacet(facet, perpendicular_distance, miller_indices, growth_face=None)

A facet on a SeedMorphology with associated growth face information.

Extends the base Facet class to include a reference to the GrowthFace which contains the detailed growth calculation results.

property growth_face: GrowthFace | None

Return the growth face associated with this facet.

class Settings

Settings for controlling the SeedMorphology calculation.

property facets

Overloaded function from the MorphologyBase - Return the facets of the seed -

get_facet(hkl: Tuple[int, int, int]) → SeedFacet | None

Return the facet for the given Miller indices.

Parameters:

hkl – Miller indices as (h, k, l) tuple.

Returns:

The matching SeedFacet, or None if not found.

get_growth_face(hkl: Tuple[int, int, int]) → GrowthFace | None

Return the growth face for the given Miller indices.

Parameters:

hkl – Miller indices as (h, k, l) tuple.

Returns:

The matching GrowthFace, or None if not found.

property growth_faces: Tuple[GrowthFace, ...]

Return all calculated growth faces.

class ccdc.morphology.GrowthEnergies(terrace: float = 0.0, reverse_terrace: float = 0.0, step_edge: float = 0.0, reverse_step_edge: float = 0.0, kink: float = 0.0, reverse_kink: float = 0.0, internal: float = 0.0, bulk: float = 0.0, interfacial: float = 0.0)

Energy breakdown for a growth element.

All energy values are in kJ/mol.