The ParentLattice class¶
Documentation of the ParentLattice 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.parent_lattice.ParentLattice(atoms=None, substitutions=None, numbers=None, symbols=None, filepath=None, pbc=None, sites=None, site_symbols=None, json_db_filepath=None)¶
Parent lattice class
The parent lattice in a cluster expansion defines the atomic positions, the periodicity, the substitutional species, and the spectator sites, i.e. those atoms which are present in the crystal but are not substituted.
ParentLatticesubclasses ASE’sAtomsclass.- Parameters:
- atomsASE’s Atoms
atomsobject corresponding to the pristine lattice. Ifsitesorsite_symbolsis not None, then the passedAtomsobjects may not contain a definition of atomic species, i.e., can be initialized by only indicating atomic positions, unit cell, and periodic boundary conditions.- substitutionslist of ASE’s Atoms objects
Every
Atomsobject in the list, corresponds to a possible full substitution of only one sublattice. If set, overridessites(see below).- numberslist of int arrays or dict
This is an array of length equal to the number of atoms in the parent lattice. Every element in the array is an array with species numbers, representing the species which can occupy the crystal sites (see examples below). This is overriden by
substitutionsif set. If a dict, the dict keys must be the site indices.- symbolslist of str
This is an array of length equal to the number of atoms in the parent lattice. Every element in the array is an array with species symbols (e.g.
[["Cu","Au"]]), representing the species which can occupy the crystal sites (see examples below). This is overriden bysubstitutionsif set.- filepathstr
Path to a Json database file, as created by
ParentLattice.serialize(). Overrides all the above. Allows to create aParentLatticeobject from file.- json_db_filepathstr, optional
Deprecated. Use
filepathinstead.- pbcthree bool
Periodic boundary conditions flags. Examples: (1, 1, 0), (True, False, False). Default value: (1,1,1)
Examples
In all the examples below, you may visualize the created parent lattice by executing:
$> ase gui plat.json
In this example, the parent lattice for a simple binary fcc CuAl Alloy is built:
from ase.build import bulk from clusterx.parent_lattice import ParentLattice pri = bulk('Cu', 'fcc', a=3.6) sub = bulk('Al', 'fcc', a=3.6) plat = ParentLattice(pri, substitutions=[sub], pbc=pri.get_pbc()) plat.serialize(fname="plat.json")
In the next example, a parent lattice for a complex clathrate compound is defined. This definition corresponds to the chemical formula \(Si_{46-x-y} Al_x Vac_y Ba_{8-z} Sr_z\)
from ase.spacegroup import crystal a = 10.515 x = 0.185; y = 0.304; z = 0.116 wyckoff = [ (0, y, z), #24k (x, x, x), #16i (1/4., 0, 1/2.), #6c (1/4., 1/2., 0), #6d (0, 0 , 0) #2a ] from clusterx.parent_lattice import ParentLattice pri = crystal(['Si','Si','Si','Ba','Ba'], wyckoff, spacegroup=223, cellpar=[a, a, a, 90, 90, 90]) sub1 = crystal(['Al','Al','Al','Ba','Ba'], wyckoff, spacegroup=223, cellpar=[a, a, a, 90, 90, 90]) sub2 = crystal(['X','X','X','Ba','Ba'], wyckoff, spacegroup=223, cellpar=[a, a, a, 90, 90, 90]) sub3 = crystal(['Si','Si','Si','Sr','Sr'], wyckoff, spacegroup=223, cellpar=[a, a, a, 90, 90, 90]) plat = ParentLattice(atoms=pri,substitutions=[sub1,sub2,sub3]) plat.serialize(fname="plat.json")
This example uses the optional
sitesparameter instead of thesubstitutionsparameter:from ase import Atoms from clusterx.parent_lattice import ParentLattice a = 5.0 cell = [[a,0,0],[0,a,0],[0,0,a]] scaled_positions = [[0,0,0],[0.25,0.25,0.25],[0.5,0.5,0.5],[0.75,0.75,0.75],[0.5,0.5,0]] sites = [[11,13],[25,0,27],[11,13],[13,11],[5]] plat = ParentLattice(Atoms(scaled_positions=scaled_positions,cell=cell), sites=sites) plat.serialize(fname="plat.json")
Defined in this way, the crystal site located at [0,0,0] may be occupied by species numbers 11 and 13; the crystal site at [0.25,0.25,0.25] may be occupied by species numbers 25, 0 (vacancy) or 27; and so on. The pristine lattice has species numbers [11,25,11,13,5] (i.e. the first element in every of the lists in sites). Notice that sites with atom index 0 and 2 belong to a common sublattice (i.e. [11,13]) while site with atom index 3 (i.e. [13,11]) determines a different sublattice.
- as_dict()¶
Return dictionary with object definition
- copy()¶
Return a copy.
- get_all_atoms()¶
Return list of Atoms objects of pristine and fully substituted configurations.
Returned Atoms objects are copies of members
self._atomsandself._subs.
- get_atom_indices_for_site_type(site_type)¶
Return atom indices of the structure of a certain given site type
- get_cell(complete=False)¶
Get the three unit cell vectors as a class:ase.cell.Cell` object.
The Cell object resembles a 3x3 ndarray, and cell[i, j] is the jth Cartesian coordinate of the ith cell vector.
- get_n_sub_sites(unique=True)¶
Return total number of substitutional sites
- Parameters:
- uniquebool, default True
If
True, return the number of site-types which may be substituted. IfFalse, return the number of sites which may be substituted.
- get_natoms()¶
Get the total number of atoms.
- get_nsites_per_type()¶
Return number of sites per site type.
For instance, suppose that the
sitesdefinition of the structure is:sites = {0: [14,13], 1: [14,13], 2: [14,13], 3: [56,0,38], 4: [56,0,38], 5:[11]}
The
site_typesdictionary (as returned byidx_subs()) for this will be:site_types = {0: [14,13], 1: [56,0,38], 2:[11]}
Thus, the tags definition will be:
tags = [0,0,0,1,1,2]
and, the number of sites per site type (what this function returns):
{0: 3, 1: 2, 2: 1}
That is, there are three sites of type 0, 2 sites of type 1, and 1 site of type 2.
- get_positions(wrap=False, **wrap_kw)¶
This method caches positions, otherwise ASE would copy large arrays.
- get_pristine()¶
Return (reference to) Atoms object of pristine configuration
- get_sites()¶
Return dictionary of sites
The keys of the
sitesdictionary correspond to the atom indices in the ParentLattice object. The value for each key is an array of integer number representing the species-number that may occupy the site. For instance, if a ParentLattice object consists of six positions, such that the first three positions can be occupied by species 14 or 13, the 4th and 5th positions by species 56, vacant or species 38, and the 6th position can be only occupied by species 11, then the sites dictionary reads:sites = {0: [14,13], 1: [14,13], 2: [14,13], 3: [56,0,38], 4: [56,0,38], 5:[11]}
- get_spectator_sites()¶
Return atom indexes which may not be substituted
- get_spectator_tags()¶
Return site types for non substitutional sites
- get_sublattice_types(pretty_print=False)¶
Return dictionary of site type indexes and substitutional species
The format of the returned dictionary is:
{'0':[pri0,sub00,sub01,...],'1':[pri1,sub10,sub11,...]...}
where the key indicates the site type,
pri#the atomic number of the pristine structure andsub##the possible substitutional atomic numbers for the site.- Parameters:
- pretty_printbool
Whether to return a dictionary or a self-explanatory and nicely formatted string.
DEPRECATED: Use print_sublattice_types() instead.
Examples
For instance, if a ParentLattice object consists of six positions, such that the first three positions can be occupied by species 14 or 13, the 4th and 5th positions by species 56, vacant or species 38, and the 6th position can be only occupied by species 11, then there are three site types, and the returned dictionary will look like:
{0: [14,13], 1: [56,0,38], 2:[11]}
- get_substitutional_atoms()¶
Return Atoms object for pristine lattice containing only sites which may be substituted
- get_substitutional_sites()¶
Return atom indexes which may be substituted
- get_substitutional_tags()¶
Return site types for substitutional sites
- get_substitutions()¶
Return array of (references to) Atoms objects corresponding to fully substituted configurations.
- get_sym()¶
Get space symmetry of a ParentLattice object.
- is_nary(n)¶
Check whether lattice is n-ary
Returns
Trueif the structure is based on a n-ary ParentLattice object, i.e., whether it consists of a single n-ary substitutional sublattice (plus any number of spectator sublattices). Otherwise returnsFalse.- Parameters:
- nint
Integer number indicating how many different species can be hosted by the substitutional sublattice.
Examples
Check whether a structure is a ternary:
from clusterx.parent_lattice import ParentLattice from clusterx.super_cell import SuperCell from ase.build import bulk cu = bulk("Cu","fcc") au = bulk("Au","fcc") ag = bulk("Ag","fcc") plat = ParentLattice(atoms=cu, substitutions=[au,ag]) scell = SuperCell(plat, [[2,2,-2],[2,-2,2],[-2,2,2]]) s = scell.gen_random(nsubs={0:[10,3]}) If s.is_nary(3): print("The structure is ternary")
- plat_from_dict()¶
Generates ParentLattice object from a dictionary as returned by ParentLattice.as_dict()
- print_sublattice_types()¶
Print chemical symbols and atomic numbers for each sublattice type.
- round_coords(decimals=12)¶
Round cell vectors and lattice positions coordinates.
Uses
numpy.around()method.- Parameters:
- decimalsint
Number of decimal places to round to (default: 0). If decimals is negative, it specifies the number of positions to the left of the decimal point.
- Returns:
- ParentLattice
Returns a new ParentLattice object with rounded coordinates.
- serialize(filepath='plat.json', fname=None)¶
Serialize a ParentLattice object
Writes a ASE’s json database file containing a representation of the parent lattice. An instance of the ParentLattice class can be initialized from the created file. The created database can be visualized using ASE’s gui, e.g.:
ase gui plat.json
- Parameters:
- filepathstr
Output file name.
- fnamestr
DEPRECATED, use
filepathinstead. Output file name.