Trial Move Generators

Trial moves used in Monte Carlo (MC) sampling in Clease are provided from clease.montecarlo.trial_move_generator.TrialMoveGenerator classes.

The API

class clease.montecarlo.trial_move_generator.TrialMoveGenerator(max_attempts: int = 10000)

Bases: ABC

Class for producing trial moves.

Parameters:

max_attempts – Maximum number of attempts to try to find a move that passes the constraints. If not constraints are added, this has no effect.

__init__(max_attempts: int = 10000)

initialize(atoms: Atoms) → None

Initialize the generator.

Parameters:

atoms – Atoms object used in the simulation

remove_constraints() → None

Remove all constraints

property name

add_constraint(cnst: MCConstraint)

Add a constraint to the generator

Parameters:

cnst – Constraint that must be satisfied for all trial moves

abstractmethod get_single_trial_move() → Sequence[SystemChange]

Return a single trial move, must be implemented in sub-classes

get_trial_move() → Sequence[SystemChange]

Produce a trial move that is consistent with all cosntraints

on_move_accepted(changes: Sequence[SystemChange]) → None

Callback that is called by Monte Carlo after each accepted move

param change:

Seqeunce of trial moves performed

on_move_rejected(changes: Sequence[SystemChange]) → None

Callback that is called after a move is rejected

Parameters:

change – Seqeunce of trial moves performed

class clease.montecarlo.trial_move_generator.SingleTrialMoveGenerator(**kwargs)

Bases: TrialMoveGenerator, ABC

Interface class for generators that return only one type of trial moves

CHANGE_NAME = None

__init__(**kwargs)

name_matches(change: SystemChange) → bool

Return true of the name of the passed system change matches the CHANGE_NAME attribute.

Parameters:

change – a system change

made_changes(changes: Sequence[SystemChange]) → List[SystemChange]

Extract the subset system changes made by an instance of itself. This method can be overrided in sublcasses, but the default behavior is to extract the subset of changes where the name matches.

class clease.montecarlo.trial_move_generator.RandomFlip(symbols: Set[str], atoms: Atoms, indices: List[int] | None = None, **kwargs)

Bases: SingleTrialMoveGenerator

Generate trial moves where the symbol at a given site is flipped

Parameters:

• symbols – Set with all symbols considered in a move

• atoms – Atoms object for the simulation

• indices – List with all indices that should be considered. If None, all indices are considered

CHANGE_NAME = 'flip_move'

__init__(symbols: Set[str], atoms: Atoms, indices: List[int] | None = None, **kwargs)

get_single_trial_move() → List[SystemChange]

Get a random flip of an included site into a different element.

class clease.montecarlo.trial_move_generator.RandomSwap(atoms: Atoms, indices: List[int] | None = None, **kwargs)

Bases: SingleTrialMoveGenerator

Produce random swaps

Parameters:

• atoms – Atoms object in the MC simulation

• indices – List with indices that can be chosen from. If None, all indices can be chosen.

CHANGE_NAME = 'swap_move'

__init__(atoms: Atoms, indices: List[int] | None = None, **kwargs)

get_single_trial_move() → List[SystemChange]

Create a swap move

on_move_accepted(changes: Sequence[SystemChange])

Callback that is called by Monte Carlo after each accepted move

param change:

Seqeunce of trial moves performed

is_tracked(index: int) → bool

Check if a given index is being tracked.

class clease.montecarlo.trial_move_generator.MixedSwapFlip(atoms: Atoms, swap_indices: Sequence[int], flip_indices: Sequence[int], flip_symbols: Sequence[str], flip_prob: float = 0.5, **kwargs)

Bases: TrialMoveGenerator

Class for generating trial moves in a mixed ensemble. A subset of the sites should maintain a constant concentrations, and a subset should maintain constant chemical potential. Thus, for the subset of sites where the concentration should be fixed, swap moves are proposed and for the subset that should have constant chemical potentia, flip moves are probosed (e.g. switching symbol type on a site)

Parameters:

• atoms – Atoms object used in the simulation

• swap_indices – List of indices that constitue the sub-lattice that should have fixed concentration

• flip_indices – List of indices that constitute the sub-lattice that should have fixed chemical potential

• flip_symbols – List of possible symbols that can be substituted on the lattice with fixed chemical potential.

• flip_prob – Probability of returning a flip move. The probability of returning a swap move is then 1 - flip_prob.

__init__(atoms: Atoms, swap_indices: Sequence[int], flip_indices: Sequence[int], flip_symbols: Sequence[str], flip_prob: float = 0.5, **kwargs) → None

property generators: Tuple[SingleTrialMoveGenerator]

property weights: Tuple[float]

The probability weights for each generator

initialize(atoms: Atoms) → None

Initialize the trial move generator

get_single_trial_move() → Sequence[SystemChange]

Produce a single trial move. Return a swap move with probability

on_move_accepted(changes: Sequence[SystemChange])

Callback triggered when a move have been accepted.

on_move_rejected(changes: Sequence[SystemChange]) → None

Callback triggered when a move have been accepted.

class clease.montecarlo.trial_move_generator.RandomFlipWithinBasis(symbols: Sequence[Sequence[str]], atoms: Atoms, indices: Sequence[Sequence[int]] | None = None, **kwargs)

Bases: SingleTrialMoveGenerator

Produce trial moves consisting of flips within each basis. Each basis is defined by a list of indices.

Parameters:

• symbols – Sequence allowed symbols in each basis

• atoms – Atoms object to be used in the simulation for which the trial moves are produced

• indices – Sequence of sets of indices where each set specify the indices of a basis. Note len(symbols) == len(indices)

Example:

Create a generator for a rocksalt structure with two basis

>>> from ase.build import bulk
>>> from clease.montecarlo import RandomFlipWithinBasis
>>> atoms = bulk("LiO", crystalstructure="rocksalt", a=3.9)*(3, 3, 3)
>>> basis1 = [a.index for a in atoms if a.symbol == "Li"]
>>> basis2 = [a.index for a in atoms if a.symbol == "O"]
>>> generator = RandomFlipWithinBasis([["Li", "X"], ["O", "V"]], atoms, [basis1, basis2])

CHANGE_NAME = 'flip_within_basis_move'

__init__(symbols: Sequence[Sequence[str]], atoms: Atoms, indices: Sequence[Sequence[int]] | None = None, **kwargs)

get_single_trial_move() → Sequence[SystemChange]

Produce a trial move by choosing a random flipper