enforce_composition#

libcasm.clexmonte.enforce_composition(
state: MonteCarloState,
target_mol_composition: Annotated[numpy.typing.ArrayLike, numpy.float64, '[m, 1]'],
system: System | None = None,
composition_calculator: CompositionCalculator | None = None,
semigrand_canonical_swaps: collections.abc.Sequence[OccSwap] | None = None,
occ_location: OccLocation = None,
engine: RandomNumberEngine | None = None,
) → None#

Apply grand canonical swaps to enforce a target composition

Method

  • Find which of the provided grand canonical swap types transforms the composition most closely to the target composition

  • If no swap can improve the composition, return

  • Propose and apply an event consistent with the found swap type

  • Repeat

Parameters:

  • state (MonteCarloState) – The state to modify to enforce a target composition

  • target_mol_composition (np.ndarray) – The target mol composition per unit cell, \(\vec{n}\).

  • system (Optional[System] = None) – System data. Used to get the composition calculator, get the allowed semi-grand canonical swaps, and construct occupant location list, unless they are provided explicitly.

  • composition_calculator (Optional[CompositionCalculator] = None) – Composition calculator. If not provided, the system composition calculator is used. Raises if neither system nor composition_calculator are provided.

  • semigrand_canonical_swaps (Optional[list[OccSwap]] = None) – Swaps to use to enforce composition. If not provided, the system semi-grand canonical swaps are used. Raises if neither system nor composition_calculator are provided.

  • occ_location (Optional[OccLocation] = None) – Current occupant location list. If provided, the user is responsible for ensuring it is up-to-date with the current occupation of state and it is used and updated during the run. If None, a occupant location list is generated for the function. Raises if neither system nor occ_location are provided.

  • engine (Optional[RandomNumberEngine] = None) – Optional random number engine to use.

On this page