Cluster

Cluster:

The cluster module defines the Cluster object (for simple clusters, transition state clusters, and vacancy-base clusters), and a MonteCarloSampler object with a jit version.

Cluster expansion module: types necessary to implement cluster expansions of quantities based on crystals.

class cluster.Cluster(clustersitelist, transition=False, vacancy=False, NOSORT=False)

Class to define (arbitrary) cluster interactions. A cluster is defined as a set of ClusterSites. We don’t implement this using sets, however, because we make a choice of a “reference” site in each cluster, which has a lattice vector of 0, to account for translational invariance.

The flag transition dictates whether the cluster is a transition state cluster or not. The difference with a transition state cluster is that the first two states in the cluster are the initial and final states of the transition, while all of the remaining parts are the cluster.

static Cluster_constructor(loader, node)

Construct a ClusterSite from YAML

static Cluster_representer(dumper, data)

Output a ClusterSite

__add__(other)

Add a clustersite to a cluster expansion

__contains__(elem)

Returns whether a cluster site is in our cluster expansion

__eq__(other)

Test for equality of two clusters. This is a bit trickier than one would expect, since clusters are essentially sets where all of the lattice vectors are shifted by the center of mass of the sites.

__hash__()

Return our hash value, precomputed

__init__(clustersitelist, transition=False, vacancy=False, NOSORT=False)

Cluster interaction, from an iterable of ClusterSites :param clustersitelist: iterable of ClusterSites :param transition: True if a transition state cluster; cl[0] = initial, cl[1] = final

__str__()

Human readable version

__sub__(other)

Subtract a site from a cluster. Had a very specific meaning: if the site is in the cluster, it returns a list of all the other sites, shifted so that the other site is at the origin.

Needs to be clarified for the case of a transition state.

Parameters:

other – needs to be a cluster site in the cluster.

__weakref__

list of weak references to the object

g(crys, g)

Apply group operation.

Parameters:

• crys – crystal

• g – group operation (from crys)

Return g*cluster:

corresponding to group operation applied to self

istransition(site0, site1)

Check whether two sites correspond to the transition state

pairdistances(crys)

Return a dictionary of all the pair distances between the chemistries in the cluster. For simplicity, we include both (c1,c2) and (c2,c1).

Parameters:

crys – crystal

Return dist_dict:

dist_dict[c1][c2] = sorted list of distances between chemistry c1 and c2

transitionstate()

Return the two sites of the transition state

vacancy()

Return the two sites of the transition state

class cluster.ClusterSite(ci, R)

A class corresponding to a site in a cluster.

Parameters:

• ci – (chem, index) of the site

• R – lattice vector of the site

static ClusterSite_constructor(loader, node)

Construct a ClusterSite from YAML

static ClusterSite_representer(dumper, data)

Output a ClusterSite

__add__(other)

Add a vector to a site; other must be a vector

__eq__(other)

Test for equality–we don’t bother checking dx

__hash__()

Hash, so that we can make sets of states

__ne__(other)

Inequality == not __eq__

__neg__()

Negation of site

__str__()

Human readable version

classmethod fromcryscart(crys, cart_pos)

Return a ClusterSite corresponding to Cartesian position cart_pos in crystal crys

classmethod fromcrysunit(crys, unit_pos)

Return a ClusterSite corresponding to unit cell position unit_pos in crystal crys

g(crys, g)

Apply group operation.

Parameters:

• crys – crystal

• g – group operation (from crys)

Return g*site:

corresponding to group operation applied to self

class cluster.MonteCarloSampler(supercell, spectator_occ, clusterexp, enevalues, chem=None, jumpnetwork=(), KRAvalues=0, TSclusters=(), TSvalues=())

An object to maintain state in a supercell, evaluate energies efficiently including “trial” moves. Built from cluster expansions and using a cluster supercell.

Now is able to handle supercells that contain a single vacancy.

E()

Compute the energy.

Return E:

total of all interactions

__init__(supercell, spectator_occ, clusterexp, enevalues, chem=None, jumpnetwork=(), KRAvalues=0, TSclusters=(), TSvalues=())

Setup a MonteCarloSampler using a supercell, with a given spectator occupancy, cluster expansion, and energy values for the clusters. Now includes the ability to evaluate a jumpnetwork, which is optional. Because we need to be consistent with our cluster expansion, can only be done at initialization.

Parameters:

• supercell – should be a ClusterSupercell

• spectator_occ – vector of occupancies for spectator species (0 or 1), consistent with our supercell

• clusterexp – list of sets of cluster interactions

• enevalues – energy values corresponding to each cluster

• chem – (optional) index of species that transitions

• jumpnetwork – (optional) list of lists of jumps; each is ((i, j), dx) where i and j are unit cell indices for species chem

• KRAvalues – (optional) list of “KRA” values for barriers (relative to average energy of endpoints); if TSclusters are used, choosing 0 is more straightforward.

• TSclusters – (optional) list of transition state cluster expansion terms; this is always added on to KRAvalues (thus using 0 is recommended if TSclusters are also used)

• TSvalues – (optional) values for TS cluster expansion entries

__weakref__

list of weak references to the object

deltaE_trial(occsites=(), unoccsites=())

Compute the energy change if the sites in occsites are occupied, and the sites in unoccsites are unoccupied.

A few notes: the algorithm does not check whether the same site appears in either iterable multiple times; it trusts that the user has provided it with a meaningful trial change.

Parameters:

• occsites – iterable of sites to attempt occupying

• unoccsites – iterable of sites to attempt unoccupying

Return deltaE:

change in energy

start(occ)

Initialize with an occupancy, and prepare for future calculations.

Parameters:

occ – occupancy of sites in supercell; assumed to be 0 or 1

transitions()

Compute all transitions.

Return ijlist:

list of (initial, final) tuples for each transition

Return Qlist:

vector of energy barriers for each transition

Return dxlist:

vector of displacements for each transition

update(occsites=(), unoccsites=())

Update the state to occupy the sites in occsites and un-occupy the sites in unoccsites.

Parameters:

• occsites – iterable of sites to occupy

• unoccsites – iterable of sites to unoccupy

class cluster.MonteCarloSampler_jit(*args, **kwargs)

Numba jit wrapper on a MonteCarloSampler.

cluster.MonteCarloSampler_param(MCsampler)

Takes in a MCsampler, returns a dictionary of all the parameters for the jit-version

cluster.makeTSclusters(crys, chem, jumpnetwork, clusterexp)

Function to make TS clusters based on an existing cluster expansion corresponding to a given jump network.

Parameters:

• crys – crystal to construct our clusters for

• chem – index of mobile species

• jumpnetwork – list of lists of ((i, j), dx) transitions

• clusterexp – list of sets of clusters to base TS cluster expansion

Returns:

TSclusterexp: list of sets of TS clusters

cluster.makeVacancyClusters(crys, chem, clusterexp)

Function to make vacancy clusters based on an existing cluster expansion where the vacancies live on a particular sublattice.

Parameters:

• crys – crystal to construct our clusters for

• chem – index of the sublattice to contain a vacancy

• clusterexp – list of sets of clusters to base vacancy cluster expansion

Returns:

VacClusterexp: list of sets of vacancy clusters

cluster.makeclusters(crys, cutoff, maxorder, exclude=())

Function to make clusters up to a maximum order involving all sites within a cutoff distance. We can exclude certain chemistries; default is to use all.

Parameters:

• crys – crystal to construct our clusters for

• cutoff – distance between sites; all sites in a cluster must have this mutual distance

• maxorder – maximum order of our clusters

• exclude – list of chemistries to exclude

Return clusterexp:

list of sets of clusters