The thermodynamic properties of substitutional systems can be computed by means of Monte Carlo simulations.
This module allows the realization of Monte Carlo simulations in various ensembles.
Monte Carlo class
Objects of this class are used to perform Monte Carlo samplings.
It is initialized with:
a Model object, that enables to calculate the energy of a structure,
a SuperCell object, in which the sampling is performed,
specification of the thermodynamic ensemble:
If
ensemble
is ‘canonical’, the composition for the sampling is defined withnsubs
. In case of multilattices, the sublattice for the sampling can be refined withsublattice_indices
.If
ensemble
is ‘gandcanonical’, the sublattice is defined withsublattices_indices
.
Parameters:
energy_model
: Model objectModel used for acceptance and rejection. Usually, the Model enables to calculate the total energy of a structure.
scell
: SuperCell objectSimulation cell in which the sampling is performed.
ensemble
: string (default: canonical
) canonical
allows for swaps of atoms that conserve the concentration defined with nsubs
.
grandcanonical
allows for replacing atoms in the sub-lattices defined with sublattice_indices
.
(So far, grandcanonical
is not yet implemented.)
nsubs
: dictionary (default = None)Defines the number of substituted atoms in each sub-lattice of the Supercell in which the sampling is performed.
The format of the dictionary is as follows:
{site_type1:[n11,n12,...], site_type2:[n21,n22,...], ...}
It indicates how many substitutional atoms of every kind (n#1, n#2, …) may replace the pristine species for sites of site_type# (see related documentation in SuperCell object).
sublattice_indices
: list of integers (default = None)Defines the sublattices for the grand canonical sampling.
Furthermore, it can be used to limit the canonical sampling
to a reduced number of sublattices. E.g. in the case of nsubs = {0:[4,6], 1:[4]}. Here, sublattices 0 and 1
contain substitutional sites, but only a sampling in sublattice 0 is wanted. Then, put sublattice_indices
= [0].
chemical_potentials
: dictionary (default: None)Define the chemical potentials used for samplings in the grand canonical ensemble.
The format of the dictionary is as follows
{site_type1:[\(\Delta \mu_{11}\), \(\Delta \mu_{12}\),…], site_type2:[\(\Delta \mu_{21}\), \(\Delta \mu_{22}\),…],…}
Here, \(\Delta \mu_{\#i}\) is the chemical potential difference of substitutional species i relative to the pristine species in sub-lattice with site_type#.
models
: List of Model objectsThe properties returned from these Model objects are additionally
calculated during the sampling and stored with their corresponding prop_name
to the dictionary key_value_pairs
for each visited structure during the sampling.
Properties from Model obejects can also be calculated after the sampling by using the MonteCarloTrajectory class.
no_of_swaps
: integer (default: 1)Number of atom swaps/replacements per sampling step.
predict_swap
: boolean (default: False)If set to True, this parameter makes the sampling faster by calculating the correlation difference of the proposed structure with respect to the previous structure.
error_reset
: integer (default: None)If not None* and ``predict_swap`` equal to **True, the correlations are calculated as usual (no differences) every n-th step.
Perform Monte-Carlo Metropolis simulation
Perfom Monte-Carlo Metropolis sampling for nmc sampling steps.
During the sampling, a new structure at step i is accepted with the probability given by \(\min( 1, \exp( - (E_i - E_{i-1})/(k_B T)) )\)
The energy \(E_i\) of visited structure at step i is calculated from the Model
energy_model
. The factor \(k_B T\) is the product of the temperature \(T\)
and the Boltzmann constant \(k_B\) (also know as the thermal energy).
Note: The units of the energy
\(E\) and the factor \(k_B T\) must be the same.
With scale_factor
, \(k_B T\) can be adjusted to the correct units (see below).
Parameters:
no_of_sampling_steps
: integerNumber of sampling steps
temperature
: floatTemperature at which the sampling is performed.
boltzmann_constant
: floatBoltzmann constant
scale_factor
: list of floatsList is used to adjust the factor \(k_B T\) to the same units as the energy from energy_model
.
All floats in list are multiply to the factor \(k_B T\). If list is empty, the factor \(k_B T\) remains changed.
initial_decoration
: list of integersAtomic numbers of the initial structure, from which the sampling starts.
If None
, sampling starts with a structure randomly generated.
acceptance_ratio
: float (default: None)Real number between 0 and 100. Represents the percentage of accepted moves.
If not None
, the initial temperature will be adjusted to match the given
acceptance ratio. The acceptance ratio during the simulation is computed using
the last 100 moves.
serialize
: boolean (default: False)Serialize the MonteCarloTrajectory object into a Json file after the sampling.
filename
: string (default: trajectory.json
)Name of a Json file in which the trajectory is serialized after the sampling if serialize
is True.
**kwargs
: keyworded argument list, arbitrary lengthThese arguments are added to the MonteCarloTrajectory object that is initialized in this method.
Trajectory containing the complete information of the sampling trajectory.