Monte-Carlo sample generators#

This module contains classes and functions to sample training structures using Monte-Carlo at an increasing series of temperatures, given a specific supercell matrix and a constant composition or chemical potentials.

Class are implemented with smol.moca.

Monte-carlo to estimate ground states and sample structures.

class CanonicalSampleGenerator(ce, sc_matrix, counts, anneal_temp_series=None, heat_temp_series=None, num_steps_anneal=None, num_steps_heat=None, duplicacy_criteria='correlations', remove_decorations_before_duplicacy=False)[source]#

Bases: McSampleGenerator

Sample generator in canonical ensembles.

Initialize.

Parameters:

  • ce (ClusterExpansion) – A cluster expansion object to enumerate with.

  • sc_matrix (3*3 ArrayLike) – Supercell matrix to solve on.

  • counts (1D ArrayLike of int) – Composition in the “counts “ format, not normalized by number of primitive cells per super-cell. Refer to smol.moca.composition for explanation.

  • anneal_temp_series (list of float) – optional A series of temperatures to use in simulated annealing. Must be strictly decreasing.

  • heat_temp_series (list of float) – optional A series of increasing temperatures to sample on. Must be strictly increasing

  • num_steps_anneal (int) – optional The number of steps to run per simulated annealing temperature.

  • num_steps_heat (int) – optional The number of steps to run per heat temperature.

  • duplicacy_criteria (str) – The criteria when to consider two structures as the same and old to add one of them into the candidate training set. Default is “correlations”, which means to assert duplication if two structures have the same correlation vectors. While “structure” means two structures must be symmetrically equivalent after being reduced. No other option is allowed. Note that option “structure” might be significantly slower since it has to attempt reducing every structure to its primitive cell before matching. It should be used with caution.

  • remove_decorations_before_duplicacy (bool) – optional Whether to remove all decorations from species (i.e, charge and other properties) before comparing duplicacy. Default to false. Only valid when duplicacy_criteria=”structure”.

property ensemble#

CanonicalEnsemble.

property sampler#

A sampler to sample structures.

class McSampleGenerator(ce, sc_matrix, anneal_temp_series=None, heat_temp_series=None, num_steps_anneal=None, num_steps_heat=None, duplicacy_criteria='correlations', remove_decorations_before_duplicacy=False)[source]#

Bases: object

Abstract monte-carlo sampler class.

Allows finding the ground state, and then gradually heats up the ground state to generate an unfrozen sample.

Each Generator should only handle one composition (canonical) or one set of chemical potentials (grand-canonical)!

Initialize.

Parameters:

  • ce (ClusterExpansion) – A cluster expansion object to enumerate with.

  • sc_matrix (3*3 ArrayLike) – Supercell matrix to solve on.

  • anneal_temp_series (list of float) – optional A series of temperatures to use in simulated annealing. Must be strictly decreasing.

  • heat_temp_series (list of float) – optional A series of increasing temperatures to sample on. Must be strictly increasing

  • num_steps_anneal (int) – optional The number of MC steps to run per annealing temperature.

  • num_steps_heat (int) – optional The number of MC steps to run per heating temperature.

  • duplicacy_criteria (str) – The criteria when to consider two structures as the same and old to add one of them into the candidate training set. Default is “correlations”, which means to assert duplication if two structures have the same correlation vectors. While “structure” means two structures must be symmetrically equivalent after being reduced. No other option is allowed. Note that option “structure” might be significantly slower since it has to attempt reducing every structure to its primitive cell before matching. It should be used with caution.

  • remove_decorations_before_duplicacy (bool) – optional Whether to remove all decorations from species (i.e, charge and other properties) before comparing duplicacy. Default to false. Only valid when duplicacy_criteria=”structure”.

default_anneal_temp_series = [5000, 3200, 1600, 1000, 800, 600, 400, 200, 100]#
default_heat_temp_series = [500, 2000, 5000, 12000]#
abstract property ensemble#

Get ensemble to run.

get_ground_state_features()[source]#

Get the feature vector of the ground state.

Returns:

list of float.

get_ground_state_occupancy()[source]#

Use simulated annealing to solve the ground state occupancy.

Returns:

The ground-state occupancy string obtained through simulated annealing.

Return type:

list of int

get_ground_state_structure()[source]#

Get the ground state structure.

Returns:

Structure.

get_unfrozen_sample(previous_sampled_structures=None, previous_sampled_features=None, num_samples=100)[source]#

Generate a sample of structures by heating the ground state.

Parameters:

  • previous_sampled_structures (list of Structure) – optional Sample structures already calculated in past iterations.

  • previous_sampled_features (list of ArrayLike) – optional Feature vectors of sample structures already calculated in past iterations.

  • num_samples (int) – optional Maximum number of samples to draw per unfreezing run. Since Structures must be de-duplicated, the actual number of structures returned might be fewer than this threshold. Default to 100.

Returns:

New samples structures, NOT including the ground-state, sampled occupancy arrays, and feature vectors of sampled structures.

Return type:

list of Structure, list of lists of int, list of lists of float

property n_steps_per_scan#

Least number of steps required to span configurations.

property num_steps_anneal#

Number of steps to run at each temperature when annealing.

property num_steps_heat#

Number of steps to run at each temperature when annealing.

property processor#

Get Processor.

property sampler#

Sampler to run.

property sublattices#

Get sublattices in ensemble.

Note

If you wish to do delicate operations such as sub-lattice splitting, please do it on self.ensemble. Refer to smol.moca.ensemble for further details.

class SemigrandSampleGenerator(ce, sc_matrix, chemical_potentials, anneal_temp_series=None, heat_temp_series=None, num_steps_anneal=None, num_steps_heat=None, duplicacy_criteria='correlations', remove_decorations_before_duplicacy=False)[source]#

Bases: McSampleGenerator

Sample generator in semi-grand canonical ensembles.

Initialize.

Parameters:

  • ce (ClusterExpansion) – A cluster expansion object to enumerate with.

  • sc_matrix (3*3 ArrayLike) – Supercell matrix to solve on.

  • chemical_potentials (dict) – Chemical potentials of each species. See documentation of smol.moca.ensemble.

  • anneal_temp_series (list of float) – optional A series of temperatures to use in simulated annealing. Must be strictly decreasing.

  • heat_temp_series (list of float) – optional A series of increasing temperatures to sample on. Must be strictly increasing.

  • num_steps_anneal (int) – optional The number of steps to run per simulated annealing temperature.

  • num_steps_heat (int) – optional The number of steps to run per heat temperature.

  • duplicacy_criteria (str) – The criteria when to consider two structures as the same and old to add one of them into the candidate training set. Default is “correlations”, which means to assert duplication if two structures have the same correlation vectors. While “structure” means two structures must be symmetrically equivalent after being reduced. No other option is allowed. Note that option “structure” might be significantly slower since it has to attempt reducing every structure to its primitive cell before matching. It should be used with caution.

  • remove_decorations_before_duplicacy (bool) – optional Whether to remove all decorations from species (i.e, charge and other properties) before comparing duplicacy. Default to false. Only valid when duplicacy_criteria=”structure”.

property ensemble#

CanonicalEnsemble.

property sampler#

A sampler to sample structures.

mcgenerator_factory(mcgenerator_name, *args, **kwargs)[source]#

Create a McSampleGenerator with its subclass name.

Parameters:

  • mcgenerator_name (str) – The name of a subclass of McSampleGenerator.

  • *args – Arguments used to initialize the class.

  • **kwargs –

    Arguments used to initialize the class.