ForceBiasMonteCarloNPTBerendsen

class ForceBiasMonteCarloNPTBerendsen(temperature=None, pressure=None, barostat_factor=None, compressibility=None, coupling_mask=None, max_atom_displacement=None, heating_rate=None, compression_rate=None, random_seed=None, max_random_attempts=None)

Set up the ForceBiasMonteCarlo object with NPT Berendsen pressure control.

Parameters:
  • temperature (PhysicalQuantity of type temperature | None) – The temperature at which the Monte Carlo simulation should be run.
    Default: 300*Kelvin

  • pressure (PhysicalQuantity of type pressure) – The reservoir pressure in the simulation. The pressure can be given either as a scalar value, as a vector of length 3 denoting the hydrostatic components, as a vector of length 6 in Voigt notation, or as a 3x3 tensor. A scalar value will result in isotropic pressure coupling, whereas for all other representations, each pressure component will be coupled to the barostat independently.
    Default: 1.0*bar

  • barostat_factor (float) – Defines the barostat timescale by taking the product of this factor and the time step.
    Default: 500

  • compressibility (PhysicalQuantity of type pressure**-1) – The estimated compressibility of the system relating volume changes to pressures changes.
    Default: 1.0e-4*bar**-1

  • coupling_mask (array of bools) – The mask determining which elements of the stress tensor the barostat should couple to. Can be given as a vector of length 3, denoting the hydrostatic components, as a vector of length 6 in Voigt notation, or as a 3x3 tensor. By default the barostat couples only to the diagonal elements.
    Default: True for diagonal elements, False for shear components.

  • heating_rate (PhysicalQuantity of type temperature/time | None) – The heating rate of the target temperature. A value of None disables the heating of the system.
    Default: None

  • max_atom_displacement (PhysicalQuantity of type length | None) – The maximum distance an atom can move in each Cartesian direction during a single step.
    Default: 0.1*Angstrom

  • compression_rate (PhysicalQuantity of type pressure | None) – The change in the pressure per step. A value of None disables the compression of the system.
    Default: None

  • random_seed (int | None) – The seed for the random generator. Must be between 0 and 2**32.
    Default: The default random seed

  • max_random_attempts (int) – The maximum attempts used in the rejection sampling of the probability distribution.
    Default: 500

monteCarloStep(configuration, forces, stress, constraints=None)

Perform a Monte Carlo step, applying new positions to the configuration and scaling the unit cell.

Parameters:
monteCarloTimeStep()
Returns:

The average time that elapses between each step according to the time-stamped force bias MC (tfMC) formalism or None if not initialized.

Return type:

PhysicalQuantity of type time | None

reservoirTemperature()
Returns:

The current reservoir temperature.

Return type:

PhysicalQuantity of type temperature

Usage Example

Use the ForceBiasMonteCarloNPTBerendsen object to run a TimeStampedForceBiasMonteCarlo simulation:

# -------------------------------------------------------------
# Time-Stamped Force-Bias Monte Carlo
# -------------------------------------------------------------

method = ForceBiasMonteCarloNPTBerendsen(
    temperature=500*Kelvin,
    max_atom_displacement=0.1*Angstrom,
    pressure=1*bar,
    barostat_factor=500,
    compressibility=0.0001*bar**-1,
)

mc_trajectory = TimeStampedForceBiasMonteCarlo(
    bulk_configuration,
    constraints=[],
    trajectory_filename='tfmc_trajectory.hdf5',
    steps=500,
    log_interval=50,
    method=method
)

bulk_configuration = mc_trajectory.lastImage()

tfmc_example.py

Notes

The ForceBiasMonteCarloNPTBerendsen class is used in the TimeStampedForceBiasMonteCarlo function to run a time-stamped force-bias Monte Carlo (TFMC) simulation [1]. This class builds upon the method defined in the ForceBiasMonteCarlo to add pressure control via a Benendsen barostat. This allows the unit cell of the material to change during the simulation in response to an external pressure.

A Monte Carlo step is taken by displacing each Cartesian component, using the same algorithm as in the ForceBiasMonteCarlo class. In addition to the atomic displacements, the unit cell is also scaled at each step according to the Berendsen barostat, as described in Ref. [2]. The target pressure in the simulation is specified with the argument pressure. If a single scalar pressure value is given, isotropic pressure coupling is applied, scaling all cell vectors by the same factor. If a pressure vector (of length 3 or 6, in Voigt notation), or a 3x3-tensor is given, anisotropic pressure coupling is applied, allowing each unit cell vector to be scaled independently.

By adjusting the max_atom_displacement parameter one can tune accuracy vs. efficiency of the simulation. A small value results in a more accurate sampling of the canonical ensemble, whereas a large value increases the efficiency at which the phase space is sampled. Typically, values in the range \(0.1 R_{eq} \, - \, 0.3 R_{eq}\) are a reasonable choice, where \(R_{eq}\) represents an equilibrium bond length in the system.

The response rate of the unit cell to the Berendsen barostat is controlled by two factors. The first of these is the barostat scaling factor, specified with barostat_factor. This factor, given as a dimensionless scalar, is combined with the Monte Carlo time step to give a time scale of how rapidly the unit cell adjusts to changes in pressure. The second variable is the compressibility of the material, which is specified with the argument compressibility. This gives a measure of the pressure required to create a change in volume. The default value of this parameter is the compressibility of water, which is usually sufficient in most simulations, as reasonable changes in the compressibility do not significantly alter the simulation.

In cases where anisotropic pressure is specified, different cell dimensions can be coupled or uncoupled with the barostat by using the argument coupling_mask. This takes a 3x3 matrix of boolean values specifying whether or not the cell dimension is coupled to the barostat.

The target temperature and pressure during the simulation can also be scaled. If a non-zero heating_rate is specified, the reservoir temperature will be changed by the given value after each Monte Carlo step, resulting in an increase or decrease of the temperature during sampling. As with the temperature, the target pressure can also be scaled using the argument compression_rate. Note that due to technical reasons, the MC time step will be kept constant during the simulation, also when using a finite heating rate, although strictly speaking the time scale depends on the temperature. This means that time-dependent quantities calculated from heating or cooling simulations should be considered only an approximation.