Ensembles#

The Ensemble class is used to represent different types of ensembles that can be implemented for MC sampling. Systems at constant temperature and constant composition (no species flow in/out of the system) should have chemical_potentials set to None and choose an appropriate step type (i.e. a swap). Systems at constant temperature and constant applied chemical potential (species flow allowed) should simple set the chemical_potentials property.

Implementation of Thermodynamic Ensemble for MC sampling.

class Ensemble(processor, sublattices=None, chemical_potentials=None)[source]#

Bases: MSONable

Thermodynamic ensemble class.

thermo_boundaries#

Dictionary with corresponding thermodynamic boundaries, i.e. chemical potentials. This is kept only for descriptive purposes.

Type:

dict

Initialize class instance.

Parameters:

  • processor (Processor) – a processor that can compute the change in property given a set of flips.

  • sublattices (list of Sublattice) – optional list of Sublattice objects representing sites in the processor supercell with same site spaces.

property active_sublattices#

Get list of active sub-lattices.

as_dict()[source]#

Get Json-serialization dict representation.

Returns:

MSONable dict

chemical_potentials = None#
compute_feature_vector(occupancy)[source]#

Compute the feature vector for a given occupancy.

The feature vector includes the necessary features required to compute the exponent determining the relative probability for the given occupancy (i.e. a generalized enthalpy). The feature vector for ensembles represents the sufficient statistics.

For a cluster expansion, the feature vector is the correlation vector x system size

Parameters:

occupancy (ndarray) – encoded occupancy string

Returns:

feature vector

Return type:

ndarray

compute_feature_vector_change(occupancy, step)[source]#

Compute the change in the feature vector from a given step.

Parameters:

  • occupancy (ndarray) – encoded occupancy string.

  • step (list of tuple) – a sequence of flips given by MCUsher.propose_step

Returns:

difference in feature vector

Return type:

ndarray

classmethod from_cluster_expansion(cluster_expansion, supercell_matrix, processor_type='decomposition', **kwargs)[source]#

Initialize an ensemble from a cluster expansion.

Convenience constructor to instantiate an ensemble. This will take care of initializing the correct processor based on the ClusterExpansion.

Parameters:

  • cluster_expansion (ClusterExpansion) – A cluster expansion object.

  • supercell_matrix (ndarray) – Supercell matrix defining the system size.

  • processor_type (str) – optional Type of processor to be used besides external term. Can use “decomposition” (default) or “expansion”.

  • **kwargs – Keyword arguments to pass to ensemble constructor. Such as sublattices, sublattice_probabilities, chemical_potentials, fugacity_fractions.

Returns:

Ensemble

classmethod from_dict(ensemble_d)[source]#

Instantiate a CanonicalEnsemble from dict representation.

Parameters:

ensemble_d (dict) – dictionary representation.

Returns:

CanonicalEnsemble

property natural_parameters#

Get the vector of natural parameters.

The natural parameters correspond to the fit coefficients of the underlying processor plus any additional terms involved in the Legendre transformation corresponding to the ensemble.

property num_energy_coefs#

Return the number of coefficients used in the energy expansion.

property num_sites#

Get the total number of sites in the supercell.

property processor#

Get the ensemble processor.

reset_restricted_sites()[source]#

Unfreeze all previously restricted sites.

restrict_sites(sites)[source]#

Restricts (freezes) the given sites.

This will exclude those sites from being flipped during a Monte Carlo run. If some of the given indices refer to inactive sites, there will be no effect.

Parameters:

sites (Sequence) – indices of sites in the occupancy string to restrict.

property restricted_sites#

Get indices of all restricted sites.

property species#

Species on active sublattices.

These are minimal species required in setting chemical potentials.

split_sublattice_by_species(sublattice_id, occu, species_in_partitions)[source]#

Split a sub-lattice in system by its occupied species.

An example use case might be simulating topotactic Li extraction and insertion, where we want to consider Li/Vac, TM and O as different sub-lattices that can not be mixed by swapping.

Parameters:

  • sublattice_id (int) – The index of sub-lattice to split in self.sublattices.

  • occu (np.ndarray[int]) – An occupancy array to reference with.

  • species_in_partitions (List[List[int|Species|Vacancy|Element|str]]) – Each sub-list contains a few species or encodings of species in the site space to be grouped as a new sub-lattice, namely, sites with occu[sites] == specie in the sub-list, will be used to initialize a new sub-lattice. Sub-lists will be pre-sorted to ascending order.

property sublattices#

Get list of Sublattices included in ensemble.

property system_size#

Get size of supercell in number of prims.