MCKernels#

MCKernel classes implement different Monte Carlo sampling algorithms. They are used by Sampler classes to perform the actual sampling. The following kernels are currently implemented:

Implementation of Metropolis and UniformlyRandom kernels.

A simple Metropolis-Hastings kernel and a Multicell Metropolis kernel that can hop among different supercell shapes.

class Metropolis(ensemble, step_type, temperature, *args, seed=None, bias_type=None, bias_kwargs=None, **kwargs)[source]#

Bases: MetropolisAcceptMixin, ThermalKernelMixin, MCKernel

A Metropolis-Hastings kernel.

The classic and nothing but the classic.

Initialize Metropolis Kernel.

Parameters:

  • ensemble (Ensemble) – an Ensemble instance to obtain the features and parameters used in computing log probabilities.

  • step_type (str) – string specifying the MCMC step type.

  • temperature (float) – temperature at which the MCMC sampling will be carried out.

  • args – positional arguments to instantiate the MCUsher for the corresponding step size.

  • kwargs – keyword arguments to instantiate the MCUsher for the corresponding step size.

valid_bias = ['FugacityBias', 'SquareChargeBias', 'SquareHyperplaneBias']#
valid_mcushers = ['Flip', 'Swap', 'MultiStep', 'Composite', 'TableFlip']#
class MulticellMetropolis(mckernels, temperature, kernel_probabilities=None, kernel_hop_periods=5, kernel_hop_probabilities=None, seed=None, **kwargs)[source]#

Bases: MetropolisAcceptMixin, ThermalKernelMixin, MulticellKernel

A Multicell Metropolis Hastings kernel.

This is useful for example when one wants to sample over different supercell shapes, i.e. for generating special quasi-random structures.

The ensembles in all kernels must have supercells of the same size, only the shape can change. All ensembles must be created from the same Hamiltonian. And all kernels must be of the same kind.

There is no requirement for the individual kernels to have the same step type, bias, or any other setup parameter, which allows very flexible sampling strategies. However, users are responsible for ensuring that the overall sampling strategy is correct! (i.e. satisfies balance or detailed balance).

Initialize MCKernel.

Parameters:

  • mckernels (list of MCKernels) – a list of MCKernels instances to obtain the features and parameters used in computing log probabilities.

  • temperature (float) – Temperature that kernel hops are attempted at.

  • seed (int) – optional non-negative integer to seed the PRNG

  • kernel_probabilities (Sequence of floats) – optional Probability for choosing each of the supplied kernels

  • kernel_hop_periods (int or Sequence of ints) – optional number of steps between kernel hop attempts.

  • kernel_hop_probabilities (Sequence of floats) – optional probabilities for choosing each of the specified hop periods.

property temperature#

Get the temperature of kernel.

valid_bias = None#
valid_mcushers = None#

A Wang-Landau kernel for multicanonical estimation of the density of states.

Based on: https://link.aps.org/doi/10.1103/PhysRevLett.86.2050

class WangLandau(ensemble, step_type, min_enthalpy, max_enthalpy, bin_size, *args, flatness=0.8, mod_factor=1.0, check_period=1000, update_period=1, mod_update=None, seed=None, **kwargs)[source]#

Bases: MCKernel

A Wang-Landau sampling kernel.

Allows wang-landau sampling method. Stores histogram and DOS in its instance.

Initialize a WangLandau Kernel.

Parameters:

  • ensemble (Ensemble) – The ensemble object to use to generate samples

  • step_type (str) – An MC step type corresponding to an MCUsher. See valid_mcushers

  • min_enthalpy (float) – The minimum enthalpy to sample. Enthalpy means the dot product of natural parameters and ensemble features. In canonical ensemble, it shall be the energy. In semigrand ensemble, it shall be E- mu N. Unit is eV scaled at the super-cell.

  • max_enthalpy (float) – The maximum enthalpy to sample.

  • bin_size (float) – The enthalpy bin size to determine different states.

  • flatness (float) – optional The flatness factor used when checking histogram flatness. Must be between 0 and 1.

  • mod_factor (float) – log of the initial modification factor used to update the DOS/entropy. Default is 1, which means the DOS shall be multiplied by e^1.

  • check_period (int) – optional The period in number of steps for the histogram flatness to be checked.

  • update_period (int) – optional The period in number of steps to update the histogram and entropy. In some cases periods slightly larger than each step, may allow more efficient exploration of energy space.

  • mod_update (float|Callable) – optional A function used to update the fill factor when the histogram satisfies the flatness criteria. It must monotonically decrease to 0. When a number is provided, at each update we will divide the mod factor by this number.

  • seed (int) – optional non-negative integer to seed the PRNG

  • args – Positional arguments to instantiate MCUsher.

  • kwargs – Keyword arguments to instantiate MCUsher.

property bin_size#

Enthalpy bin size.

compute_initial_trace(occupancy)[source]#

Compute initial values for sample trace given an occupancy.

Add the micro-canonical entropy and histograms to the trace. :type occupancy: :param occupancy: Initial occupancy :type occupancy: ndarray

Returns:

Trace

property dos#

Density of states on visited levels.

property entropy#

log(dos) on visited levels.

property histogram#

Histogram on visited levels.

property levels#

Visited enthalpy levels.

property mod_factor#

Mod factor.

set_aux_state(occupancy, *args, **kwargs)[source]#

Set the auxiliary occupancies based on an occupancy.

This is necessary for WangLandau to work properly because it needs to store the current enthalpy and features.

valid_bias = None#
valid_mcushers = ['Flip', 'Swap', 'MultiStep', 'Composite', 'TableFlip']#

A uniformly random kernel.

The UniformlyRandom kernel is equivalent to a Metropolis kernel with infinite temperature.

class UniformlyRandom(ensemble, step_type, *args, seed=None, bias_type=None, bias_kwargs=None, **kwargs)[source]#

Bases: MCKernel

A Kernel that accepts all proposed steps.

This kernel samples the random limit distribution where all states have the same probability (corresponding to an infinite temperature). If a bias is added then the corresponding distribution will be biased accordingly.

Initialize MCKernel.

Parameters:

  • ensemble (Ensemble) – an Ensemble instance to obtain the features and parameters used in computing log probabilities.

  • step_type (str) – string specifying the MCMC step type.

  • seed (int) – optional non-negative integer to seed the PRNG

  • bias_type (str) – optional name for bias type instance.

  • bias_kwargs (dict) – optional dictionary of keyword arguments to pass to the bias constructor.

  • args – positional arguments to instantiate the MCUsher for the corresponding step size.

  • kwargs – keyword arguments to instantiate the MCUsher for the corresponding step size.

valid_bias = ['FugacityBias', 'SquareChargeBias', 'SquareHyperplaneBias']#
valid_mcushers = ['Flip', 'Swap', 'MultiStep', 'Composite', 'TableFlip']#