Objects of this class are used to sample the configuration space using the Wang-Landau method. The sampling yields the configurational density of states. With it, various thermodynamical properties can be readily computed, including the free energy, and the configurational entropy.
Wang Landau class
Objects of this class are used to obtain the configurational density of states by performing samplings using the Wang Landau method. For details about the method, see F. Wang and D.P. Landau, PRL 86, 2050 (2001).
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
ensembleis ‘canonical’, the composition for the sampling is defined withnsubs. In case of multilattices, the sublattice for the sampling can be defined withsublattice_indices.If
ensembleis ‘gandcanonical’, the sublattice is defined withsublattices_indices.
Parameters:
energy_model: Model objectCE model for predicting the internal energy of the supercell (see scell below)
in [eV]. If other units are employed, see parameter energy_factor below.
energy_factor: float (default: 1.0)Multiplicator factor (\(s\)) applied to the predictions of energy_model
(\(E_{CE}\)). Set this factor such that \(s * E_{CE}\) gives
the total energy, in [eV], of the supercell (scell below).
For instance, if the CE model predicts the energy in meV/atom, set this parameter
to 1000*Nsc, where Nsc is the total number of atoms of the supercel (len(scell)).
If CE predicts the energy in Hartree
per parent lattice, set energy_factor to 27.2114*Npl, where Npl is
the number of parent lattices contained in the supercell (this can be obtained
with scell.get_index()).
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.
fileprefix: string (default: ‘cdos’)Prefix for files in which the configurational density of states is saved.
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 Wang Landau simulation
The Wang-Landau algorithm uses the fact that a Markov chain with transition probability \(P_{1 -> 2} = \min[ 1, g(E_1)/g(E_2) ]\), with \(g(E)\) being the configurational density of states, yields a flat histogram in energy [see F. Wang and D.P. Landau, PRL 86, 2050 (2001)]. This fact is employed to iteratively modify \(g(E)\), which is unknown and initially set to 1, in order to achieve a flat histogram of the visited energies. The accuracy of the found \(g(E)\) will depend on how flat is the histogram at the end of the run and other parameters, as explained below.
The energy of a visited structure is calcualted with the CE model energy_model.
During the sampling, a new structure at step i is accepted with the probability given by \(\min[ 1, g(E_{i-1})/g(E_i) ]\)
If a step is accepted, \(g(E_i)\) of energy bin \(E_i\) is updated with a modification factor \(f\). If a step is rejected, \(g(E_{i-1})\) of the previous energy bin \(E_{i-1}\) with a modification factor \(f\).
The sampling procedure is a nested loop:
Inner loop: Generation of a flat histogram in energy for a fixed \(f\).
Outer loop: Gradual reduction of \(f\) to increase the accuracy of \(g(E)\).
The initial modification factor is usually \(f=\exp(1)\). Since it is large, it ensures to reach all energy levels quickly. In the standard procedure, the modification factor is reduced from \(f\) to \(\sqrt{f} ` for the next inner loop. :math:`f\) is a measure of the accuracy for \(g(E)\): The lower the value of \(f\), the higher the accuracy. The sampling stops, if the next \(f\) is below the threshold \(f_{final}\).
A histogram is considered as flat, if the lowest number of counts of all energy bins is above a given percentage of the mean value. The percentage can be set for each \(f\). Usually, the lower \(f\), the larger the percentage can be set.
Parameters:
energy_range: list of two floats [E_min, E_max] (default: [-2,2])Defines the energy range, in [eV], starting from energy E_min (center of first energy bin) until energy E_max.
energy_bin_width: float (default: 0.2)Bin width w of each energy bin, in [eV].
I.e., energy bins [E_min, E_min+w, E_min+2*w, …, E_min+n*w ], if E_min+(n+1)*w would be larger than E_max.
f_range: list of two floats (default: [2.71828182, 1.00010000])List defines the initial modification factor \(f_1\) and the threshold for the last modification factor \(f_{final}\). I.e. [\(f_1\), \(f_{ final}\)]
update_method: string (default: ‘square_root’)Defines the method of how the modification factor is reduced. (for now: only square_root implemented)
flatness_conditions: list Defines the flatness condition via the percentage \(p\) for each modification factor. I.e.
[[\(p_1\), \(f_1\)], [\(p_2\), \(f_2\)], [\(p_3\), \(f_3\)], … , [\(p_{final}\), \(f_{final}\)]]
That means, the percentage is \(p_1\) for all f > \(f_1\). If \(f_1 \geq f > f_2\), the flatness condition is defined via \(p_2\), etc.
The default usually produces reasonable results and is defined as: Default: [[0.5, 1.1], [0.8, 1.001], [0.9, 1.00001],[0.95, 1.0000001], [0.98, 1.00000001]]
initial_decoration: list of integersAtomic numbers of the initial structure, from which the sampling starts. If None, sampling starts with a structure randomly generated.
serialize: boolean (default: False)If True, the ConfigurationalDensityOfStates object is serialized into a JSON file after the sampling.
filename: string (default: cdos.json)Name of a Json file in which the ConfigurationalDensityOfStates is serialized
after the sampling if serialize is True.
serialize_during_sampling: boolean (default: False)If True, the ConfigurationalDensityOfStates object is serialized every time after a flat histogramm is reached (i.e. the inner loop is completed). This allows for studying the CDOS while the final \(f\) is not yet reached.
acc_prob_init_structure: float (default: 1e-3)When searching for an initial structure inside a given energy window, this is the acceptance probability for moves which whose energy difference with the upper window bound increases or for moves whose energy difference with the lower window bound decreases.
itmax_init_structure: integerMaximum number of trials to search for initial structure inside given energy window.
**kwargs: keyworded argument list, arbitrary lengthThese arguments are added to the ConfigurationalDensityOfStates object that is initialized in this method.
Object contains the configurational density of states (CDOS) obtained from the last outer loop plus the CDOSs obtained from the previous outer loops.