The SuperCell class

Documentation of the SuperCell class. Every cluster expansion is based on the definition of a parent lattice, which indicates the cell vectors of the pristine (i.e. non substituted) crystal in its smallest possible primitive cell.

To every site of the parent lattice, a number of species are assigned (see below) indicating the substitutional type of the site.

Assigning the substitutions

List of all methods

class clusterx.super_cell.SuperCell(parent_lattice=None, p=None, sort_key=None, filepath=None, json_db_filepath=None, sym_table=False)

Build a super cell

A SuperCell object acts as a blue-print for the creation of structures with arbitrary decorations.

The SuperCell class inherits from the ParentLattice class. Therefore, all methods available to the ParentLattice class are available to the SuperCell class. Refer to the documentation of ParentLattice for more methods.

Parameters:
parent_latticeParentLattice object

In CELL, a super cell is a periodic repetition of a parent lattice object. This parameter defines such a parent lattice for the created super cell.

pint, or 1x3, 2x2, or 3x3 int array

Transformation matrix \(P\). The cartesian coordinates of the latttice vectors defining the created SuperCell object, are the rows of the matrix \(S\) defined by \(S = PV\) where the rows of \(V\) are the cartesian coordinates of the lattice vectors of the ParentLattice object. That is, the value of ParentLattice.get_cell(). The given matrix p must be compatible with the periodic boundary conditions of the parent lattice, i.e. the resulting super cell must not contain translations along the non-periodic directions.

sort_keylist of three int, optional

Create supercell object with sorted atomic coordinates

Example:sort_key=(2,1,0) will result in atoms sorted according to increasing z-coordinate first, increasing y-coordinate second, increasing x-coordinate third. Useful to get well ordered slab structures, for instance. Sorting can be changed by appropriately setting the sort_key argument, with the same effect as in the argument to itemgetter below:

from operator import itemgetter
sp = sorted(p, key=itemgetter(2,1,0))

here p is a Nx3 array of vector coordinates.

filepathstr, default None

The path of a JSON file containing a serialized SuperCell object, as generated by the SuperCell.serialize() method. This is the preferred argument.

json_db_filepathstr, default None

Deprecated. Use filepath instead. If provided, this argument will still be accepted but a deprecation warning will be issued.

Notes

as_dict()

Return dictionary with object definition

copy()

Return a copy

gen_random_decoration(nsubs, rng: Generator = Generator(PCG64) at 0x7F02D9C72F80)

Generate a random decoration of the super cell with given number of substitutions.

Parameters:
nsubsdict

The format of the dictionary is as follows:

{site_type1:[n11,n12,...], site_type2:[n21,n22,...], ...}

it indicates how many substitutional atoms of every kind (n#1, n#2, …) may replace the pristine species for sites of site_type#.

rngobject

NumPy random number generator with the function integers.

Returns:
decorationlist of int

list with the same length as the pristine structure. decoration[atom_idx] = species number sitting at site idx.

sigmaslist of int

sigma[atom_index] is an integer between 0 and M-1, where M is the total number of different species which may substitute an atom in this position.

gen_random_structure(nsubs=None, rng: Generator = Generator(PCG64) at 0x7F02D9C72EA0, track_indices=False, distribution='uniform')

Generate a random Structure with given number of substitutions.

Parameters:
nsubsNone, int or dict, default None

If dictionary, the nsubs argument must have the format {site_type0:[nsub01,nsub02,...], site_type1: ...} where site_type# and nsub## are, respectively, an integer indicating the site type index and the number of substitutional species of each kind, as returned by SuperCell.get_sublattice_types().

If integer, the SuperCell object must be correspond to a binary, i.e. the output of scell.is_nary(2) must be True. In this case, nsub indicates the number of substitutional atoms in the binary.

If None, the number of substitutions in each sublattice is generated at random.

rngobject

NumPy random number generator with the method integers.

track_indicesbool, default False

internally keep track which sites are occupied with which species, enables faster generation of MonteCarlo steps.

distributionstr, default “binomial”

The distribution of concentrations. “uniform” means each nsubs is equally likely. “binomial” means that for each site the substitution is drawn randomly, resulting in a binomial distribution of concentrations.

gen_structure(sigmas=None, track_indices=False)

Generate a Structure with given configuration.

Parameters:
sigmasndarray of int

sigmas[idx] must be the ocupation variable for crystal site idx. For instance, supose that:

ThisObject.get_sublattice_types()

returns {0:[14,13], 1:[56,47,38]}, and that:

ThisObject.get_tags()

returns [0,0,1,1,0], meaning that for atom idx=0,1,4 the sublattice types are 0 and for idx=2,3 the sublattice types is 1. Then, the argument sigmas=[0,1,0,2,1] will produce the configuration:

[14,13,56,38,13]
get_index()

Return index of the SuperCell

The index of the supercell is an integer number, equal to the super cell volume in units of the parent cell volume.

get_internal_translations()

Get internal translations of parent lattice in supercell, scaled to supercell

get_parent_lattice()

Return the parent lattice object which defines the supercell.

get_positions(wrap=False, **wrap_kw)

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

get_pristine_structure()

Return Structure object corresponding to pristine structure.

get_sym()

Get space symmetry of the super cell.

get_sym_platt()

Get space symmetry of the parent lattice.

get_symmetry_table(symprec=1e-12, tol=0.001)

Takes a SuperCell as a parameter and returns the final indices of every atom after all symmetry operations have been applied, see below: {(index of the atom, index of the symmetry operation): index of the atom after the symmetry operation}

get_transformation()

Return the transformation matrix that defines the supercell from the defining parent lattice.

plot()

Plot the pristine supercell object.

scell_from_dict()

Generates SuperCell object from a dictionary as returned by SuperCell.as_dict()

serialize(filepath='scell.json', fname=None)

Serialize a SuperCell object

Writes a ASE’s json database file containing a representation of the super cell. The created database can be visualized using ASE’s gui, e.g.:

ase gui scell.json
Parameters:
filepathstr

Output file name.

fnamestr

DEPRECATED, use filepath instead. Output file name.