MCUshers#

Implementations of MCMC Usher classes.

An usher is used to generate step proposals for MC Monte Carlo sampling. For example a Flipper simply proposes a change of the identity of a species at a site for use in a SemiGrand ensemble. A Swapper will propose a swap between species at two sites for use in Canonical ensemble simulations.

More complex steps can be defined simply by deriving from the MCUsher.

class Composite(sublattices, mcushers, mcusher_weights=None, rng=None)[source]#

Bases: MCUsher

A composite usher for chaining different step types.

This can be used to mix step types for all sublattices or to create hybrid ensembles where different sublattices have different allowed steps.

Initialize the composite usher.

Parameters:

  • sublattices (list of Sublattice) – list of active Sublattices to propose steps for. Active sublattices are those that include sites with configuration degrees of freedom DOFs, only occupancy on active sub-lattices’ active sites are allowed to change.

  • mcushers (list of MCUsher) – A list of mcushers to add to the composite.

  • mcusher_weights (list of float) – A list of the weights associated with each mcusher passed. With this the corresponding probabilities for each mcusher to be picked are generated. Must be in the same order as the mcusher list.

  • rng (np.Generator) – optional The given PRNG must be the same instance as that used by the kernel and any bias terms, otherwise reproducibility will be compromised.

add_mcusher(mcusher, weight=1)[source]#

Add an MCUsher to the Composite usher.

Parameters:

  • mcusher (MCUsher) – The MCUsher to add

  • weight (float) – The weight associated with the mcusher being added

property mcushers#

Get the list of mcushers.

propose_step(occupancy)[source]#

Propose a step given an occupancy.

property weight#

Get the weights associated with each mcusher.

class Flip(sublattices, sublattice_probabilities=None, rng=None)[source]#

Bases: MCUsher

Implementation of a simple flip step at a random site.

Initialize MCMCStep.

Parameters:

  • sublattices (list of Sublattice) – list of active Sublattices to propose steps for. Active sublattices are those that include sites with configuration degrees of freedom DOFs, only occupancy on active sub-lattices’ active sites are allowed to change.

  • sublattice_probabilities (list of float) – optional list of probabilities to pick a site from specific active sublattices.

  • rng (np.Generator) – optional The given PRNG must be the same instance as that used by the kernel and any bias terms, otherwise reproducibility will be compromised.

propose_step(occupancy)[source]#

Propose a single random flip step.

A step is given as a sequence of tuples, where each tuple is of the form (site index, species code to set)

Parameters:

occupancy (ndarray) – encoded occupancy string.

Returns:

list of tuples each with (index, code)

Return type:

list(tuple)

class MultiStep(sublattices, mcusher, step_lengths, step_probabilities=None, rng=None)[source]#

Bases: MCUsher

A multistep usher to generate steps of several flips.

Any usher can be used to chain steps, ie create multi flip steps, multi swap steps even multi composite steps, etc.

Initialize a multistep usher.

Parameters:

  • sublattices (list of Sublattice) – list of active Sublattices to propose steps for. Active sublattices are those that include sites with configuration degrees of freedom DOFs, only occupancy on active sub-lattices’ active sites are allowed to change.

  • mcusher (MCUsher) – An instantiated MCUsher to use to create multisteps.

  • step_lengths (int or Sequence of int) – The length or lengths of steps. If given a sequence of sizes, a size is chosen at each proposal according to step_probabilities. The step length proposed may be less in cases where the same site is chosen more than once. This should become less and less likely for larger supercells.

  • step_probabilities (Sequence of float) – optional A sequence of probabilities corresponding to the step lengths provided. If none is given, then a uniform probability is used.

  • rng (np.Generator) – optional The given PRNG must be the same instance as that used by the kernel and any bias terms, otherwise reproducibility will be compromised.

propose_step(occupancy)[source]#

Propose a step given an occupancy.

property sublattice_probabilities#

Get the probabilities of choosing a sublattice.

class Swap(sublattices, sublattice_probabilities=None, rng=None)[source]#

Bases: MCUsher

Implementation of a simple swap step for two random sites.

Initialize MCMCStep.

Parameters:

  • sublattices (list of Sublattice) – list of active Sublattices to propose steps for. Active sublattices are those that include sites with configuration degrees of freedom DOFs, only occupancy on active sub-lattices’ active sites are allowed to change.

  • sublattice_probabilities (list of float) – optional list of probabilities to pick a site from specific active sublattices.

  • rng (np.Generator) – optional The given PRNG must be the same instance as that used by the kernel and any bias terms, otherwise reproducibility will be compromised.

propose_step(occupancy)[source]#

Propose a single random swap step.

A step is given as a sequence of tuples, where each tuple is of the form (site index, species code to set)

Parameters:

occupancy (ndarray) – encoded occupancy string.

Returns:

list of tuples each with (index, code)

Return type:

list(tuple)

class TableFlip(sublattices, rng=None, flip_table=None, charge_balanced=True, other_constraints=None, optimize_basis=False, table_ergodic=False, flip_weights=None, swap_weight=0.1)[source]#

Bases: MCUsher

Implementation of table flips.

Use user-specified or auto-calculated flip tables. Does not check the correctness of the flip tables.

No longer computing and assigning a-priori proabilities before flip selection, and selects sites instead.

Direct use of this class is not recommended, because the dict form of the flip table is not very easy to read and write.

Initialize TableFlip.

Parameters:

  • sublattices (list of Sublattice) – list of Sublattices to propose steps for. Must be all sublattices, including active and inactive ones.

  • rng (np.Generator) – optional The given PRNG must be the same instance as that used by the kernel and any bias terms, otherwise reproducibility will be compromised.

  • flip_table (2D np.ndarray[int]) – Flip vectors in “n” format, as generated by a CompositionSpace. If not given, we will initialize a CompositionSpace from sublattice information, and calculate the flip table with that CompositionSpace. Notice: 1, We suggest you provide a pre-computed flip table, unless the number of sites in sub-lattices can be reduced to very small when divided with their GCD. 2, As implemented in the Sublattice class, you are allowed to have multiple species on an inactive sub-lattice, but it is not the suggested approach. In this case, you have 3 choices. Either always try to split until all inactive sub-lattices only have one species (suggested), fixing number of inactive species as a constraint, or pre-compute your own flip table.

  • charge_balanced (bool) – optional Whether to add charge balance constraint. Default to true.

  • other_constraints (List[tuple(1D arrayLike[int], int)]) – optional Other integer constraints except charge balance and site-number conservation. Should be given in the form of tuple(a, bb), each gives constraint np.dot(a, n)=bb.

  • optimize_basis (bool) – optional Whether to optimize the basis to minimal flip sizes and maximal connectivity in the minimum super-cell size. When the minimal super-cell size is large, we recommend not to optimize basis.

  • table_ergodic (bool) – optional When generating a flip table, whether to add vectors and ensure ergodicity under a minimal super-cell size. Default to False. When the minimal super-cell size is large, we recommend not to ensure ergodicity. This is not only because of the computation difficulty; but also because at large super-cell size, the fraction of inaccessible compositions usually becomes minimal.

  • swap_weight (float) – optional Percentage of canonical swaps to attempt. Should be a positive value, but smaller than 1. Default to 0.1.

  • flip_weights (1D Arraylike) – optional Weights to adjust probability of each flip. If None given, will assign equal weights to each flip vector and its inverse. Length must equal to 2*len(flip_table).

Note

In table flip, adding proposal bias to different sub-lattices is not meaningful. We will always assign sub-lattice probabilities as equal.

compute_log_priori_factor(occupancy, step)[source]#

Compute a-priori weight to adjust step acceptance ratio.

This is essential in keeping detailed balance. Return log for numerical accuracy.

Arg:
occupancy (ndarray):

encoded occupancy string. (Processor encoding.)

step (list[tuple]):

Metropolis step. list of tuples each with (index, code). (Processor encoding.)

Returns:

log of a-priori adjustment ratio.

Return type:

float

propose_step(occupancy)[source]#

Propose a single random flip step.

A step is given as a sequence of tuples, where each tuple is of the form (site index, species code to set)

1, Pick a flip in table; 2, Choose sites from site specie statistics list according to the flip. 3, (Acceptance proability will be adjusted according to a-priori

weight to enforce detailed balance.)

4, If selection failed, may or may not attempt a canonical swap based

on self.add_swap parameter.

There are circumstances where the current occupancy can not be accessed by minimal table flips. This method does not take care of that, please be careful when choosing starting compositions.

Parameters:

occupancy (ndarray) – encoded occupancy string.

Returns:

list of tuples each with (idex, code).

Return type:

list(tuple)

available_step_types()[source]#

Get available step types.

Return type:

tuple[str]

mcusher_factory(usher_type, sublattices, *args, **kwargs)[source]#

Get a MC Usher from string name.

Parameters:

  • usher_type (str) – string specifying step to instantiate.

  • sublattices (list of Sublattice) – list of Sublattices to propose steps for.

  • *args – positional arguments passed to class constructor

  • **kwargs – keyword arguments passed to class constructor

Returns:

instance of derived class.

Return type:

MCUsher