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.
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
objectIn 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 arrayTransformation 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, optionalCreate 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:
Return dictionary with object definition
Return a copy
Generate a random decoration of the super cell with given number of substitutions.
Parameters:
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:
list with the same length as the pristine structure. decoration[atom_idx] = species number sitting at site idx.
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.
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.
Generate a Structure with given configuration.
Parameters:
sigmas
: array of integerssigmas[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]
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 of parent lattice in supercell, scaled to supercell
Return the parent lattice object which defines the supercell.
Get array of positions.
Parameters:
wrap atoms back to the cell before returning positions
optional keywords pbc, center, pretty_translation, eps,
see ase.geometry.wrap_positions()
Return Structure object corresponding to pristine structure.
Get space symmetry of a ParentLattice object.
Get space symmetry of a ParentLattice object.
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}
Return the transformation matrix that defines the supercell from the defining parent lattice.
Plot the pristine supercell object.
Generates SuperCell object from a dictionary as returned by SuperCell.as_dict()
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
: stringOutput file name.
fname
: stringDEPRECATED, use filepath instead. Output file name.