# 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.

temperature

float – temperature in Kelvin.

boltzmann_constant

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

acceptance_ratio

acceptance ratio, i.e. accepted_trials / total_trials.

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

Attaches an observer to the ensemble.

Parameters: observer (mchammer Observer object) –
calculator

mchammer Calculator.

data_container

mchammer DataContainer object

do_trial_step()

Do a trial step.

get_ensemble_data()

Returns a dict with the default data of the ensemble.

Here the temperature are added to the default data.

Returns: dict ensemble data key pairs Dict[~KT, ~VT]
get_property_change(indices, elements)

Get the property change for a hypothetical change of the input indices, elements.

Parameters: indices (list of int) – refer to indices in the lattice elements (list of int) – refer to atomic species change in property value float float
get_random_sublattice_index()

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

Returns: sublattice_index int int
name

str – Name of BaseEnsemble.

next_random_number()

Returns the next random number from the RNG.

observer_interval

int – minimum number of steps to run Monte Carlo simulation without observation interruptions.

observers

dict – mchammer observers.

random_seed

int – Random seed used in random number generator.

reset_data_container()

Resets the data container and the internal step attribute.

run(number_of_trial_steps, reset_step=False)

Samples the ensemble for number_of_trial_steps steps.

Parameters: number_of_trial_steps (int) – number of steps to run in total reset_step (bool) – if True the MC trial step counter will be initialized to zero
step

int – current MC trial step

Return type: int
structure

ASE Atoms object – The current state of the structure being sampled in the ensemble.

update_occupations(list_of_sites, list_of_elements)

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

Parameters: list_of_sites (list of int) – list of indices of the configuration to change. list_of_elements (list of int) – list of elements to put on the lattice sites the indices refer to. ValueError : if list_of_sites are not the same length – as list_of_elements

## 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, **kwargs)

Semi-grand canonical (SGC) ensemble.

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 c_i \big) / k_B T \Big]$

with the relative chemical potentials $$\Delta\mu_i = \mu_i - \mu_1$$ and concentrations $$c_i = N_i / N_\text{total}$$

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, i.e. accepted_trials / total_trials.

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

Attaches an observer to the ensemble.

Parameters: observer (mchammer Observer object) –
calculator

mchammer Calculator.

chemical_potentials

dict – chemical potentials $$\mu_i$$

data_container

mchammer DataContainer object

do_trial_step()

Carry out one Monte Carlo trial step.

get_ensemble_data()

Returns a dict with the default data of the ensemble.

Here the temperature and element counts are added to the default data.

Returns: dict ensemble data key pairs Dict[~KT, ~VT]
get_property_change(indices, elements)

Get the property change for a hypothetical change of the input indices, elements.

Parameters: indices (list of int) – refer to indices in the lattice elements (list of int) – refer to atomic species change in property value float float
get_random_sublattice_index()

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

Returns: sublattice_index int int
name

str – Name of BaseEnsemble.

next_random_number()

Returns the next random number from the RNG.

observer_interval

int – minimum number of steps to run Monte Carlo simulation without observation interruptions.

observers

dict – mchammer observers.

random_seed

int – Random seed used in random number generator.

reset_data_container()

Resets the data container and the internal step attribute.

run(number_of_trial_steps, reset_step=False)

Samples the ensemble for number_of_trial_steps steps.

Parameters: number_of_trial_steps (int) – number of steps to run in total reset_step (bool) – if True the MC trial step counter will be initialized to zero
step

int – current MC trial step

Return type: int
structure

ASE Atoms object – The current state of the structure being sampled in the ensemble.

update_occupations(list_of_sites, list_of_elements)

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

Parameters: list_of_sites (list of int) – list of indices of the configuration to change. list_of_elements (list of int) – list of elements to put on the lattice sites the indices refer to. ValueError : if list_of_sites are not the same length – as list_of_elements