Ensembles

CanonicalEnsemble

class mchammer.ensembles.CanonicalEnsemble(atoms=None, calculator=None, name='Canonical ensemble', data_container=None, random_seed=None, data_container_write_period=inf, ensemble_data_write_interval=None, trajectory_write_interval=None, boltzmann_constant=8.617330337217213e-05, *, temperature)

Canonical Ensemble.

Instances of this class allow one to simulate systems in the canonical ensemble (\(N_iVT\)), i.e. at constant temperature (\(T\)), number of species (\(N_i\)), and volume (\(V\)).

temperature

float – temperature \(T\) in appropriate units [commonly Kelvin]

boltzmann_constant

float – Boltzmann constant \(k_B\) in appropriate units, i.e. units that are consistent with the underlying cluster expansion and the temperature units [default: eV/K]

acceptance_ratio

acceptance ratio

Return type:float
atoms

current configuration (copy)

Return type:Atoms
attach_observer(observer, tag=None)

Attaches an observer to the ensemble.

Parameters:
  • observer (BaseObserver) – observer instance to attach
  • tag – name used in data container
calculator

calculator attached to the ensemble

Return type:BaseCalculator
data_container

data container associated with ensemble

Return type:DataContainer
get_random_sublattice_index()

Returns a random sublattice index based on the weights of the sublattice.

Todo

  • fix this method
  • add unit test
Return type:int
name

ensemble name

Return type:str
observer_interval

minimum number of steps to run Monte Carlo simulation without interruption for observation

Return type:int
observers
Return type:Dict[str, BaseObserver]
random_seed

seed used to initialize random number generator

Return type:int
reset_data_container()

Resets the data container and the trial step counter.

run(number_of_trial_steps, reset_step=False)

Samples the ensemble for the given number of trial steps.

Parameters:
  • number_of_trial_steps (int) – number of MC trial steps to run in total
  • reset_step (bool) – if True the MC trial step counter and the data container will be reset to zero and empty, respectively.
step

current Monte Carlo trial step

Return type:int
update_occupations(sites, species)

Updates the occupation vector of the configuration being sampled. This will change the state of the configuration in both the calculator and the configuration manager.

Parameters:
  • sites (List[int]) – indices of sites of the configuration to change
  • species (List[int]) – new occupations (species) by atomic number
Raises:

ValueError – if input lists are not of the same length

SemiGrandCanonicalEnsemble

class mchammer.ensembles.SemiGrandCanonicalEnsemble(atoms=None, calculator=None, name='Semi-grand canonical ensemble', data_container=None, random_seed=None, data_container_write_period=inf, ensemble_data_write_interval=None, trajectory_write_interval=None, boltzmann_constant=8.617330337217213e-05, *, temperature, chemical_potentials)

Semi-grand canonical (SGC) ensemble.

Instances of this class allow one to simulate systems in the SGC ensemble (\(N\Delta\mu_i VT\)), i.e. at constant temperature (\(T\)), total number of sites (\(N=\sum_i N_i\)), relative chemical potentials (\(\Delta\mu_i=\mu_i - \mu_1\), where \(i\) denotes the species), and volume (\(V\)).

The probability density of the SGC ensemble for a \(m\)-component system is

\[\rho_{\text{SGC}} = \exp\Big[ - \big( E + \sum_{i>1}^m \Delta\mu_i N_i \big) / k_B T \Big]\]

with the relative chemical potentials \(\Delta\mu_i = \mu_i - \mu_1\) and species counts \(N_i\).

temperature

float – temperature \(T\) in appropriate units [commonly Kelvin]

boltzmann_constant

float – Boltzmann constant \(k_B\) in appropriate units, i.e. units that are consistent with the underlying cluster expansion and the temperature units [default: eV/K]

acceptance_ratio

acceptance ratio

Return type:float
atoms

current configuration (copy)

Return type:Atoms
attach_observer(observer, tag=None)

Attaches an observer to the ensemble.

Parameters:
  • observer (BaseObserver) – observer instance to attach
  • tag – name used in data container
calculator

calculator attached to the ensemble

Return type:BaseCalculator
chemical_potentials

chemical potentials \(\mu_i\)

Return type:Dict[int, float]
data_container

data container associated with ensemble

Return type:DataContainer
get_random_sublattice_index()

Returns a random sublattice index based on the weights of the sublattice.

Todo

  • fix this method
  • add unit test
Return type:int
name

ensemble name

Return type:str
observer_interval

minimum number of steps to run Monte Carlo simulation without interruption for observation

Return type:int
observers
Return type:Dict[str, BaseObserver]
random_seed

seed used to initialize random number generator

Return type:int
reset_data_container()

Resets the data container and the trial step counter.

run(number_of_trial_steps, reset_step=False)

Samples the ensemble for the given number of trial steps.

Parameters:
  • number_of_trial_steps (int) – number of MC trial steps to run in total
  • reset_step (bool) – if True the MC trial step counter and the data container will be reset to zero and empty, respectively.
step

current Monte Carlo trial step

Return type:int
update_occupations(sites, species)

Updates the occupation vector of the configuration being sampled. This will change the state of the configuration in both the calculator and the configuration manager.

Parameters:
  • sites (List[int]) – indices of sites of the configuration to change
  • species (List[int]) – new occupations (species) by atomic number
Raises:

ValueError – if input lists are not of the same length