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
Structureobject is aSuperCellobject augmented by an array of species numbers (or symbols). This array indicates a particular configuration of theSuperCell(a “decoration”), in a way which is compatible with the sublattices defined in theSuperCellobject.The
Structureclass inherits from theSuperCellclass. Therefore, all methods available to theSuperCellclass (and to theParentLatticeclass, from whichSuperCellinherits) are available to theStructureclass. Therefore, look at the documentation of the classesSuperCellandParentLatticefor additional methods for theStructureclass.- Parameters:
- super_cellSuperCell
SuperCellobject.- decorationlist of int, default None
Atomic numbers of the structure. Overriden by
sigmasandatomic_symbolsif notNone.- decoration_symbolslist of str, default None
Atomic symbols of the structure. Overriden by
sigmasif notNone.- 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 withdecoration = [10,25,25]ordecoration_symbols = ["Ne","Mn","Mn"]orsigmas = [0,0,1]. If notNone,sigmasoverridesdecorationanddecoration_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
filepathinstead. 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