The WangLandau class¶
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.
Initialization and methods¶
- class clusterx.thermodynamics.wang_landau.WangLandau(energy_model: Model, scell: SuperCell, nsubs=None, ensemble='canonical', sublattice_indices=[], energy_factor=1.0, chemical_potentials=None, predict_swap=False, reduce_structure: bool = False, error_reset=None)¶
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
Modelobject Linear CE model for predicting the internal energy of the supercell (see
scellbelow) in [eV]. If other units are employed, see parameterenergy_factorbelow.- scellSuperCell
Simulation cell in which the sampling is performed.
- ensemblestr, default canonical
canonicalallows for swaps of atoms that conserve the concentration defined withnsubs.grandcanonicalallows for replacing atoms in the sub-lattices defined withsublattice_indices. (So far,grandcanonicalis not yet implemented.)- nsubsdict, 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_indiceslist of int, 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].- energy_factorfloat, 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 (scellbelow). For instance, if the CE model predicts the energy in meV/atom, set this parameter to Nsc/1000, where Nsc is the total number of atoms of the supercell (len(scell)). If CE predicts the energy in Hartree per parent lattice, setenergy_factorto 27.2114*Npl, where Npl is the number of parent lattices contained in the supercell (this can be obtained withscell.get_index()).- chemical_potentialsdict, default None
Define the chemical potentials used for samplings in the grand canonical ensemble.
- fileprefixstr, default ‘cdos’
Prefix for files in which the configurational density of states is saved.
- predict_swapbool, 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.
- reduce_structurebool, default False
If true, cluster orbits/correlations are computed and evaluated on subset of sigmas, in a box around central site in the structure. Incompatible with non-diagonal supercell shapes.
- error_resetint, default None
If not None and
predict_swapequal to True, the correlations are calculated as usual (no differences) every n-th step.
- energy_model
Notes
- wang_landau_sampling(energy_range: [<class 'float'>, <class 'float'>] = [-2.0, 2.0], energy_bin_width: float = 0.2, f_range: [<class 'float'>, <class 'float'>] = [2.718281828459045, 1.0001000050001667], update_method: str = 'square_root', flatness_conditions: list[[<class 'float'>, <class 'float'>]] = [[0.5, 1.1051709180756477], [0.8, 1.0010005001667084], [0.9, 1.00001000005], [0.95, 1.000000100000005], [0.98, 1.00000001]], initial_decoration: list[int] = None, serialize: bool = False, filename: str = 'cdos.json', serialize_during_sampling: bool = False, restart_from_file: bool = False, plot_hist_real_time: bool = False, acc_prob_init_structure: float = 0.001, acc_prob_dist_init_structure: str = 'gaussian', itmax_init_structure: int = 100000000, niter_per_sweep: int = 100000, nproc: int = 0, seed: int = None, **kwargs)¶
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_rangelist 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_widthfloat, 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_rangelist 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_methodstr, default ‘square_root’
Defines the method of how the modification factor is reduced. (for now: only square_root implemented)
- flatness_conditionslist
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_decorationlist of int
Atomic numbers of the initial structure, from which the sampling starts. If None, sampling starts with a structure randomly generated.
- serializebool, default False
If True, the ConfigurationalDensityOfStates object is serialized into a JSON file after the sampling.
- filenamestr, default cdos.json
Name of a Json file in which the ConfigurationalDensityOfStates is serialized after the sampling if
serializeis True.- serialize_during_samplingbool, 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_structurefloat, 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_structureint
Maximum number of trials to search for initial structure inside given energy window.
- nprocint, default 0
Number of processes to use for the initial structure search.
- seedint, default None
Seed for the random.Random and numpy random number generator. If None, sequences are non-deterministic, if set with integer, sequences are deterministic, i.e. pseudo-random.
- **kwargskeyworded argument list, arbitrary length
These arguments are added to the ConfigurationalDensityOfStates object that is initialized in this method.
- Returns:
- ConfigurationalDensityOfStates object
Object contains the configurational density of states (CDOS) obtained from the last outer loop plus the CDOSs obtained from the previous outer loops.