The Structure class

Initialization and methods

class clusterx.structure.Structure(super_cell, decoration=None, decoration_symbols=None, sigmas=None, mc=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.


super_cell: SuperCell object

SuperCell object.

decoration: list of int (default: None)

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

decoration_symbols: list of strings (default: None)

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

sigmas: list 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.

mc: Boolean (default: False)

whether the initialization of the Structure object is in the context of a Monte Carlo (MC) run. Setting it to True affects the behavior of the method Structure.swap_random_binary()

(*) This means, crystal site 0 can host any of the species 10 (Neon) or 11 (Sodium), etc. See, e.g., ParentLattice.get_sites().



Get decoration array


Get Atoms object corresponding to the Structure object


Get decoration array


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)

Get array of positions.


wrap: bool

wrap atoms back to the cell before returning positions

wrap_kw: (keyword=value) pairs

optional keywords pbc, center, pretty_translation, eps, see ase.geometry.wrap_positions()


Return decoration array in terms of sigma variables.


Return SuperCell member of the Structure

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

Serialize structure object

Wrapper for ASEs write method.


fmt: string (default: json)

Indicate the file format of the output file. All the formats accepted by method are valid (see corresponding documentation in

filepath: string (default: structure.json)

DEPRECATED, use filepath instead file name (may includ absolute or relative path).

fname: string (default: None)

DEPRECATED, use filepath instead. File name (may includ absolute or relative path).


Set Calculator object for structure.


Swap 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.

Structure object is modified by the swap. The swapped Structure object is also returned.

See also Structure.swap_random_binary()


site_types: integer array (required)

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

swap_random_binary(site_type, sigma_swap=[0, 1])

Swap two randomly selected atoms in given sub-lattice.


site_type: integer (required)

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

sigma_swap: two-component integer array (default: [0,1])

Indicate which atomic species (represented by sigma variables) in the sublattice are swapped. E.g., in the case of a binary, this can only be [0,1], while for a ternary, this can be [0,1], [0,2], [1,2] (and, obviously, the exchanged ones, e.g. [1,0]).



Update decoration of the structure object