site_analysis.atom

Representation of atoms and utilities for atom creation.

This module provides the Atom class, which represents a single atom in a crystal structure, along with utility functions for creating collections of atoms.

The Atom class maintains information about an atom’s identity (index), position (fractional coordinates), site assignment, and movement history (trajectory).

The module also provides helper functions to create Atom objects from various input forms: - atoms_from_structure: Create atoms from a Structure based on species - atoms_from_species_string: Create atoms for a specific species in a Structure - atoms_from_indices: Create atoms with specific atom indices

class Atom(index: int, species_string: str | None = None)

Bases: object

Represents a single persistent atom during a simulation.

index

Unique numeric index identifying this atom.

Type:

int

in_site

Site index for the site this atom currently occupies.

Type:

int

trajectory

list of site indices occupied at each timestep.

Type:

list

Note

The atom index is used to identify it when parsing structures, so needs to be e.g. the corresponding Site index in a Pymatgen Structure.

as_dict() → dict[str, Any]

assign_coords(frac_coords: ndarray) → None

Assign fractional coordinates to this atom from a coordinate array.

Parameters:

frac_coords – Full fractional coordinate array, shape (N, 3), from which this atom’s coordinates are extracted using self.index.

property frac_coords: ndarray

Getter for the fractional coordinates of this atom.

Raises:

AttributeError – if the fractional coordinates for this atom have not been set.

classmethod from_dict(d: dict) → Atom

classmethod from_file(filename)

classmethod from_str(input_string: str) → Atom

Initiate an Atom object from a JSON-formatted string.

Parameters:

input_string (str) – JSON-formatted string.

Returns:

(Atom)

property most_recent_site: int | None

Return the most recent non-None site assigned to this atom.

Returns:

The site index of the most recently assigned site, or None if no site has been assigned yet.

reset() → None

Reset the state of this Atom.

Clears the in_site, trajectory, and _recent_sites attributes.

Returns:

None

to(filename: str | None = None) → str

update_recent_site(site_index: int) → None

Record a site visit, updating the recent sites tracker.

Only updates if the site differs from the current most recent, so repeated assignments to the same site are ignored.

Parameters:

site_index – The site index being assigned.

atoms_from_indices(indices: list[int]) → list[Atom]

Create Atom objects with the specified indices.

This function creates a list of Atom objects with indices exactly matching the provided list. This is useful when you already know which atoms you want to track by their indices.

Parameters:

indices – A list of integer indices to use for the Atom objects

Returns:

A list of Atom objects, one for each index in the input list. The Atom objects will have their index set but no other attributes.

Note

This function does not check for uniqueness of indices. If the input contains duplicate indices, the result will contain multiple Atom objects with the same index.

atoms_from_species_string(structure: Structure, species_string: str) → list[Atom]

Create Atom objects for all atoms of a specific species in a structure.

This function creates a list of Atom objects for each atom in the structure that matches the given species string.

Parameters:

• structure – A pymatgen Structure containing the atoms

• species_string – The species to match (e.g., “Li”, “O”)

Returns:

A list of Atom objects, one for each matching atom in the structure. The Atom objects will have their index set to the corresponding atom’s index in the structure, but will not have coordinates assigned.

atoms_from_structure(structure: Structure, species_string: list[str] | str) → list[Atom]

Create Atom objects for atoms of specified species in a structure.

Similar to atoms_from_species_string, but accepts either a single species string or a list of species strings, and sets both the species_string attribute and fractional coordinates for each atom.

Parameters:

• structure – A pymatgen Structure containing the atoms

• species_string – Either a single species string (e.g., “Li”) or a list of species strings (e.g., [“Li”, “Na”])

Returns:

A list of Atom objects, one for each matching atom in the structure. Each Atom will have its index, species_string, and _frac_coords set.