Atoms
What is an Atom in site_analysis?
In site_analysis, an Atom represents a single mobile ion that is tracked throughout a simulation. Unlike conventional molecular dynamics representations that simply store coordinates, the Atom class maintains information about site occupation and movement history, enabling analysis of diffusion pathways.
Each Atom has a unique index that corresponds to its position in the original structure and maintains its identity across timesteps as its position changes. This persistent identity allows the package to track how ions move between sites over time.
Core Atom Properties
The Atom class maintains several key attributes:
index: Unique numerical identifier that matches the atom’s index in the source structure
species_string: Chemical symbol of the atom (e.g., “Li”, “Na”)
in_site: Index of the site this atom is inside in the most recently analysed structure (or None if it is in no site)
frac_coords: Current fractional coordinates in the crystal structure
trajectory: List of site indices (or None values) that this atom has occupied over time (its committed sites when the trajectory uses commitment)
committed_site: Site index of the site this atom is committed to when the trajectory uses commitment (or None)
geometric_trajectory: List of the sites this atom was inside at each timestep, recorded only when the trajectory uses commitment
These properties provide the foundation for analysing how atoms move through the crystal structure during a simulation.
Atoms and Site Occupation
The relationship between atoms and sites is bidirectional:
Each atom records which site it is inside via its
in_siteattributeEach site records which atoms it currently contains via its
contains_atomslist
With commitment, an atom’s trajectory records committed sites, and contains_atoms holds the committed atoms after append_timestep() and the atoms inside each site after analyse_structure() alone. The matching atom attribute is committed_site; in_site is the site the atom is inside.
When analysing a structure, the appropriate site collection determines which atoms belong to which sites.
Tracking Atom Trajectories
As a simulation progresses, an atom’s trajectory is built by recording the sequence of sites it occupies at each timestep. This trajectory is stored as a list of site indices or None values, where each entry corresponds to a timestep in the simulation:
atom.trajectory = [5, 5, 5, 12, 12, 12, 12, 15, 15, ...]
In this example, the atom started in site 5, moved to site 12 after three timesteps, and then to site 15 after four more timesteps.
If an atom is not in any site at a particular timestep (e.g., it’s in a gap between sites), the trajectory will contain None for that timestep. The in_site attribute is also set to None when an atom is not in any site, ensuring that both the current state and the trajectory consistently represent periods when an atom is not assigned to any site. With commitment on, an atom between sites keeps its committed site in committed_site and its trajectory, while in_site is None; see the commitment guide.
Creating and Managing Atoms
In most workflows, atoms are created automatically by the TrajectoryBuilder when you specify mobile species:
trajectory = (TrajectoryBuilder()
.with_structure(structure)
.with_mobile_species("Li") # Creates Atom objects for all Li ions
.with_polyhedral_sites(...)
.build())
However, the package provides several utility functions for creating atoms in different ways:
atoms_from_structure: Create atoms for specified species in a structure
atoms_from_species_string: Create atoms for a specific species in a structure
atoms_from_indices: Create atoms with specific atom indices
Bulk Analysis of Atom Movements
The Trajectory class provides methods to analyse the collective behaviour of atoms:
geometric_sites: Returns the site each atom is inside
committed_sites: Returns each atom’s committed site, with commitment
atoms_trajectory: Returns the site occupation history for all atoms over time (the committed sites with commitment)
geometric_trajectory: Returns the sites the atoms were inside at each timestep (the same as
atoms_trajectorywithout commitment)
These methods facilitate analysis of diffusion patterns, correlations between atom movements, and statistical properties of ion migration.
Atoms vs. Sites Perspective
site_analysis allows you to analyse diffusion from two complementary perspectives:
Atom-centric: Following individual atoms as they move between sites
Site-centric: Analysing which atoms occupy each site over time
The atom-centric view is useful for tracking specific ions and their pathways, while the site-centric view helps identify preferred sites, occupation probabilities, and transition frequencies.