The Structure class

Initialization and methods

class clusterx.structure.Structure(super_cell: SuperCell, decoration: Sequence | None = None, decoration_symbols: Sequence | None = None, sigmas: Sequence | None = None, track_indices: bool = False)

Structure class

A Structure object is a SuperCell object augmented by an array of species numbers (or symbols). This array indicates a particular configuration of the SuperCell (a “decoration”), in a way which is compatible with the sublattices defined in the SuperCell object.

The Structure class inherits from the SuperCell class. Therefore, all methods available to the SuperCell class (and to the ParentLattice class, from which SuperCell inherits) are available to the Structure class. Therefore, look at the documentation of the classes SuperCell and ParentLattice for additional methods for the Structure class.

Parameters:
super_cellSuperCell

SuperCell object.

decorationlist of int, default None

Atomic numbers of the structure. Overriden by sigmas and atomic_symbols if not None.

decoration_symbolslist of str, default None

Atomic symbols of the structure. Overriden by sigmas if not None.

sigmaslist of int, default None

Every site in a supercell is represented by an array of the species that can occupy the site. Thus, taking as reference these arrays, a possible representation of a decoration is by indicating the ordinal number of the corresponding species. For instance, if the “sites”-based representation of the SuperCell is {0: [10,11], 1: [25], 2: [12,25]} (*), then equivalent structures are obtained with decoration = [10,25,25] or decoration_symbols = ["Ne","Mn","Mn"] or sigmas = [0,0,1]. If not None, sigmas overrides decoration and decoration_symbols.

track_indicesbool

Whether to keep maps of site indices by sublattice and species.

Notes

backup_arrays()

Backup current state of arrays for potential restoration later.

flip(atom_index: int, sigma_initial: int, sigma_final: int, site_type: int | None = None) → None

Perform a flip on sublattice site_type from sigma_initial to sigma_final.

classmethod from_dict(structure_dict: dict) → Structure

Create a Structure object from a dictionary object.

This method is used to reconstruct a Structure from a Python dictionary that was obtained by loading a JSON file previously created using the Structure.serialize() method.

Parameters:
structure_dictdict

A dictionary containing the deserialized structure data.

Returns:
Structure

An instance of the Structure class initialized with the given data.

classmethod from_file(filepath: str, parent_lattice: ParentLattice | None = None) → Structure

Load a Structure object from a serialized file.

Supports both binary and JSON-based serialization formats. The file is expected to have been created using the Structure.serialize() method.

Supported formats: - .pickle: Full Python object serialization using pickle. - .json : ASE-compatible JSON database file. - .xyz : extended xyz file.

Parameters:
filepathstr

Path to the serialized file. The format is inferred from the file extension.

parent_latticeParentLattice, optional

Provide ParentLattice if it is missing in the .xyz structure file for some reason. Overwrites ParentLattice from the structure file.

Returns:
Structure

A reconstructed Structure object based on the contents of the file.

Raises:
ValueError

If the file extension is not supported.

get_atomic_numbers() → ndarray

Get decoration array

get_atoms(ignore_observer_atoms: bool = False) → Atoms

Get Atoms object corresponding to the Structure object

get_chemical_symbols()

Get decoration array

get_degeneracy() → int

Calculate and return the degeneracy of the structure.

get_fractional_concentrations()

Get fractional concentration of each species on each sublattice

This function returns a dictionary. The keys of the dictionary, denoted with \(t\), are the site types that admit substitution (i.e., those returned by Structure.get_substitutional_tags()). The values of the dictionary are arrays of float, denoted with vectors \(\mathbf{c}_t\). The coordinates of \(\mathbf{c}_t\) (\(c_{\sigma t}\)) are equal to \(n_{\sigma t}/n_t\), where \(\sigma \in [ 0,m-1]\), \(n_{\sigma t}\) is the number of atoms of species \(\sigma\) occupying sites of type \(t\), and \(n_t\) is the total number of sites of type \(t\). The coordinates of \(\mathbf{c}_t\) sum up to \(1\).

get_positions(wrap=False, **wrap_kw)

This method caches positions, otherwise ASE would copy large arrays.

get_random_flip(site_type: int | None = None, sigma_initial: int | None = None, sigma_final: int | None = None, rng: Random = <module 'random' from '/users/sol/srigamonti/.local/share/uv/python/cpython-3.13.11-linux-x86_64-gnu/lib/python3.13/random.py'>) → tuple[int, int, int, int]

Get a random flip index in given sublattice with given sigmas.

Parameters:
site_typeint (required)

Indicate index of sub-lattice where atom is to be flipped.

sigma_initialint or None, optional, default None

Specifies which atomic species (denoted by the occupation variable sigma) in the sublattice should be flipped.

  • For an n-ary system with sigma values in the range [0, …, n-1]: If sigma_initial = i, the species i is flipped to a randomly chosen different species j ≠ i from the same range, or to sigma_final, if given.

  • If None (default): A species i is randomly selected and flipped to a randomly chosen j ≠ i, or to sigma_final, if given.

Examples:

  • Binary system (n = 2, sigma ∈ {0, 1}): sigma_initial = 0 flips to 1; sigma_flip = 1 flips to 0.

  • Ternary system (n = 3, sigma ∈ {0, 1, 2}): sigma_intial = 1 flips to either 0 or 2, chosen randomly.

rngrandom number generator with .choice method
Returns:
atom_indexint
sigma_initialint
sigma_finalint
site_typeint
get_random_swap(site_types: list[int] | None, rng: Random = <module 'random' from '/users/sol/srigamonti/.local/share/uv/python/cpython-3.13.11-linux-x86_64-gnu/lib/python3.13/random.py'>) → tuple[int, int, int]

Get indices of two randomly selected atoms in randomly selected sub-lattice.

First, a sublattice from the site_types array is picked at random. Second, a pair of species from the selected sublattice are swapped.

See also Structure.get_random_swap_binary()

Parameters:
site_typesint array (required)

Indicate indices of sub-lattices to be considered in the random sub-lattice selection.

get_random_swap_binary(site_type: int | None = None, sigma_initial: int = 0, sigma_final: int = 1, rng: Random = <module 'random' from '/users/sol/srigamonti/.local/share/uv/python/cpython-3.13.11-linux-x86_64-gnu/lib/python3.13/random.py'>) → tuple[int, int, int]

Return indices and sigmas of two randomly selected atoms in given sub-lattice.

Parameters:
site_typeint (required)

Indicate index of sub-lattice where atoms are to be swapped.

sigma_initialint, default 0

Sigma of site i before swap

sigma_finalint, default 0

Sigma of site i after swap

Returns:
tuple of int

indices i, j and sigmas sigmas[i], sigmas[j] of swap sites (after swap).

get_reduced_structure(index: int) → Structure

Return a reduced structure and reduced index. Given transformation p, around site index.

Only local offsets are cached, so additional storage is independent of the full supercell size for a fixed reduced shape. The cache is rebuilt when either grid shape changes and is created lazily for older pickles.

get_sigmas()

Return decoration array in terms of sigma variables.

get_supercell()

Return SuperCell member of the Structure

get_symbols_per_site_type()

Get fractional concentration of each species on each sublattice

This function returns a dictionary. The keys of the dictionary, denoted with \(t\), are the site types that admit substitution (i.e., those returned by Structure.get_substitutional_tags()). The values of the dictionary are arrays of float, denoted with vectors \(\mathbf{c}_t\). The coordinates of \(\mathbf{c}_t\) (\(c_{\sigma t}\)) are equal to \(n_{\sigma t}/n_t\), where \(\sigma \in [ 0,m-1]\), \(n_{\sigma t}\) is the number of atoms of species \(\sigma\) occupying sites of type \(t\), and \(n_t\) is the total number of sites of type \(t\). The coordinates of \(\mathbf{c}_t\) sum up to \(1\).

init_reduced_structure(scell_reduced: SuperCell)

Initialize reduced structure, which has the same parent lattice as self, but with SuperCell scell_reduced.

restore_arrays()

Restore arrays from backup.

serialize(filepath='structure.json', fmt=None, fname=None)

Save the structure to a file in the specified format.

Parameters:
fmtstr, optional

File format for output (default is “json”). All formats supported by ase.io.write() are accepted. See: https://wiki.fysik.dtu.dk/ase/ase/io/io.html#ase.io.write

filepathstr, optional

Path to the output file (default is “structure.json”).

fnamestr, optional

DEPRECATED. Use filepath instead. This argument will be removed in a future version.

set_calculator(calculator)

Set Calculator object for structure.

swap(i: int, j: int, site_type: int | None = None) → None

Swap sigmas at indices i and j with matching sublattices site_type.

track_indices() → None

Start tracking indices.

This method needs to be called if track_indices was not called during intialization, but an index map is needed for efficient canonical sampling.

update_decoration(decoration)

Update decoration of the structure object

Parameters:
decoration