Ensembles¶
Canonical ensemble¶

class
mchammer.ensembles.
CanonicalEnsemble
(atoms, calculator, temperature, user_tag=None, boltzmann_constant=8.617330337217213e05, data_container=None, random_seed=None, data_container_write_period=inf, ensemble_data_write_interval=None, trajectory_write_interval=None)[source]¶ Instances of this class allow one to simulate systems in the canonical ensemble (\(N_iVT\)), i.e. at constant temperature (\(T\)), number of atoms of each species (\(N_i\)), and volume (\(V\)).
The probability for a particular state in the canonical ensemble is proportional to the wellknown Boltzmann factor,
\[\rho_{\text{C}} \propto \exp [  E / k_B T ].\]Since the concentrations or equivalently the number of atoms of each species is held fixed in the canonical ensemble, a trial step must conserve the concentrations. This is accomplished by randomly picking two unlike atoms and swapping their identities. The swap is accepted with probability
\[P = \min \{ 1, \, \exp [  \Delta E / k_B T ] \},\]where \(\Delta E\) is the change in potential energy caused by the swap.
The canonical ensemble provides an ideal framework for studying the properties of a system at a specific concentration. Properties such as potential energy or phenomena such as chemical ordering at a specific temperature can conveniently be studied by simulating at that temperature. The canonical ensemble is also a convenient tool for “optimizing” a system, i.e., finding its lowest energy chemical ordering. In practice, this is usually achieved by simulated annealing, i.e. the system is equilibrated at a high temperature, after which the temperature is continuously lowered until the acceptance probability is almost zero. In a wellbehaved system, the chemical ordering at that point corresponds to a lowenergy structure, possibly the global minimum at that particular concentration.
Parameters:  atoms (
Atoms
) – atomic configuration to be used in the Monte Carlo simulation; also defines the initial occupation vector  calculator (
BaseCalculator
) – calculator to be used for calculating the potential changes that enter the evaluation of the Metropolis criterion  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]
 user_tag (str) – humanreadable tag for ensemble [default: None]
 data_container (str) – name of file the data container associated with the ensemble will be written to; if the file exists it will be read, the data container will be appended, and the file will be updated/overwritten
 random_seed (int) – seed for the random number generator used in the Monte Carlo simulation
 ensemble_data_write_interval (int) – interval at which data is written to the data container; this includes for example the current value of the calculator (i.e. usually the energy) as well as ensembles specific fields such as temperature or the number of atoms of different species
 data_container_write_period (float) – period in units of seconds at which the data container is written to file; writing periodically to file provides both a way to examine the progress of the simulation and to back up the data [default: np.inf]
 trajectory_write_interval (int) – interval at which the current occupation vector of the atomic configuration is written to the data container.

acceptance_ratio
¶ acceptance ratio
Return type: float

accepted_trials
¶ number of accepted trial steps
Return type: int

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
 observer (

boltzmann_constant
¶ Boltzmann constant \(k_B\) (see parameters section above)
Return type: float

calculator
¶ calculator attached to the ensemble
Return type: BaseCalculator

data_container
¶ data container associated with ensemble
Return type: DataContainer

data_container_write_period
¶ data container write period
Return type: float

ensemble_parameters
¶ Returns parameters associated with the ensemble.
Return type: dict

get_random_sublattice_index
()[source]¶ Returns a random sublattice index based on the weights of the sublattice.
Todo
 add unit test
Return type: int

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.
 number_of_trial_steps (

sublattices
¶ sublattices for the configuration being sampled
Return type: Sublattices

temperature
¶ temperature \(T\) (see parameters section above)
Return type: float

total_trials
¶ number of Monte Carlo trial steps
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 sites (

user_tag
¶ tag used for labeling the ensemble
Return type: str

write_data_container
(outfile)¶ Updates last state of the Monte Carlo simulation and writes DataContainer to file.
Parameters: outfile ( Union
[str
,Binaryio
,Textio
]) – file to which to write
 atoms (
Canonical annealing¶

class
mchammer.ensembles.
CanonicalAnnealing
(atoms, calculator, T_start, T_stop, n_steps, cooling_function='exponential', user_tag=None, boltzmann_constant=8.617330337217213e05, data_container=None, random_seed=None, data_container_write_period=inf, ensemble_data_write_interval=None, trajectory_write_interval=None)[source]¶ Instances of this class allow one to carry out simulated annealing in the canonical ensemble, i.e. the temperature is varied in predefined fashion while the composition is kept fixed. See
mchammer.ensembles.CanonicalEnsemble
for more information about the standard canonical ensemble.The canonical annealing ensemble can be useful, for example, for finding ground states or generating low energy configurations.
The temperature control scheme is selected via the
cooling_function
keyword argument, while the initial and final temperature are set via theT_start
andT_stop
arguments. Several predefined temperature control schemes are available including linear and exponential. In the latter case the temperature varies logarithmatically as a function of the MC step, emulating the exponential temperature dependence of the atomic exchange rate encountered in many materials. It is also possible to provide a user defined cooling function via the keyword argument. This function must comply with the following function header:def cooling_function(step, T_start, T_stop, n_steps): T = ... # compute temperature return T
Here
step
refers to the current MC trial step.Parameters:  atoms (
Atoms
) – atomic configuration to be used in the Monte Carlo simulation; also defines the initial occupation vector  calculator (
BaseCalculator
) – calculator to be used for calculating the potential changes that enter the evaluation of the Metropolis criterion  T_start (float) – temperature from which the annealing is started
 T_stop (float) – final temperature for annealing
 n_steps (int) – number of steps to take in the annealing simulation
 cooling_function (str/function) – to use the predefined cooling functions provide a string linear or exponential, otherwise provide a function
 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]
 user_tag (str) – humanreadable tag for ensemble [default: None]
 data_container (str) – name of file the data container associated with the ensemble will be written to; if the file exists it will be read, the data container will be appended, and the file will be updated/overwritten
 random_seed (int) – seed for the random number generator used in the Monte Carlo simulation
 ensemble_data_write_interval (int) – interval at which data is written to the data container; this includes for example the current value of the calculator (i.e. usually the energy) as well as ensembles specific fields such as temperature or the number of atoms of different species
 data_container_write_period (float) – period in units of seconds at which the data container is written to file; writing periodically to file provides both a way to examine the progress of the simulation and to back up the data [default: np.inf]
 trajectory_write_interval (int) – interval at which the current occupation vector of the atomic configuration is written to the data container.

T_start
¶ Starting temperature
Return type: float

T_stop
¶ Starting temperature
Return type: float

acceptance_ratio
¶ acceptance ratio
Return type: float

accepted_trials
¶ number of accepted trial steps
Return type: int

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
 observer (

boltzmann_constant
¶ Boltzmann constant \(k_B\) (see parameters section above)
Return type: float

calculator
¶ calculator attached to the ensemble
Return type: BaseCalculator

data_container
¶ data container associated with ensemble
Return type: DataContainer

data_container_write_period
¶ data container write period
Return type: float

ensemble_parameters
¶ Returns parameters associated with the ensemble.
Return type: dict

get_random_sublattice_index
()[source]¶ Returns a random sublattice index based on the weights of the sublattice.
Todo
 add unit test
Return type: int

n_steps
¶ Number of steps to carry out
Return type: int

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.

sublattices
¶ sublattices for the configuration being sampled
Return type: Sublattices

temperature
¶ Current temperature
Return type: float

total_trials
¶ number of Monte Carlo trial steps
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 sites (

user_tag
¶ tag used for labeling the ensemble
Return type: str

write_data_container
(outfile)¶ Updates last state of the Monte Carlo simulation and writes DataContainer to file.
Parameters: outfile ( Union
[str
,Binaryio
,Textio
]) – file to which to write
 atoms (
Semigrand canonical ensemble¶

class
mchammer.ensembles.
SemiGrandCanonicalEnsemble
(atoms, calculator, temperature, chemical_potentials, user_tag=None, data_container=None, random_seed=None, data_container_write_period=inf, ensemble_data_write_interval=None, trajectory_write_interval=None, boltzmann_constant=8.617330337217213e05)[source]¶ Instances of this class allow one to simulate systems in the semigrand canonical (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 for a particular state in the SGC ensemble for a \(m\)component system can be written
\[\rho_{\text{SGC}} \propto \exp\Big[  \big( E + \sum_{i>1}^m \Delta\mu_i N_i \big) \big / k_B T \Big]\]with the relative chemical potentials \(\Delta\mu_i = \mu_i  \mu_1\) and species counts \(N_i\). Unlike the canonical ensemble, the number of the respective species (or, equivalently, the concentrations) are allowed to vary in the SGC ensemble. A trial step thus consists of randomly picking an atom and changing its identity with probability
\[P = \min \Big\{ 1, \, \exp \big[  \big( \Delta E + \sum_i \Delta \mu_i \Delta N_i \big) \big / k_B T \big] \Big\},\]where \(\Delta E\) is the change in potential energy caused by the swap.
There exists a simple relation between the differences in chemical potential and the canonical free energy \(F\). In a binary system, this relationship reads
\[\Delta \mu =  \frac{1}{N} \frac{\partial F}{\partial c} ( N, V, T, \langle c \rangle).\]Here \(c\) denotes concentration (\(c=N_i/N\)) and \(\langle c \rangle\) the average concentration observed in the simulation. By recording \(\langle c \rangle\) while gradually changing \(\Delta \mu\), one can thus in principle calculate the difference in canonical free energy between the pure phases (\(c=0\) or \(1\)) and any concentration by integrating \(\Delta \mu\) over that concentration range. In practice this requires that the average recorded concentration \(\langle c \rangle\) varies continuously with \(\Delta \mu\). This is not the case for materials with multiphase regions (such as miscibility gaps), because in such regions \(\Delta \mu\) maps to multiple concentrations. In a Monte Carlo simulation, this is typically manifested by discontinuous jumps in concentration. Such jumps mark the phase boundaries of a multiphase region and can thus be used to construct the phase diagram. To recover the free energy, however, such systems require sampling in other ensembles, such as the varianceconstrained semigrand canonical ensemble.
Parameters:  atoms (
Atoms
) – atomic configuration to be used in the Monte Carlo simulation; also defines the initial occupation vector  calculator (
BaseCalculator
) – calculator to be used for calculating the potential changes that enter the evaluation of the Metropolis criterion  temperature (float) – temperature \(T\) in appropriate units [commonly Kelvin]
 chemical_potentials (Dict[str, float]) – chemical potential for each species \(\mu_i\); the key denotes the species, the value specifies the chemical potential in units that are consistent with the underlying cluster expansion
 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]
 user_tag (str) – humanreadable tag for ensemble [default: None]
 data_container (str) – name of file the data container associated with the ensemble will be written to; if the file exists it will be read, the data container will be appended, and the file will be updated/overwritten
 random_seed (int) – seed for the random number generator used in the Monte Carlo simulation
 ensemble_data_write_interval (int) – interval at which data is written to the data container; this includes for example the current value of the calculator (i.e. usually the energy) as well as ensembles specific fields such as temperature or the number of atoms of different species
 data_container_write_period (float) – period in units of seconds at which the data container is written to file; writing periodically to file provides both a way to examine the progress of the simulation and to back up the data [default: np.inf]
 trajectory_write_interval (int) – interval at which the current occupation vector of the atomic configuration is written to the data container.

acceptance_ratio
¶ acceptance ratio
Return type: float

accepted_trials
¶ number of accepted trial steps
Return type: int

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
 observer (

boltzmann_constant
¶ Boltzmann constant \(k_B\) (see parameters section above)
Return type: float

calculator
¶ calculator attached to the ensemble
Return type: BaseCalculator

chemical_potentials
¶ chemical potentials \(\mu_i\) (see parameters section above)
Return type: Dict
[int
,float
]

data_container
¶ data container associated with ensemble
Return type: DataContainer

data_container_write_period
¶ data container write period
Return type: float

ensemble_parameters
¶ Returns parameters associated with the ensemble.
Return type: dict

get_random_sublattice_index
()¶ Returns a random sublattice index based on the weights of the sublattice.
Todo
 add unit test
Return type: int

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.
 number_of_trial_steps (

sublattices
¶ sublattices for the configuration being sampled
Return type: Sublattices

temperature
¶ temperature \(T\) (see parameters section above)
Return type: float

total_trials
¶ number of Monte Carlo trial steps
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 sites (

user_tag
¶ tag used for labeling the ensemble
Return type: str

write_data_container
(outfile)¶ Updates last state of the Monte Carlo simulation and writes DataContainer to file.
Parameters: outfile ( Union
[str
,Binaryio
,Textio
]) – file to which to write
 atoms (
Varianceconstrained semigrand canonical ensemble¶

class
mchammer.ensembles.
VCSGCEnsemble
(atoms, calculator, temperature, phis, kappa, boltzmann_constant=8.617330337217213e05, user_tag=None, data_container=None, random_seed=None, data_container_write_period=inf, ensemble_data_write_interval=None, trajectory_write_interval=None)[source]¶ Instances of this class allow one to simulate systems in the varianceconstrained semigrand canonical (VCSGC) ensemble (\(N\phi\kappa VT\)), i.e. at constant temperature (\(T\)), total number of sites (\(N=\sum_i N_i\)), and two additional dimensionless parameters \(\phi\) and \(\kappa\), which constrain average and variance of the concentration, respectively. The VCSGC ensemble is currently only implemented for binary systems.
The probability for a particular state in the VCSGC ensemble for a \(2\)component system can be written
\[\rho_{\text{VCSGC}} \propto \exp\Big[  E / k_B T + \kappa N ( c_1 + \phi_1 / 2 )^2 \Big],\]where \(c_1\) represents the concentration of species 1, i.e. \(c_1=N_1/N\). (Please note that the quantities \(\kappa\) and \(\phi\) correspond, respectively, to \(\bar{\kappa}\) and \(\bar{\phi}\) in [SadErh12].) This implementation requires \(\phi\) to be specified for both species. The sum of the specified \(\phi\) values is required to be \(2\), because then the above expression is symmetric with respect to interchange of species 1 and 2, i.e., it does not matter if we use \(\phi_1\) and \(c_1\) or \(\phi_2\) and \(c_2\).
Just like the semigrand canonical ensemble, the VCSGC ensemble allows concentrations to change. A trial step consists of changing the identity of a randomly chosen atom and accepting the change with probability
\[P = \min \{ 1, \, \exp [  \Delta E / k_B T + \kappa N \Delta c_1 (\phi_1 + \Delta c_1 + 2 c_1 ) ] \}.\]Note that for a sufficiently large value of \(\kappa\), say 200, the probability density \(\rho_{\text{VCSGC}}\) is sharply peaked around \(c_1=\phi_1 / 2\). In practice, this means that we can gradually change \(\phi_1\) from (using some margins) \(2.1\) to \(0.1\) and take the system continuously from \(c_1 = 0\) to \(1\). The parameter \(\kappa\) constrains the fluctuations (or the variance) of the concentration at each value of \(\phi_1\), with higher values of \(\kappa\) meaning less fluctuations. Unlike the semigrand canonical ensemble, one value of \(\phi_1\) maps to one and only one concentration also in multiphase regions. Since the derivative of the canonical free energy can be expressed in terms of parameters and observables of the VCSGC ensemble,
\[k_B T \kappa ( \phi_1 + 2 \langle c_1 \rangle ) =  \frac{1}{N} \frac{\partial F}{\partial c_1} (N, V, T, \langle c_1 \rangle ),\]this ensemble allows for thermodynamic integration across multiphase regions. This means that we can construct phase diagrams by directly comparing the free energies of the different phases. This often makes the VCSGC ensemble more convenient than the semigrand canonical ensemble when simulating materials with multiphase regions, such as alloys with miscibility gaps.
When using the VCSGC ensemble, please cite Sadigh, B. and Erhart, P., Phys. Rev. B 86, 134204 (2012) [SadErh12].
Parameters:  atoms (
Atoms
) – atomic configuration to be used in the Monte Carlo simulation; also defines the initial occupation vector  calculator (
BaseCalculator
) – calculator to be used for calculating the potential changes that enter the evaluation of the Metropolis criterion  temperature (float) – temperature \(T\) in appropriate units [commonly Kelvin]
 phis (Dict[str, float]) – average constraint parameters \(\phi_i\); the key denotes the species; there must be one entry for each species but their sum must be \(2.0\) (referred to as \(\bar{\phi}\) in [SadErh12])
 kappa (float) – parameter that constrains the variance of the concentration (referred to as \(\bar{\kappa}\) in [SadErh12])
 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]
 user_tag (str) – humanreadable tag for ensemble [default: None]
 data_container (str) – name of file the data container associated with the ensemble will be written to; if the file exists it will be read, the data container will be appended, and the file will be updated/overwritten
 random_seed (int) – seed for the random number generator used in the Monte Carlo simulation
 ensemble_data_write_interval (int) – interval at which data is written to the data container; this includes for example the current value of the calculator (i.e. usually the energy) as well as ensembles specific fields such as temperature or the number of atoms of different species
 data_container_write_period (float) – period in units of seconds at which the data container is written to file; writing periodically to file provides both a way to examine the progress of the simulation and to back up the data [default: np.inf]
 trajectory_write_interval (int) – interval at which the current occupation vector of the atomic configuration is written to the data container.

acceptance_ratio
¶ acceptance ratio
Return type: float

accepted_trials
¶ number of accepted trial steps
Return type: int

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
 observer (

boltzmann_constant
¶ Boltzmann constant \(k_B\) (see parameters section above)
Return type: float

calculator
¶ calculator attached to the ensemble
Return type: BaseCalculator

data_container
¶ data container associated with ensemble
Return type: DataContainer

data_container_write_period
¶ data container write period
Return type: float

ensemble_parameters
¶ Returns parameters associated with the ensemble.
Return type: dict

get_random_sublattice_index
()¶ Returns a random sublattice index based on the weights of the sublattice.
Todo
 add unit test
Return type: int

kappa
¶ kappa \(\bar{\kappa}\) constrain parameter (see parameters section above)
Return type: float

observer_interval
¶ minimum number of steps to run Monte Carlo simulation without interruption for observation
Return type: int

observers
¶ Return type: Dict
[str
,BaseObserver
]

phis
¶ phis \(\phi_i\), one for each species but their sum must be \(2.0\) (referred to as \(\bar{\phi}\) in [SadErh12])
Return type: Dict
[int
,float
]

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.
 number_of_trial_steps (

sublattices
¶ sublattices for the configuration being sampled
Return type: Sublattices

temperature
¶ temperature \(T\) (see parameters section above)
Return type: float

total_trials
¶ number of Monte Carlo trial steps
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 sites (

user_tag
¶ tag used for labeling the ensemble
Return type: str

write_data_container
(outfile)¶ Updates last state of the Monte Carlo simulation and writes DataContainer to file.
Parameters: outfile ( Union
[str
,Binaryio
,Textio
]) – file to which to write
 atoms (