The SuperCell class¶

Assigning the substitutions¶

List of all methods¶

class clusterx.super_cell.SuperCell(parent_lattice=None, p=None, sort_key=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_lattice: ParentLattice 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.

p: integer, or 1x3, 2x2, or 3x3 integer 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_key: list of three integers, 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.

json_db_filepath: string (default: None)

Overrides all the above. Used to initialize from file. Path of a json file containing a serialized superCell object, as generated by the SuperCell.serialize() method.

Methods:

as_dict()¶

Return dictionary with object definition

copy()¶

Return a copy

gen_random_decoration(nsubs)¶

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

Parameters:

nsubs: dictionary

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

Returns:

decoration: list of int

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

sigmas: list 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, mc=False)¶

Generate a random Structure with given number of substitutions.

Parameters:

nsubs: None, int or dictionary (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.

Notes:

This function can be also called with the method gen_random, with the same signature. Use gen_random_structure, since gen_random is deprecated.

gen_structure(sigmas=None, mc=False)¶

Generate a Structure with given configuration.

Parameters:

sigmas: array of integers

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)¶

Get array of positions.

Parameters:

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()

get_pristine_structure()¶

Return Structure object corresponding to pristine structure.

get_sym()¶

Get space symmetry of a ParentLattice object.

get_sym_platt()¶

Get space symmetry of a ParentLattice object.

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:

filepath: string

Output file name.

fname: string

DEPRECATED, use filepath instead. Output file name.