The ParentLattice class¶

Assigning the substitutions¶

List of all methods¶

class clusterx.parent_lattice.ParentLattice(atoms=None, substitutions=None, numbers=None, symbols=None, json_db_filepath=None, pbc=None, sites=None, site_symbols=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. ParentLattice subclasses ASE’s Atoms class.

Parameters:

atoms: ASE’s Atoms object

atoms object corresponding to the pristine lattice. If sites or site_symbols is not None, then the passed Atoms objects may not contain a definition of atomic species, i.e., can be initialized by only indicating atomic positions, unit cell, and periodic boundary conditions.

substitutions: list of ASE’s Atoms objects.

Every Atoms object in the list, corresponds to a possible full substitution of only one sublattice. If set, overrides sites (see below).

numbers: list of integer 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 substitutions if set. If a dict, the dict keys must be the site indices.

symbols: list of strings

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 by substitutions if set.

json_db_filepath: string

Path to a Json database file, as created by ParentLattice.serialize(). Overrides all the above. Allows to create a ParentLattice object from file.

pbc: three 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 sites parameter instead of the substitutions parameter:

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.

Methods:

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._atoms and self._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:

unique: Boolean (default True)

If True, return the number of site-types which may be substituted. If False, 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 sites definition 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_types dictionary (as returned by idx_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)¶

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

Return (reference to) Atoms object of pristine configuration

get_sites()¶

Return dictionary of sites

The keys of the sites dictionary 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 and sub## the possible substitutional atomic numbers for the site.

Parameters:

pretty_print: boolean

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 True if 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 returns False.

Example: 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")

Parameters:

n: int

Integer number indicating how many different species can be hosted by the substitutional sublattice.

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:

decimals: integer

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.

Return:

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:

filepath: string

Output file name.

fname: string

DEPRECATED, use filepath instead. Output file name.