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_latticeParentLattice
Parent lattice of the system.
- npointsndarray of int
The number of points of the clusters in the pool. Must be of the same dimension as
radii.- radiindarray of float
The maximum radii of the clusters in the pool, for each corresponding number of points in
npoints. Ifsuper_cellis given (see below), any element of theradiiarray can be a negative number. In such a case, all clusters fitting in the givensuper_cell(for the corresponding number of points in npoints) are generated.- super_cellSuperCell
If present,
radiiis 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. Useradiito get accurate multiplicities.)- methodint (0 or 1)
If 0, an elimination method is used to build the clusters pool. If 1, an incremental method is used instead. Use method 1 only if
super_cellisNone.- filepathstr, 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_filepathstr, default None
DEPRECATED, use
filepathinstead. Overrides all the above. Used to initialize from file. Path of a json file containing a serialized ClustersPool object, as generated by theClustersPool.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
- 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:
- ecisndarray 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, append=False)¶
Generate pool of clusters
- Parameters:
- methodint
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, 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 outputorbitis a clusters pool object, containing the orbit of the input cluster in the supercellscell(given as input parameter).The outputweigths=[w1, w2, ... , wNc]is an integer numpy array with the same length as theorbit, withwibeing the weight of clusteriin the orbit.The outputmultis 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 outputrmultis 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_cellSuperCell
The super cell in which the orbit is calculated.
- cluster_sitesndarray of int
the atom indices of the cluster as referred to the SuperCell object given in
super_cell, or theClustersPool.get_cpool_scell()superCell object (seecluster_index).- cluster_speciesndarray of int
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 are14,15and16(14for the pristine), then15represents the site basis function with label1and16the basis function with label2.- tolfloat
tolerance to determine whether cluster and atom positions are the same.
- no_transbool
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_indexint
Index of a cluster in the pool. Overrides
super_cell, and the orbit is calculated on the supercell of theClustersPool.get_cpool_scell()object.- cluster_positionslist 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_strategystr
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.
- nclmaxint
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()andself.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_atoms(orbit=None, super_cell=None, vacancy_atomic_number=0)¶
- Parameters:
- vacancy_atomic_numberint, default 0
In
CELL, vacancies are formally represented as a species with species number 0 and symbolX. In some cases, e.g. visualization, you may want to give the vacancy a different species number. Set this variable to a different number (different from all other species numbers in the corresponding parent lattice) if that is the case.
- 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 per-order diameter bounds paired with
get_npoints().Generated pools record the requested generation cutoffs. Subpools record the largest retained cluster diameter for each order; they need not contain every cluster within these bounds. Use
get_all_radii()for the radius of each individual cluster.
- 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 cluster orders paired with the bounds in
get_max_radii().Generated pools record the requested orders. Subpools record the sorted unique orders of their retained clusters. Use
get_all_npoints()for the order of each individual cluster.
- 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_indexesndarray of int
The indexes of the clusters to build the subpool from.
Notes
The original cluster order, multiplicities, and defining supercell are preserved. The sorted unique orders and maximum diameter for each order are determined from the retained clusters, without regenerating clusters or asserting that the selected subset is a complete pool.
- 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:
- ecisndarray of float (optional)
Effective cluster interactions. If not
None, the displayed table contains the ECI values in the last column.
- serialize(filepath='cpool.json', vacancy_atomic_number=0, 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_filepathattribute of ClustersPool class.- Parameters:
- filepathstr, default “cpool.json”
Name of the file to save the ClustersPool object.
- vacancy_atomic_numberint, default 0
In
CELL, vacancies are formally represented as a species with species number 0 and symbolX. In some cases, e.g. visualization, you may want to give the vacancy a different species number. Set this variable to a different number (different from all other species numbers in the corresponding parent lattice) if that is the case. IMPORTANT: Do not change the deafult value of this parameter if you plan to use the generated file for creating aCPOOLobject from the generated file.- db_namestr, default “cpool.json”
DEPRECATED, use
filepathinstead. Name of the json database file.
- sort()¶
Sort clusters pool
- write_clusters_db(orbit=None, super_cell=None, db_name='cpool.json', vacancy_atomic_number=0)¶
Write cluster orbit to Atoms JSON database
- Parameters:
- orbitpython list, default None
list of
Clusterobjects. IfNone, just the clusters in theClustersPoolobject are written.- super_cell
SuperCellobject (default:None) The supercell in which the clusters are supported. IfNone, theSuperCellobject ofself(output of methodget_cpool_scell()) is used.- db_namestr
Name of the json file containing the database
- vacancy_atomic_numberint, default 0
In
CELL, vacancies are formally represented as a species with species number 0 and symbolX. In some cases, e.g. visualization, you may want to give the vacancy a different species number. Set this variable to a different number (different from all other species numbers in the corresponding parent lattice) if that is the case.