site_analysis.trajectory

Trajectory analysis for tracking site occupations over time.

This module provides the Trajectory class, which is responsible for analyzing and tracking atom movements through crystallographic sites in a simulation trajectory.

The Trajectory class manages the relationship between atoms and sites, analyzes structures to assign atoms to sites, and records the movement history of atoms between sites over time.

Key functionality includes: - Assigning atoms to sites based on their positions in a structure - Tracking atom migrations between sites over a sequence of structures - Recording site occupation and transition data - Supporting different site definitions via appropriate SiteCollection types

Note

Trajectory objects should typically be created using the TrajectoryBuilder class rather than directly instantiated. The builder provides an interface for configuring all aspects of the trajectory:

>>> from site_analysis.builders import TrajectoryBuilder
>>> trajectory = (TrajectoryBuilder()
...              .with_structure(structure)
...              .with_mobile_species("Li")
...              .with_spherical_sites(centres=[[0.5, 0.5, 0.5]], radii=[2.0])
...              .build())

class Trajectory(sites: Sequence[Site], atoms: list[Atom])

Bases: object

Class for performing sites analysis on simulation trajectories.

analyse_structure(structure: Structure) → None

Analyse a structure to assign atoms to sites.

This delegates the analysis to the site collection’s analyse_structure method.

Parameters:

structure – A pymatgen Structure object to be analysed.

append_timestep(structure: Structure, t: int | None = None) → None

Append a new timestep to the trajectory.

This method: 1. Analyses the structure to assign atoms to sites 2. Updates the trajectory information for atoms and sites 3. Adds the timestep to the list of timesteps if provided

Parameters:

• structure – A pymatgen Structure object for this timestep.

• t – Optional timestep index to record. If None, no timestep is recorded.

assign_site_occupations(structure: Structure) → None

Assign atoms to sites for a specific structure.

This delegates the assignment to the site collection’s assign_site_occupations method.

Parameters:

structure – A pymatgen Structure object to be analysed.

property at

Shorthand for atoms_trajectory.

Returns:

The atoms_trajectory property.

atom_by_index(i: int) → Atom

Return the atom with the specified index.

Parameters:

i – Index of the atom to return.

Returns:

The Atom object with the specified index.

property atom_sites: list[int | None]

Return the sites that each atom currently occupies.

Returns:

A list of site indices (or None for unoccupied atoms), one for each atom.

property atoms_trajectory

Return the trajectory of all atoms.

Returns:

A list of lists, where each inner list represents a timestep and contains the site indices occupied by each atom at that timestep.

reset() → None

Reset the trajectory.

This clears all trajectory information for atoms and sites and resets the timesteps list.

site_by_index(i: int) → Site

Return the site with the specified index.

Parameters:

i – Index of the site to return.

Returns:

The Site object with the specified index.

site_coordination_numbers() → Counter

Return the coordination numbers of all sites.

Returns:

A Counter object mapping coordination numbers to their frequencies.

site_labels() → list[str | None]

Return the labels of all sites.

Returns:

A list of site labels (or None for sites without labels).

property site_occupations: list[list[int]]

Return the atoms occupying each site.

Returns:

A list of lists, where each inner list contains the indices of atoms occupying a site.

site_summaries(metrics: list[str] | None = None) → list[dict]

Generate summary statistics for all sites in this trajectory.

Parameters:

metrics – List of metrics to include for each site. None returns default metrics for each site.

Returns:

List of summary dicts, one per site, in site order.

property sites_trajectory

Return the trajectory of all sites.

Returns:

A list of lists, where each inner list represents a timestep and contains the atom indices occupying each site at that timestep.

property st

Shorthand for sites_trajectory.

Returns:

The sites_trajectory property.

trajectory_from_structures(structures: Sequence[Structure], progress: bool = False) → None

Generate a trajectory from a list of structures.

Parameters:

• structures – The structures to analyse, one per timestep.

• progress – Show a progress bar. Automatically selects the appropriate widget for terminal or notebook environments.

transition_counts_by_label(*, keys: Sequence[str] | None = None) → TransitionTable[str]

Return label-aggregated transition counts as a TransitionTable.

Sites without labels are skipped. A warning is emitted if any transitions are dropped as a result.

Parameters:

keys – Optional key ordering for rows and columns. If None, keys are sorted. Must be a permutation of the default keys.

Returns:

A TransitionTable of integer counts keyed by site label.

Raises:

ValueError – If keys does not match the default key set, or if a site has a transition to an unknown site index.

transition_counts_by_site(*, keys: Sequence[int] | None = None) → TransitionTable[int]

Return per-site transition counts as a TransitionTable.

Parameters:

keys – Optional key ordering for rows and columns. If None, keys are sorted. Must be a permutation of the default keys.

Returns:

A TransitionTable of integer counts keyed by site index.

Raises:

ValueError – If keys does not match the default key set, or if a site has a transition to an unknown site index.

transition_probabilities_by_label(*, keys: Sequence[str] | None = None) → TransitionTable[str]

Return label-aggregated row-normalised transition probabilities.

Each row is normalised so that its values sum to 1.0. Rows with no outgoing transitions remain as all zeros. Sites without labels are skipped. A warning is emitted if any transitions are dropped.

Parameters:

keys – Optional key ordering for rows and columns. If None, keys are sorted. Must be a permutation of the default keys.

Returns:

A TransitionTable of float probabilities keyed by site label.

Raises:

ValueError – If keys does not match the default key set, or if a site has a transition to an unknown site index.

transition_probabilities_by_site(*, keys: Sequence[int] | None = None) → TransitionTable[int]

Return per-site row-normalised transition probabilities.

Each row is normalised so that its values sum to 1.0. Rows with no outgoing transitions remain as all zeros.

Parameters:

keys – Optional key ordering for rows and columns. If None, keys are sorted. Must be a permutation of the default keys.

Returns:

A TransitionTable of float probabilities keyed by site index.

Raises:

ValueError – If keys does not match the default key set, or if a site has a transition to an unknown site index.

write_site_summaries(filename: str, metrics: list[str] | None = None) → None

Write site summaries to a JSON file.

Parameters:

• filename – Path to output JSON file.

• metrics – List of metrics to include for each site. None returns default metrics for each site.

update_occupation(site, atom)

Update the occupation record for a site and atom pair.

This utility function updates the occupation records when an atom is assigned to a site. It:

1. Adds the atom’s index to the site’s list of contained atoms

2. Sets the atom’s in_site attribute to the site’s index

Parameters:

• site (Site) – The site that contains the atom

• atom (Atom) – The atom to be assigned to the site

Returns:

None

Note

This is a simplified version of the update_occupation method in SiteCollection classes, used for direct assignments without tracking transitions.