mpcd.collide

Overview

at
srd

Details

MPCD collision methods

An MPCD collision method is required to update the particle velocities over time. It is meant to be used in conjunction with an integrator and streaming method (see stream). Particles are binned into cells based on their positions, and all particles in a cell undergo a stochastic collision that updates their velocities while conserving linear momentum. Collision rules can optionally be extended to also enforce angular-momentum conservation. The stochastic collision lead to a build up of hydrodynamic interactions, and the choice of collision rule and solvent properties determine the transport coefficients.

class hoomd.mpcd.collide.at(seed, period, kT, group=None)

Andersen thermostat method

Parameters:
  • seed (int) – Seed to the collision method random number generator (must be positive)
  • period (int) – Number of integration steps between collisions
  • kT (hoomd.variant or float) – Temperature set point for the thermostat (in energy units).
  • group (hoomd.group) – Group of particles to embed in collisions

This class implements the Andersen thermostat collision rule for MPCD, as described by Allahyarov and Gompper. Every period steps, the particles are binned into cells. The size of the cell can be selected as a property of the MPCD system (see data.system.set_params()). New particle velocities are then randomly drawn from a Gaussian distribution (using seed) relative to the center-of-mass velocity for the cell. The random velocities are given zero-mean so that the cell momentum is conserved. This collision rule naturally imparts the canonical (NVT) ensemble consistent with kT. The properties of the AT fluid are tuned using period, kT, the underlying size of the MPCD cell list, and the particle density.

Note

The period must be chosen as a multiple of the MPCD stream period. Other values will result in an error when hoomd.run() is called.

When the total mean-free path of the MPCD particles is small, the underlying MPCD cell list must be randomly shifted in order to ensure Galilean invariance. Because the performance penalty from grid shifting is small, shifting is enabled by default in all simulations. Disable it using set_params() if you are sure that you do not want to use it.

HOOMD particles in group can be embedded into the collision step (see embed()). A separate integration method (integrate) must be specified in order to integrate the positions of particles in group. The recommended integrator is nve.

Examples:

collide.at(seed=42, period=1, kT=1.0)
collide.at(seed=77, period=50, kT=1.5, group=hoomd.group.all())
disable()

Disable the collision method

Examples:

method.disable()

Disabling the collision method removes it from the current MPCD system definition. Only one collision method can be attached to the system at any time, so use this method to remove the current collision method before adding another.

embed(group)

Embed a particle group into the MPCD collision

Parameters:group (hoomd.group) – Group of particles to embed

The group is embedded into the MPCD collision step and cell properties. During collisions, the embedded particles are included in determining per-cell quantities, and the collisions are applied to the embedded particles.

No integrator is generated for group. Usually, you will need to create a separate method to integrate the embedded particles. The recommended (and most common) integrator to use is nve. It is generally not a good idea to use a thermostatting integrator for the embedded particles, since the MPCD particles themselves already act as a heat bath that will thermalize the embedded particles.

Examples:

polymer = hoomd.group.type('P')
md.integrate.nve(group=polymer)
method.embed(polymer)
enable()

Enable the collision method

Examples:

method.enable()

Enabling the collision method adds it to the current MPCD system definition. Only one collision method can be attached to the system at any time. If another method is already set, disable() must be called first before switching.

set_params(shift=None, kT=None)

Set parameters for the SRD collision method

Parameters:
  • shift (bool) – If True, perform a random shift of the underlying cell list.
  • kT (hoomd.variant or float) – Temperature set point for the thermostat (in energy units).

Examples:

srd.set_params(shift=False)
srd.set_params(shift=True, kT=1.0)
srd.set_params(kT=hoomd.data.variant.linear_interp([[0,1.0],[100,5.0]]))
set_period(period)

Set the collision period.

Parameters:period (int) – New collision period.

The MPCD collision period can only be changed to a new value on a simulation timestep that is a multiple of both the previous period and the new period. An error will be raised if it is not.

Examples:

# The initial period is 5.
# The period can be updated to 2 on step 10.
hoomd.run_upto(10)
method.set_period(period=2)

# The period can be updated to 4 on step 12.
hoomd.run_upto(12)
hoomd.set_period(period=4)
class hoomd.mpcd.collide.srd(seed, period, angle, kT=False, group=None)

Stochastic rotation dynamics method

Parameters:
  • seed (int) – Seed to the collision method random number generator (must be positive)
  • period (int) – Number of integration steps between collisions
  • angle (float) – SRD rotation angle (degrees)
  • kT (hoomd.variant or float or bool) – Temperature set point for the thermostat (in energy units). If False (default), no thermostat is applied and an NVE simulation is run.
  • group (hoomd.group) – Group of particles to embed in collisions

This class implements the classic stochastic rotation dynamics collision rule for MPCD as first proposed by Malevanets and Kapral. Every period steps, the particles are binned into cells. The size of the cell can be selected as a property of the MPCD system (see data.system.set_params()). The particle velocities are then rotated by angle around an axis randomly drawn from the unit sphere. The rotation is done relative to the average velocity, so this rotation rule conserves momentum and energy within each cell, and so also globally. The properties of the SRD fluid are tuned using period, angle, kT, the underlying size of the MPCD cell list, and the particle density.

Note

The period must be chosen as a multiple of the MPCD stream period. Other values will result in an error when hoomd.run() is called.

When the total mean-free path of the MPCD particles is small, the underlying MPCD cell list must be randomly shifted in order to ensure Galilean invariance. Because the performance penalty from grid shifting is small, shifting is enabled by default in all simulations. Disable it using set_params() if you are sure that you do not want to use it.

HOOMD particles in group can be embedded into the collision step (see embed()). A separate integration method (integrate) must be specified in order to integrate the positions of particles in group. The recommended integrator is nve.

The SRD method naturally imparts the NVE ensemble to the system comprising the MPCD particles and group. Accordingly, the system must be properly initialized to the correct temperature. (SRD has an H theorem, and so particles exchange momentum to reach an equilibrium temperature.) A thermostat can be applied in conjunction with the SRD method through the kT parameter. SRD employs a Maxwell-Boltzmann thermostat on the cell level, which generates the (correct) isothermal ensemble. The temperature is defined relative to the cell-average velocity, and so can be used to dissipate heat in nonequilibrium simulations. Under this thermostat, the SRD algorithm still conserves momentum, but energy is of course no longer conserved.

Examples:

collide.srd(seed=42, period=1, angle=130.)
collide.srd(seed=77, period=50, angle=130., group=hoomd.group.all())
collide.srd(seed=1991, period=10, angle=90., kT=1.5)
disable()

Disable the collision method

Examples:

method.disable()

Disabling the collision method removes it from the current MPCD system definition. Only one collision method can be attached to the system at any time, so use this method to remove the current collision method before adding another.

embed(group)

Embed a particle group into the MPCD collision

Parameters:group (hoomd.group) – Group of particles to embed

The group is embedded into the MPCD collision step and cell properties. During collisions, the embedded particles are included in determining per-cell quantities, and the collisions are applied to the embedded particles.

No integrator is generated for group. Usually, you will need to create a separate method to integrate the embedded particles. The recommended (and most common) integrator to use is nve. It is generally not a good idea to use a thermostatting integrator for the embedded particles, since the MPCD particles themselves already act as a heat bath that will thermalize the embedded particles.

Examples:

polymer = hoomd.group.type('P')
md.integrate.nve(group=polymer)
method.embed(polymer)
enable()

Enable the collision method

Examples:

method.enable()

Enabling the collision method adds it to the current MPCD system definition. Only one collision method can be attached to the system at any time. If another method is already set, disable() must be called first before switching.

set_params(angle=None, shift=None, kT=None)

Set parameters for the SRD collision method

Parameters:
  • angle (float) – SRD rotation angle (degrees)
  • shift (bool) – If True, perform a random shift of the underlying cell list
  • kT (hoomd.variant or float or bool) – Temperature set point for the thermostat (in energy units). If False, any set thermostat is removed and an NVE simulation is run.

Examples:

srd.set_params(angle=90.)
srd.set_params(shift=False)
srd.set_params(angle=130., shift=True, kT=1.0)
srd.set_params(kT=hoomd.data.variant.linear_interp([[0,1.0],[100,5.0]]))
srd.set_params(kT=False)
set_period(period)

Set the collision period.

Parameters:period (int) – New collision period.

The MPCD collision period can only be changed to a new value on a simulation timestep that is a multiple of both the previous period and the new period. An error will be raised if it is not.

Examples:

# The initial period is 5.
# The period can be updated to 2 on step 10.
hoomd.run_upto(10)
method.set_period(period=2)

# The period can be updated to 4 on step 12.
hoomd.run_upto(12)
hoomd.set_period(period=4)