The ClustersPool class¶

Objects of this class comprise a set of clusters which can be used to perform a cluster expansion

Initialization and methods¶

class clusterx.clusters.clusters_pool.ClustersPool(parent_lattice=None, npoints=[], radii=[], super_cell=None, method=0, filepath=None, json_db_filepath=None, db=None)¶

Clusters pool class

Parameters:

parent_lattice: ParentLattice object: Parent lattice of the system.
npoints: array of integers: The number of points of the clusters in the pool. Must be of the same dimension as radii.
radii: array of float: The maximum radii of the clusters in the pool, for each corresponding number of points in npoints. If super_cell is given (see below), any element of the radii array can be a negative number. In such a case, all clusters fitting in the given super_cell (for the corresponding number of points in npoints) are generated.
super_cell: SuperCell object: If present, radii is overriden and the pool will consist of all possible simmetrically distinct clusters in the given super cell. Periodic boundary conditions of the parent lattice are taken into account (thus, e.g., if a supercell of side \(a\) of a square lattice is given, then in the directions of periodicity the clusters will not be longer than \(a/2\)). (Note: Experimental feature. The generated multiplicities may not be valid for clusters larger than half the size of the supercell. Use radii to get accurate multiplicities.)
method: integer (1 or 2): If 1, an elimination method is used to build the clusters pool. If 2, an incremental method is used instead. Use method 2 only if super_cell is None.
filepath: string (default: None): Overrides all the above. Used to initialize from file. Path of a json file containing a serialized ClustersPool object, as generated by the ClustersPool.serialize() method.
json_db_filepath: string (default: None): DEPRECATED, use filepath instead. Overrides all the above. Used to initialize from file. Path of a json file containing a serialized ClustersPool object, as generated by the ClustersPool.serialize() method.

Examples:

The example below, will generate all possible clusters up to 2 points in the super cell scell, while more compact clusters up to a radius of 4.1 and 2.9 for 3 and 4 points, respectively, are generated:

from ase import Atoms
from clusterx.parent_lattice import ParentLattice
from clusterx.super_cell import SuperCell
from clusterx.clusters.clusters_pool import ClustersPool

plat = ParentLattice(
    Atoms(cell=np.diag([2,2,5]),positions=[[0,0,0]]),
    site_symbols=[["Cu","Al"]],
    pbc=(1,1,0)
    )

scell = SuperCell(plat,np.array([(6,0,0),(0,6,0),(0,0,1)]))
cp = ClustersPool(plat, npoints=[0,1,2,3,4], radii=[0,0,-1,4.1,2.9], super_cell=scell)

cp.write_clusters_db(db_name="cpool.json")

The example

Methods:

add(other)¶

Add other ClustersPool object to this one

The actual ClustersPool object gets modified
self._cpool_scell need be the same for both summands (at the moment not checked by the function)

as_dict()¶: Return a python-dictionary representation of the clusters pool

display_info(ecis=None)¶

Display in screen information about the clusters pools

DEPRECATED: Use print_info() instead.

Displays on screen a table with information concerning the clusters pool.

Parameters:

ecis: Array of float (optional): Effective cluster interactions. If not None, the displayed table contains the ECI values in the last column.

gen_atoms_database(fname='clusters.json')¶: Builds an ASE’s json database object (self._atoms_db). Atoms items in the built database are a representation of the clusters embedded in a supercell appropriate for visualization with ASE’s gui.

gen_clusters(method=0)¶

Generate pool of clusters

Parameters:

method: int 0: Fast, default method. 1: Slow, use only for benchmarking purposes.

get_all_npoints()¶: Return array containing the number of points of each cluster in the pool

get_all_radii()¶: Return array containing the radius of each cluster in the pool

get_cluster_orbit(super_cell=None, cluster_sites=None, cluster_species=None, tol=0.001, distances=None, no_trans=False, cluster_index=None, cluster_positions=None)¶

Get cluster orbit inside a supercell.

Returns a pool of clusters corresponding to a cluster orbit in the given super cell, the weights of each cluster in the orbit (accounting for the periodic boundary conditions) and the multiplicity of the cluster.

An example is as follows:

orbit = clusters_pool.get_cluster_orbit(scell, cluster_index = 3)

Here, the orbit of the fourth cluster in the pool (i.e., the cluster clusters_pool[3]) is computed.

The output orbit is a clusters pool object, containing the orbit of the input 
cluster in the supercell scell (given as input parameter). 
The output weigths=[w1, w2, ... , wNc] is an integer numpy array with the same 
length as the orbit, with wi being the weight of cluster i in the orbit. 
The output mult is an integer number equal to the multiplicity of the cluster, i.e., 
the number of distinct realizations of the cluster which appear by the application of all
symmetries of the space group of the parent lattice. 
The output rmult is an integer number equal to the reduced multiplicity of the cluster, i.e., 
the number of distinct realizations of the cluster which appear by the application of all
symmetries of the space group of the parent lattice, but only those which correspond to 
configurations that can be relized in the supercell. 

The output verifies the relation \(n_{SC} m_r = \sum_i w_i\), with \(n_{SC}\) the “index” of the supercell (i.e. \(n_{SC}=N_{SC}/N_{pl}\), with \(N_{SC}\) the number of atoms in the supercell and \(N_{pl}\) the number of atoms in the parent lattice), \(m_r\) the reduced multiplicity of the cluster and \(w_i\) the weight of cluster i in the orbit. That is, the statement:

scell.get_index() * rmult == np.sum(weights)

evaluates to True.

Parameters:

super_cell: SuperCell object: The super cell in which the orbit is calculated.
cluster_sites: Array of integer: the atom indices of the cluster as referred to the SuperCell object given in super_cell, or the ClustersPool.get_cpool_scell() superCell object (see cluster_index).
cluster_species: array of integer: Decoration (with species numbers) of the cluster for which the orbit is calculated. The species numbers serve as index for the site cluster basis functions. Thus, for instance if in a given site, say, i=12, the possible species to put are 14, 15 and 16 (14 for the pristine), then 15 represents the site basis function with label 1 and 16 the basis function with label 2.
tol: float: tolerance to determine whether cluster and atom positions are the same.
distances: 2D array of floats: distances of all of the atoms with all of the atoms. Can be used to achieve larger efficiency.
no_trans: Boolean: set to True to ignore translations of the parent_lattice inside the SuperCell. Thus a reduced orbit is obtained which only contains the symmetry operations of the parent lattice.
cluster_index: integer: Index of a cluster in the pool. Overrides super_cell, and the orbit is calculated on the supercell of the ClustersPool.get_cpool_scell() object.
cluster_positions: list of vectors: the atoms positions in cartesian coordinates. cluster_positions[i] = [ix, iy, iz], where ix,iy and iz are float numbers representing the x, y and z cartesian coordinate, respectively, of atom i.

get_clusters_sets(grouping_strategy='size', nclmax=0, set0=[0, 0])¶

Return cluster sets for cluster selection based on CV

Parameters:

grouping_strategy: string: Can take the values “size” and “combinations”. If “size”, a set in the clusters set is determined by two parameters, the maximum number of points and the maximum radius. Thus, a set is formed by all clusters in the pool whose radius and npoints are smaller or equal than the respective maxima for the set. When “combinations” is used, all possible sets up to nclmax number of clusters are returned.
nclmax: integer: The maximum clusters-set size when strategy=”combinations” is used.
set0: [points, radius]: The clusters-set, which is defined by the two parameters - maximum number of points (points) and the maximum radius, [points, radius] -, is included in all combinations, when strategy=”size+combinations” is used.

get_containing_supercell(tight=False)¶: Return a supercell able to contain all clusters in the pool defined by the arrays self.get_npoints() and self.get_radii(). Returns the supercell which circumscribes a sphere of diameter at least as large as the largest cluster radius.

get_cpool_arrays()¶: Get arrays of atom indices and atom numbers of the clusters in the pool

get_cpool_list()¶: Return python list containing the clusters in the pool

get_cpool_structures()¶: Get array of structure objects representing the clusters in the clusters pool

get_max_radii()¶

Return array of maximum radii of the clusters in the pool.

The returned float array has the same length and its elements correspond with those of the array self.get_npoints(). Thus, the pool is defined by having all clusters of self.get_npoints()[i] number of points up to a radius of self.get__max_radii()[i]

get_multiplicities()¶

Return cluster multiplicities

The multiplicity of a cluster is equal to the number of its symmetrically equivalent realizations of it, or equivalently, the size of its orbit (without considering parent lattice translations).

get_npoints()¶

Return array of number of points of the clusters in the pool.

The returned integer array has the same length and its elements correspond with those of the array self.get_radii(). Thus, the pool is defined by having all clusters of self.get_npoints()[i] number of points up to a radius of self.get_max_radii()[i]

get_plat()¶: Return parent lattice for the clusters pool

get_subpool(cluster_indexes)¶

Return a ClustersPool object formed by a subset of the clusters pool

Parameters:

cluster_indexes: array of integers: The indexes of the clusters to build the subpool from.

get_supercell()¶: Return SuperCell instance used for the construction of the clusters pool

get_unique_radii()¶: Return sorted array of all possible unique radii of clusters in the pool.

print_info(ecis=None)¶

Print information about the clusters pools

Prints a table with information concerning the clusters pool.

Parameters:

ecis: Array of float (optional): Effective cluster interactions. If not None, the displayed table contains the ECI values in the last column.

serialize(filepath='cpool.json', db_name=None)¶

Serialize clusters pool object to json database file

The generated json file is compatible with ASE’s GUI, so you can visualize the clusters with it. You can also initialize a new ClustersPool object from this file, for this read the documentation for the json_db_filepath attribute of ClustersPool class.

Parameters:

filepath: string (default: “cpool.json”): Name of the file to save the ClustersPool object.
db_name: string (default: “cpool.json”): DEPRECATED, use filepath instead. Name of the json database file.

sort()¶: Sort clusters pool

write_clusters_db(orbit=None, super_cell=None, db_name='cpool.json')¶

Write cluster orbit to Atoms JSON database

Parameters:

orbit: python list (default: None): list of Cluster objects. If None, just the clusters in the ClustersPool object are written.
super_cell: SuperCell object (default: None): The supercell in which the clusters are supported. If None, the SuperCell object of self (output of method get_cpool_scell()) is used.
db_name: string: Name of the json file containing the database