site_analysis.reference_workflow

Reference-based workflow for defining sites in crystal structures.

This package provides tools for defining crystallographic sites in a target structure based on coordination environments identified in a reference structure.

The main entry point is the ReferenceBasedSites class, which orchestrates the entire workflow of structure alignment, coordination environment finding, index mapping, and site creation.

Example:

from site_analysis.reference_workflow import ReferenceBasedSites

# Create reference-based sites workflow
rbs = ReferenceBasedSites(
    reference_structure=reference_structure,
    target_structure=target_structure
)

# Create polyhedral sites
sites = rbs.create_polyhedral_sites(
    center_species="Li",
    vertex_species="O",
    cutoff=3.0,
    n_vertices=4
)

Reference-based workflow for defining sites in crystal structures.

This module provides the ReferenceBasedSites class, which is the main orchestrator for defining crystallographic sites in a target structure based on coordination environments identified in a reference structure. This approach is particularly useful for:

  1. Analyzing structures with distortions relative to an ideal reference

  2. Tracking specific site types across different structures or simulation frames

  3. Creating consistent site definitions across diverse structures

The ReferenceBasedSites class integrates several components to accomplish this workflow: - StructureAligner: Aligns the structures to find the optimal translation vector - CoordinationEnvironmentFinder: Identifies coordination environments in the reference - IndexMapper: Maps atom indices between reference and target structures - SiteFactory: Creates appropriate site objects in the target structure

This approach lets users define sites based on ideal coordination environments in a reference structure, then create corresponding sites in real or distorted structures where those same environments might be harder to identify directly.

class ReferenceBasedSites(reference_structure: Structure, target_structure: Structure, align: bool = True, align_species: list[str] | None = None, align_metric: str = 'rmsd', align_algorithm: str = 'Nelder-Mead', align_minimizer_options: dict[str, Any] | None = None, align_tolerance: float = 0.0001)[source]

Bases: object

Main orchestrator for defining sites using a reference structure approach.

This class ties together all components needed to define sites in crystal structures using a reference structure as a template:

  1. StructureAligner - to align the target structure to the reference

  2. CoordinationEnvironmentFinder - to find coordination environments in the reference

  3. IndexMapper - to map environments from reference to target structure

  4. SiteFactory - to create appropriate site objects

reference_structure

Reference structure defining ideal coordination environments.

target_structure

Target structure where sites will be created.

aligned_structure

Reference structure translated to match the target (None if align=False).

translation_vector

Translation vector used for alignment (None if align=False).

alignment_metrics

Metrics describing quality of structure alignment (None if align=False).

create_dynamic_voronoi_sites(center_species: str, reference_species: str | list[str], cutoff: float, n_reference: int, label: str | None = None, labels: list[str] | None = None, target_species: str | list[str] | None = None, use_reference_centers: bool = True) → list[DynamicVoronoiSite][source]

Create DynamicVoronoiSite objects based on coordination environments in the reference structure.

Parameters:

  • center_species – Species at the center of coordination environments

  • reference_species – Species of reference atoms used to define the dynamic site centers

  • cutoff – Cutoff distance for finding reference atoms (required)

  • n_reference – Number of reference atoms per site (required)

  • label – Label to apply to all created sites. Default is None.

  • labels – List of labels for each site. Default is None.

  • target_species – Species to map to in the target structure. Default is None.

  • use_reference_centers – Whether to use reference centers for PBC handling. See TrajectoryBuilder.with_polyhedral_sites() for details. Default is True.

Returns:

List of DynamicVoronoiSite objects

Raises:

ValueError – If coordination environments cannot be found or mapped, or if both label and labels are provided.

create_polyhedral_sites(center_species: str, vertex_species: str | list[str], cutoff: float, n_vertices: int, label: str | None = None, labels: list[str] | None = None, target_species: str | list[str] | None = None, use_reference_centers: bool = True) → list[PolyhedralSite][source]

Create PolyhedralSite objects based on coordination environments in the reference structure.

Parameters:

  • center_species – Species at the center of coordination environments

  • vertex_species – Species at vertices of coordination environments

  • cutoff – Cutoff distance for coordination environment (required)

  • n_vertices – Number of vertices per environment (required)

  • label – Label to apply to all created sites. Default is None.

  • labels – List of labels for each site. Default is None.

  • target_species – Species to map to in the target structure. Default is None.

  • use_reference_centers – Whether to use reference centers for PBC handling. See TrajectoryBuilder.with_polyhedral_sites() for details. Default is True.

Returns:

List of PolyhedralSite objects

Raises:

ValueError – If coordination environments cannot be found or mapped, or if both label and labels are provided.

Structure alignment tools for comparing and superimposing crystal structures.

This module provides the StructureAligner class, which finds the optimal translation vector to superimpose one crystal structure onto another. This alignment is important for:

  1. Comparing structures from different sources with different coordinate origins

  2. Analyzing structural changes while accounting for rigid translations

  3. Preparing structures for site mapping in reference-based workflows

The alignment algorithm optimizes a translation vector to minimise distances between corresponding atoms in the two structures, considering periodic boundary conditions. It supports different optimisation metrics (RMSD or maximum atom distance) and can align based on specific atom species.

This module is a key component of the reference-based workflow for defining sites in one structure based on a template from another structure.

class StructureAligner[source]

Bases: object

Aligns crystal structures via translation optimization.

This class provides methods to align a reference structure to a target structure by finding the optimal translation vector that minimizes distances between corresponding atoms, considering periodic boundary conditions.

align(reference: Structure, target: Structure, species: list[str] | None = None, metric: str = 'rmsd', tolerance: float = 0.0001, algorithm: str = 'Nelder-Mead', minimizer_options: dict[str, Any] | None = None) → tuple[Structure, ndarray, dict[str, float]][source]

Align reference structure to target structure via translation.

Finds the optimal translation vector that minimises distances between corresponding atoms in the two structures.

Parameters:

  • reference – Reference structure to translate.

  • target – Target structure to align to.

  • species – Species to include in alignment. If None, all species present in both structures are used.

  • metric – Distance metric to optimise (‘rmsd’ or ‘max_dist’).

  • tolerance – Convergence tolerance for the optimiser.

  • algorithm – Optimisation algorithm (‘Nelder-Mead’ or ‘differential_evolution’).

  • minimizer_options – Additional options passed to the optimiser.

Returns:

A tuple of (aligned_structure, translation_vector, metrics) where aligned_structure is the translated reference, translation_vector is the applied translation in fractional coordinates, and metrics is a dictionary of alignment quality measures.

Raises:

ValueError – If structures have incompatible compositions or if optimisation fails.

Coordination environment finder for crystal structures.

This module provides the CoordinationEnvironmentFinder class, which identifies coordination environments in crystal structures based on species, distance cutoffs, and coordination numbers. A coordination environment consists of a central atom surrounded by a specific number of coordinating atoms within a given distance.

The CoordinationEnvironmentFinder is used to identify specific site types in a reference structure, such as tetrahedral, octahedral, or other coordination environments. These environments can then be mapped to a target structure, enabling the creation of corresponding sites.

Key features include: - Finding atoms with exactly the specified coordination environment - Supporting both single and multiple coordinating species - Filtering by centre atom species and coordinating atom species - Customising coordination requirements per centre atom

This module is a key component of the reference-based workflow, providing the initial identification of coordination environments that will be used to define sites in both reference and target structures.

class CoordinationEnvironmentFinder(structure: Structure)[source]

Bases: object

Finds coordination environments in a structure.

find_environments(center_species: str, coordination_species: str | list[str], n_coord: int, cutoff: float) → dict[int, list[int]][source]

Find coordination environments in the structure.

Locates atoms of center_species and finds environments where these atoms are coordinated by exactly n_coord atoms of coordination_species within the specified cutoff distance.

Parameters:

  • center_species – Species at the centre of the coordination environment.

  • coordination_species – Species of the coordinating atoms (can be a string or a list of strings).

  • n_coord – Number of coordinating atoms required for each environment.

  • cutoff – Maximum distance (in Angstroms) for atoms to be considered coordinating.

Returns:

A dictionary mapping centre atom indices to lists of coordinating atom indices.

Raises:

ValueError – If center_species or coordination_species are not found in the structure.

Index mapping between reference and target crystal structures.

This module provides the IndexMapper class, which maps coordinating atom indices from a reference structure to corresponding atoms in a target structure. This mapping is essential when transferring site definitions from one structure to another, particularly when atom orderings differ or when structures have been distorted.

The IndexMapper uses a distance-based approach to find the closest corresponding atoms in the target structure for each reference atom, considering periodic boundary conditions. It enforces a 1:1 mapping constraint to ensure that each reference atom maps to a distinct target atom, which is necessary for preserving the topology of coordination environments.

The mapping can be filtered by atom species to ensure that atoms map only to atoms of the same species, which is important for maintaining chemical validity when mapping between structures with mixed compositions.

This module is a core component of the reference-based workflow, enabling the transfer of site definitions between different structures or timesteps in a simulation.

class IndexMapper[source]

Bases: object

Maps coordinating atom indices between reference and target crystal structures.

Used to translate coordination environments defined in an ideal reference structure to corresponding atoms in a target structure, handling permutations and structural distortions via distance-based matching.

The mapper verifies 1:1 correspondence between reference and target atoms, ensuring each coordinating position maps to exactly one target atom. If this constraint is violated, a ValueError is raised.

map_coordinating_atoms(ref_frac_coords: ndarray, target_frac_coords: ndarray, lattice_matrix: ndarray, ref_coordinating: list[list[int]], target_species: list[str] | None = None, species_filter: str | list[str] | None = None) → list[list[int]][source]

Map coordinating atom indices from reference to target structure.

Parameters:

  • ref_frac_coords – Fractional coordinates of the reference structure, shape (N, 3).

  • target_frac_coords – Fractional coordinates of the target structure, shape (M, 3).

  • lattice_matrix – Lattice matrix (3x3) for distance calculations.

  • ref_coordinating – List of coordinating atom index lists from reference. Each sublist contains indices of atoms that define a site.

  • target_species – Full species list for all atoms in the target structure. Required when using species_filter.

  • species_filter – Optional filter for which species to map to. If specified, only maps to atoms of these species in the target structure.

Returns:

List of coordinating atom index lists mapped to the target structure. Maintains the same structure as input but with updated indices.

Raises:

ValueError – If 1:1 mapping cannot be achieved (e.g., missing atoms, ambiguous distances, or insufficient target atoms in target structure).

Factory for creating site objects from coordination environments.

This module provides the SiteFactory class, which creates different types of site objects based on coordination environments defined by atom indices in a crystal structure. This factory simplifies the creation of complex site objects by handling the details of vertex coordinate assignment and validation.

The SiteFactory supports creating: - PolyhedralSite objects: Sites defined by polyhedra with vertices at specific atom positions - DynamicVoronoiSite objects: Sites with centers dynamically calculated from reference atom positions

It provides validation of coordination environments, ensures consistent labeling, and manages the initialisation of site objects with the appropriate structural data.

This module is part of the reference-based workflow, which creates sites in one structure based on coordination environments identified in a reference structure.

class SiteFactory(structure: Structure)[source]

Bases: object

Factory for creating site objects from coordination environments.

This class creates PolyhedralSite or DynamicVoronoiSite objects from environments defined as lists of atom indices.

structure

The structure providing atom coordinates.

Type:

Structure

create_dynamic_voronoi_sites(environments: list[list[int]], reference_centers: list[ndarray] | None = None, label: str | None = None, labels: list[str] | None = None) → list[DynamicVoronoiSite][source]

Create DynamicVoronoiSite objects from coordination environments.

Parameters:

  • environments – List of environments, where each environment is a list of atom indices defining the reference atoms for a dynamic Voronoi site.

  • reference_centers – Optional list of reference centres for PBC handling. If provided, must have the same length as environments.

  • label – Optional label to assign to all sites.

  • labels – Optional list of labels, one for each environment.

Returns:

List of DynamicVoronoiSite objects.

Raises:

ValueError – If environments are invalid.

create_polyhedral_sites(environments: list[list[int]], reference_centers: list[ndarray] | None = None, label: str | None = None, labels: list[str] | None = None) → list[PolyhedralSite][source]

Create PolyhedralSite objects from coordination environments.

Parameters:

  • environments – List of environments, where each environment is a list of atom indices defining the vertices of a polyhedral site.

  • reference_centers – Optional list of reference centres for PBC handling. If provided, must have the same length as environments.

  • label – Optional label to assign to all sites.

  • labels – Optional list of labels, one for each environment.

Returns:

List of PolyhedralSite objects.

Raises:

ValueError – If environments are invalid, if minimum vertex count is not met, or if reference_centers length doesn’t match environments.