The MonteCarlo class¶

Initialization and methods¶

class clusterx.thermodynamics.monte_carlo.MonteCarlo(energy_model, scell, nsubs=None, ensemble='canonical', sublattice_indices=None, chemical_potentials=None, models=[], no_of_swaps=1, predict_swap=False, error_reset=None, filename='trajectory.json')¶

Monte Carlo class

Description:

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 with nsubs. In case of multilattices, the sublattice for the sampling can be refined with sublattice_indices.

  If ensemble is ‘gandcanonical’, the sublattice is defined with sublattices_indices.

Parameters:

energy_model: Model object

Model used for acceptance and rejection. Usually, the Model enables to calculate the total energy of a structure.

scell: SuperCell object

Simulation 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 objects

The 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.

metropolis(no_of_sampling_steps=100, scale_factor=[1.0], temperature=1.0, boltzmann_constant=1.0, initial_decoration=None, acceptance_ratio=None, serialize=False, filename=None, **kwargs)¶

Perform Monte-Carlo Metropolis simulation

Description:

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: integer

Number of sampling steps

temperature: float

Temperature at which the sampling is performed.

boltzmann_constant: float

Boltzmann constant

scale_factor: list of floats

List 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 integers

Atomic 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 length

These arguments are added to the MonteCarloTrajectory object that is initialized in this method.

Returns: MonteCarloTrajectory object

Trajectory containing the complete information of the sampling trajectory.