md.methods.thermostats#

Overview

`Berendsen`	The Berendsen thermostat.
`Bussi`	The Bussi-Donadio-Parrinello thermostat.
`MTTK`	The Nosé-Hoover thermostat.
`Thermostat`	Base thermostat object class.

Details

Provide classes for thermostatting simulations.

The thermostat classes are for use with hoomd.md.methods.ConstantVolume and hoomd.md.methods.ConstantPressure.

Important

Ensure that your initial condition includes non-zero particle velocities and angular momenta (when appropriate). The coupling between the thermostat and the velocities / angular momenta occurs via multiplication, so the thermostat cannot convert a zero velocity into a non-zero one except through particle collisions.

Example

simulation.state.thermalize_particle_momenta(
    filter=hoomd.filter.All(),
    kT=1.5)

class hoomd.md.methods.thermostats.Berendsen(kT, tau)#

The Berendsen thermostat.

Parameters:

kT (hoomd.variant.variant_like) – Temperature of the simulation. \([\mathrm{energy}]\)
tau (float) – Thermostat time constant. \([\mathrm{time}]\)

Berendsen rescales the velocities of all particles on each time step. The rescaling is performed so that the difference in the current temperature from the set point decays exponentially:

\[\frac{dT_\mathrm{cur}}{dt} = \frac{T - T_\mathrm{cur}}{\tau}\]

Attention

Berendsen does NOT sample the correct distribution of kinetic energies.

See also

Berendsen et. al. 1984.

Example:

berendsen = hoomd.md.methods.thermostats.Berendsen(kT=1.5,
    tau=simulation.operations.integrator.dt * 10_000)
simulation.operations.integrator.methods[0].thermostat = berendsen

kT#

Temperature of the simulation. \([energy]\)

Examples:

berendsen.kT = 1.0

berendsen.kT = hoomd.variant.Ramp(A=1.0,
                                  B=2.0,
                                  t_start=0,
                                  t_ramp=1_000_000)

Type:: hoomd.variant.variant_like

tau#

Time constant of thermostat. \([time]\)

Type:: float

class hoomd.md.methods.thermostats.Bussi(kT, tau=0.0)#

The Bussi-Donadio-Parrinello thermostat.

Parameters:

kT (hoomd.variant.variant_like) – Temperature set point for the thermostat \([\mathrm{energy}]\).
tau (float) – Thermostat time constant \([\mathrm{time}]\). Defaults to 0.

Bussi controls the system temperature by separately rescaling the velocity and angular momenta by the factor \(\alpha\) sampled from the canonical distribution.

When tau is 0, the stochastic evolution of system is instantly thermalized and \(\alpha\) is given by:

\[\alpha = \sqrt{\frac{g_N kT}{K}}\]

where \(K\) is the instantaneous kinetic energy of the corresponding translational or rotational degrees of freedom, \(N\) is the number of degrees of freedom, and \(g_N\) is a random value sampled from the distribution \(\mathrm{Gamma}(N, 1)\):

\[f_N(g) = \frac{1}{\Gamma(N)} g^{N-1} e^{-g}.\]

When tau is non-zero, the kinetic energies decay to equilibrium with the given characteristic time constant and \(\alpha\) is given by:

\[\alpha = \sqrt{e^{\delta t / \tau} + (1 - e^{\delta t / \tau}) \frac{(2 g_{N-1} + n^2) kT}{2 K} + 2 n \sqrt{e^{\delta t / \tau} (1-e^{\delta t / \tau}) \frac{kT}{2 K}}}\]

where \(\delta t\) is the step size and \(n\) is a random value sampled from the normal distribution \(\mathcal{N}(0, 1)\).

See also

Bussi et. al. 2007.

Example:

bussi = hoomd.md.methods.thermostats.Bussi(kT=1.5,
    tau=simulation.operations.integrator.dt*20)
simulation.operations.integrator.methods[0].thermostat = bussi

kT#

Temperature set point for the thermostat \([\mathrm{energy}]\).

Examples:

bussi.kT = 1.0

bussi.kT = hoomd.variant.Ramp(A=1.0,
                              B=2.0,
                              t_start=0,
                              t_ramp=1_000_000)

Type:: hoomd.variant.variant_like

tau#

Thermostat time constant \([\mathrm{time}].\)

Example:

bussi.tau = 0.0

Type:: float

class hoomd.md.methods.thermostats.MTTK(kT, tau)#

The Nosé-Hoover thermostat.

Controls the system temperature using velocity rescaling with the Nosé-Hoover thermostat.

Parameters:

kT (hoomd.variant.variant_like) – Temperature set point for the thermostat \([\mathrm{energy}]\).
tau (float) – Coupling constant for the thermostat \([\mathrm{time}]\)

The translational thermostat has a momentum \(\xi\) and position \(\eta\). The rotational thermostat has momentum \(\xi_{\mathrm{rot}}\) and position \(\eta_\mathrm{rot}\). Access these quantities using translational_dof and rotational_dof.

Note

The coupling constant tau should be set within a reasonable range to avoid abrupt fluctuations in the kinetic temperature and to avoid long time to equilibration. The recommended value for most systems is \(\tau = 100 \delta t\).

Examples:

mttk = hoomd.md.methods.thermostats.MTTK(kT=1.5,
    tau=simulation.operations.integrator.dt*100)
simulation.operations.integrator.methods[0].thermostat = mttk

kT#

Temperature set point for the thermostat \([\mathrm{energy}]\).

Examples:

mttk.kT = 1.0

mttk.kT = hoomd.variant.Ramp(A=1.0,
                             B=2.0,
                             t_start=0,
                             t_ramp=1_000_000)

Type:: hoomd.variant.variant_like

tau#

Coupling constant for the thermostat \([\mathrm{time}]\)

Example:

mttk.tau = 0.2

Type:: float

translational_dof#

Additional degrees of freedom for the translational thermostat (\(\xi\), \(\eta\))

Save and restore the thermostat degrees of freedom when continuing simulations:

Examples:

Save before exiting:

numpy.save(file=path / 'translational_dof.npy',
           arr=mttk.translational_dof)

Load when continuing:

mttk = hoomd.md.methods.thermostats.MTTK(kT=1.5,
    tau=simulation.operations.integrator.dt*100)
simulation.operations.integrator.methods[0].thermostat = mttk

mttk.translational_dof = numpy.load(
    file=path / 'translational_dof.npy')

Type:: tuple[float, float]

rotational_dof#

Additional degrees of freedom for the rotational thermostat (\(\xi_\mathrm{rot}\), \(\eta_\mathrm{rot}\))

Save and restore the thermostat degrees of freedom when continuing simulations:

Examples:

Save before exiting:

numpy.save(file=path / 'rotational_dof.npy',
           arr=mttk.rotational_dof)

Load when continuing:

mttk = hoomd.md.methods.thermostats.MTTK(kT=1.5,
    tau=simulation.operations.integrator.dt*100)
simulation.operations.integrator.methods[0].thermostat = mttk

mttk.rotational_dof = numpy.load(
    file=path / 'rotational_dof.npy')

Type:: tuple[float, float]

property energy#

Energy the thermostat contributes to the Hamiltonian \([\mathrm{energy}]\).

Example:

logger.add(obj=mttk, quantities=['energy'])

(Loggable: category=”scalar”)

thermalize_dof()#

Set the thermostat momenta to random values.

thermalize_dof sets a random value for the momentum \(\xi\). When Integrator.integrate_rotational_dof is True, it also sets a random value for the rotational thermostat momentum \(\xi_{\mathrm{rot}}\). Call thermalize_dof to set a new random state for the thermostat.

Example

mttk.thermalize_dof()

Important

You must call Simulation.run before thermalize_dof.

See also

State.thermalize_particle_momenta

class hoomd.md.methods.thermostats.Thermostat(kT)#: Base thermostat object class.

Note

Users should use the subclasses and not instantiate Thermostat directly.