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
Return type:ensemble data key pairs
Return type: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
Returns:

change in property value

Return type:

float

Return type:

float

get_random_sublattice_index()

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

Returns:sublattice_index
Return type:int
Return type: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.
Raises:

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
Return type:ensemble data key pairs
Return type: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
Returns:

change in property value

Return type:

float

Return type:

float

get_random_sublattice_index()

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

Returns:sublattice_index
Return type:int
Return type: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.
Raises:

ValueError : if list_of_sites are not the same length – as list_of_elements

VCSGC