Ensembles

CanonicalEnsemble

class mchammer.ensembles.CanonicalEnsemble(atoms=None, calculator=None, name='Canonical ensemble', data_container=None, random_seed=None, ensemble_data_write_interval=None, **kwargs)

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
do_trial_step()

Carries out one Monte Carlo trial step.

get_ensemble_data()

Returns the data associated with the ensemble. For the SGC ensemble this specifically includes the temperature and the species counts.

Return type:Dict[~KT, ~VT]
get_property_change(sites, species)

Computes and returns the property change due to a change of the configuration.

_N.B.:_ This method leaves to configuration itself unchanged.

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

float

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
next_random_number()

Returns the next random number from the PRNG.

Return type:int
observer_interval

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

Return type:int
observers
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, ensemble_data_write_interval=None, trajectory_write_interval=None, **kwargs)

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
do_trial_step()

Carries out one Monte Carlo trial step.

get_ensemble_data()

Returns the data associated with the ensemble. For the SGC ensemble this specifically includes the temperature and the species counts.

Return type:Dict[~KT, ~VT]
get_property_change(sites, species)

Computes and returns the property change due to a change of the configuration.

_N.B.:_ This method leaves to configuration itself unchanged.

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

float

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
next_random_number()

Returns the next random number from the PRNG.

Return type:int
observer_interval

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

Return type:int
observers
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