Cluster Expansion & Decomposition Processors#

Implementation of CE processor class for a fixed size supercell.

If you are using a Hamiltonian with an Ewald summation electrostatic term, you should use the CompositeProcessor with a ClusterExpansionProcessor and an EwaldProcessor class to handle changes in the electrostatic interaction energy.

class ClusterDecompositionProcessor(cluster_subspace, supercell_matrix, interaction_tensors, coefficients=None, num_threads=None, num_threads_full=None)[source]#

Bases: Processor

ClusterDecompositionProcessor to use a CD in MC simulations.

An ClusterDecompositionProcessor is similar to a ClusterExpansionProcessor however it computes properties and changes of properties using cluster interactions rather than correlation functions and ECI.

For a given ClusterExpansion the results from sampling using this class should be the exact same as using a ClusterExpansionProcessor (ie the samples are from the same ensemble).

A few practical and important differences though, the featyre vectors that are used and sampled are the cluster interactions for each occupancy as opposed to the correlation vectors (so if you need correlation vectors for further analysis you’re probably better off with a standard ClusterExpansionProcessor

However, if you don’t need correlation vectors, then this is probably more efficient and more importantly the scaling complexity with model size is in terms of number of orbits (instead of number of corr functions). This can give substantial speedups when doing MC calculations of complex high component systems.

Initialize an ClusterDecompositionProcessor.

Parameters:

  • cluster_subspace (ClusterSubspace) – A cluster subspace

  • supercell_matrix (ndarray) – An array representing the supercell matrix with respect to the Cluster Expansion prim structure.

  • interaction_tensors (sequence of ndarray) – Sequence of ndarray where each array corresponds to the cluster interaction tensor. These should be in the same order as their corresponding orbits in the given cluster_subspace.

  • num_threads (int) – optional Number of threads to use to compute a correlation vector. Note that this is not saved when serializing the ClusterSubspace with the as_dict method, so if you are loading a ClusterSubspace from a file then make sure to set the number of threads as desired. corresponding orbits in the given cluster_subspace

  • coefficients (ndarray) – optional coefficients of each mean cluster interaction tensor. This should often be some multiple of the orbit multiplicities. Default is the orbit multiplicities.

as_dict()[source]#

Json-serialization dict representation.

Return type:

dict

Returns:

MSONable dict

compute_feature_vector(occupancy)[source]#

Compute the cluster interaction vector for a given occupancy string.

The cluster interaction vector in this case is normalized per supercell.

Parameters:

occupancy (ndarray) – encoded occupation array

Returns:

correlation vector

Return type:

array

compute_feature_vector_change(occupancy, flips)[source]#

Compute the change in the cluster interaction vector from a list of flips.

The cluster interaction vector in this case is normalized per supercell.

Parameters:

  • occupancy (ndarray) – encoded occupancy string

  • flips (list of tuple) – list of tuples with two elements. Each tuple represents a single flip where the first element is the index of the site in the occupancy string and the second element is the index for the new species to place at that site.

Returns:

change in cluster interaction vector

Return type:

array

classmethod from_dict(d)[source]#

Create a ClusterExpansionProcessor from serialized MSONable dict.

num_threads#

Descriptor to set an attributed value that cascades to a sequence of objects.

This descriptor is useful when an attribute is needs to be synchronized between a class that holds a sequence of objects that have a corresponding attribute.

num_threads_full#

A descriptor used to set threads of an attributed object that has multi-threading.

Right now it’s only used for the Evaluator class.

class ClusterExpansionProcessor(cluster_subspace, supercell_matrix, coefficients, num_threads=None, num_threads_full=None)[source]#

Bases: Processor

ClusterExpansionProcessor class to use a ClusterExpansion in MC.

A CE processor is optimized to compute correlation vectors and local changes in correlation vectors. This class allows the use of a CE Hamiltonian to run Monte Carlo-based simulations

A processor that allows an Ensemble class to generate a Markov chain for sampling thermodynamic properties from a CE Hamiltonian.

coefs#

Fitted coefficients from the cluster expansion.

Type:

ndarray

num_corr_functions#

Total number of orbit basis functions (correlation functions). This includes all possible labelings/orderings for all orbits. Same as ClusterSubspace.n_bit_orderings.

Type:

int

Initialize a ClusterExpansionProcessor.

Parameters:

  • cluster_subspace (ClusterSubspace) – a cluster subspace

  • supercell_matrix (ndarray) – an array representing the supercell matrix with respect to the Cluster Expansion prim structure.

  • coefficients (ndarray) – fit coefficients for the represented cluster expansion.

  • num_threads (int) – optional Number of threads to use to compute updates in a correlation vector from local changes. If None is given the number of threads are set to the same as set in the given :class:`ClusterSubspace. Note that this is not saved when serializing the ClusterSubspace with the as_dict method, so if you are loading a ClusterSubspace from a file then make sure to set the number of threads as desired.

  • num_threads_full (int) – optional Number of threads to use to compute a full correlation vector. Note that this is not saved when serializing the ClusterSubspace with the as_dict method, so if you are loading a ClusterSubspace from a file then make sure to set the number of threads as desired.

compute_feature_vector(occupancy)[source]#

Compute the correlation vector for a given occupancy string.

The correlation vector in this case is normalized per supercell. In other works it is extensive corresponding to the size of the supercell.

Parameters:

occupancy (ndarray) – encoded occupation array

Returns:

correlation vector

Return type:

array

compute_feature_vector_change(occupancy, flips)[source]#

Compute the change in the correlation vector from a list of flips.

The correlation vector in this case is normalized per supercell. In other works it is extensive corresponding to the size of the supercell.

Parameters:

  • occupancy (ndarray) – encoded occupancy string

  • flips (list of tuple) – list of tuples with two elements. Each tuple represents a single flip where the first element is the index of the site in the occupancy string and the second element is the index for the new species to place at that site.

Returns:

change in correlation vector

Return type:

array

classmethod from_dict(d)[source]#

Create a ClusterExpansionProcessor from serialized MSONable dict.

num_threads#

Descriptor to set an attributed value that cascades to a sequence of objects.

This descriptor is useful when an attribute is needs to be synchronized between a class that holds a sequence of objects that have a corresponding attribute.

num_threads_full#

A descriptor used to set threads of an attributed object that has multi-threading.

Right now it’s only used for the Evaluator class.

class LocalEvalData(site_index, evaluator, indices, cluster_ratio, num_threads=<smol.utils.cluster.numthreads.SetNumThreads object>)[source]#

Bases: object

Holds data for local evaluation updates.

A dataclass to the data for local evaluation updates of correlation and cluster interaction vectors.

cluster_ratio: ndarray#
evaluator: ClusterSpaceEvaluator#
indices: OrbitIndices#
num_threads: int#

A descriptor used to set threads of an attributed object that has multi-threading.

Right now it’s only used for the Evaluator class.

site_index: int#