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
SuperCellobject acts as a blue-print for the creation of structures with arbitrary decorations.The
SuperCellclass inherits from theParentLatticeclass. Therefore, all methods available to theParentLatticeclass are available to theSuperCellclass. Refer to the documentation ofParentLatticefor more methods.- Parameters:
- parent_lattice
ParentLatticeobject 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 matrixpmust 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 thesort_keyargument, with the same effect as in the argument toitemgetterbelow: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
filepathinstead. If provided, this argument will still be accepted but a deprecation warning will be issued.
- parent_lattice
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
nsubsargument must have the format{site_type0:[nsub01,nsub02,...], site_type1: ...}wheresite_type#andnsub##are, respectively, an integer indicating the site type index and the number of substitutional species of each kind, as returned bySuperCell.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 argumentsigmas=[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.