The ClusterOrbit class

Objects of this class comprise a set of clusters which are symetrically equivalent.

Initialization and methods

class clusterx.clusters.clusters_pool.ClusterOrbit(super_cell, cluster_sites=None, cluster_species=None, tol=0.001, no_trans=False, json_db_filepath=None, cluster_positions=None)

Cluster orbit class

gen_orbit(super_cell, cluster_sites=None, cluster_species=None, tol=0.001, no_trans=False, cluster_positions=None)

Generate 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_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 the ClustersPool.get_cpool_scell() superCell object (see cluster_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 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.

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 the ClustersPool.get_cpool_scell() object.

gen_orbit_slow_version(super_cell, cluster_sites=None, cluster_species=None, tol=0.001, no_trans=False, cluster_positions=None)

Generate 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_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 the ClustersPool.get_cpool_scell() superCell object (see cluster_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 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.

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 the ClustersPool.get_cpool_scell() object.

serialize(filepath='cpool.json', vacancy_atomic_number=0, json_db_filepath=None)

Write cluster orbit to Atoms JSON database

Parameters:
filepathstr, default cpool.json

absolute or relative path where serialized structure is saved.

vacancy_atomic_numberint, default 0

In CELL, vacancies are formally represented as a species with species number 0 and symbol X. 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 a CPOOL object from the generated file.

json_db_filepathstr, default None

DEPRECATED, use filepath instead.