hoomd.mpcd¶

Details

Multiparticle collision dynamics.

Simulating complex fluids and soft matter using conventional molecular dynamics methods (hoomd.md) can be computationally demanding due to large disparities in the relevant length and time scales between molecular-scale solvents and mesoscale solutes such as polymers, colloids, or cells. One way to overcome this challenge is to simplify the model for the solvent while retaining its most important interactions with the solute. MPCD is a particle-based simulation method for resolving solvent-mediated fluctuating hydrodynamic interactions with a microscopically detailed solute model.

Algorithm

In MPCD, a fluid is represented by point particles having continuous positions and velocities. The MPCD particles propagate in alternating streaming and collision steps. During the streaming step, particles evolve according to Newton’s equations of motion. Particles are then binned into local cells and undergo a stochastic collision within the cell. Collisions lead to the build up of hydrodynamic interactions, and the frequency and nature of the collisions, along with the fluid properties, determine the transport coefficients. All standard collision rules conserve linear momentum within the cell and can optionally be made to enforce angular-momentum conservation. Currently, we have implemented the following collision rules with linear-momentum conservation only:

Solute particles can be coupled to the MPCD particles during the collision step. This is particularly useful for soft materials like polymers. Standard molecular dynamics methods can be applied to the solute. Coupling to the MPCD particles introduces both hydrodynamic interactions and a heat bath that acts as a thermostat.

The MPCD particles can additionally be coupled to solid boundaries (with no-slip or slip boundary conditions) during the streaming step.

Details of HOOMD-blue’s implementation of the MPCD algorithm can be found in M. P. Howard et al. (2018). Note, though, that continued improvements to the code may cause some deviations.

Getting started

MPCD is intended to be used as an add-on to the standard MD methods in hoomd.md. Getting started can look like:

Initialize the MPCD particles through Snapshot.mpcd. You can include any solute particles in the snapshot as well.
Create the MPCD Integrator. Setup solute particle integration methods and interactions as you normally would to use hoomd.md.
Choose the streaming method from mpcd.stream.
Choose the collision rule from mpcd.collide. Couple the solute to the collision step.
Run your simulation!

class hoomd.mpcd.Integrator(dt, integrate_rotational_dof=False, forces=None, constraints=None, methods=None, rigid=None, half_step_hook=None, streaming_method=None, collision_method=None, virtual_particle_fillers=None, mpcd_particle_sorter=None)¶

Bases: Integrator

MPCD integrator.

Parameters:

dt (float) – Integrator time step size \([\mathrm{time}]\).
methods (Sequence[hoomd.md.methods.Method]) – Sequence of integration methods. The default value of None initializes an empty list.
forces (Sequence[hoomd.md.force.Force]) – Sequence of forces applied to the particles in the system. The default value of None initializes an empty list.
integrate_rotational_dof (bool) – When True, integrate rotational degrees of freedom.
constraints (Sequence[hoomd.md.constrain.Constraint]) – Sequence of constraint forces applied to the particles in the system. The default value of None initializes an empty list. Rigid body objects (i.e. hoomd.md.constrain.Rigid) are not allowed in the list.
rigid (hoomd.md.constrain.Rigid) – An object defining the rigid bodies in the simulation.
half_step_hook (hoomd.md.HalfStepHook) – Enables the user to perform arbitrary computations during the half-step of the integration.
streaming_method (hoomd.mpcd.stream.StreamingMethod) – Streaming method for the MPCD particles.
collision_method (hoomd.mpcd.collide.CollisionMethod) – Collision method for the MPCD particles and any embedded particles.
virtual_particle_fillers – (Sequence[hoomd.mpcd.fill.VirtualParticleFiller]): MPCD virtual-particle filler(s).
mpcd_particle_sorter (hoomd.mpcd.tune.ParticleSorter) – Tuner that sorts the MPCD particles.

The MPCD Integrator enables the MPCD algorithm concurrently with standard MD methods.

In MPCD simulations, dt defines the amount of time that the system is advanced forward every time step. MPCD streaming and collision steps can be defined to occur in multiples of dt. In these cases, any MD particle data will be updated every dt, while the MPCD particle data is updated asynchronously for performance. For example, if MPCD streaming happens every 5 steps, then the particle data will be updated as follows:

        0     1     2     3     4     5
MD:     |---->|---->|---->|---->|---->|
MPCD:   |---------------------------->|

If the MPCD particle data is accessed via the snapshot interface at time step 3, it will actually contain the MPCD particle data for time step 5. The MD particles can be read at any time step because their positions are updated every step.

Examples:

Integrator for only MPCD particles.

stream = hoomd.mpcd.stream.Bulk(period=1)
collide = hoomd.mpcd.collide.StochasticRotationDynamics(
    period=1,
    angle=130)
integrator = hoomd.mpcd.Integrator(
    dt=0.1,
    streaming_method=stream,
    collision_method=collide,
    mpcd_particle_sorter=hoomd.mpcd.tune.ParticleSorter(trigger=20))
simulation.operations.integrator = integrator

MPCD integrator with solutes.

dt_md = 0.005
md_steps_per_collision = 20 # collision time = 0.1

stream = hoomd.mpcd.stream.Bulk(period=md_steps_per_collision)
collide = hoomd.mpcd.collide.StochasticRotationDynamics(
    period=md_steps_per_collision,
    angle=130,
    embedded_particles=hoomd.filter.All())
solute_method = hoomd.md.methods.ConstantVolume(
    filter=collide.embedded_particles)

integrator = hoomd.mpcd.Integrator(
    dt=dt_md,
    methods=[solute_method],
    streaming_method=stream,
    collision_method=collide,
    mpcd_particle_sorter=hoomd.mpcd.tune.ParticleSorter(
        trigger=20*md_steps_per_collision)
    )
simulation.operations.integrator = integrator

MPCD integrator with virtual particle filler.

plates = hoomd.mpcd.geometry.ParallelPlates(separation=6.0)
stream = hoomd.mpcd.stream.BounceBack(period=1, geometry=plates)
collide = hoomd.mpcd.collide.StochasticRotationDynamics(
    period=1,
    angle=130,
    kT=1.0)
filler = hoomd.mpcd.fill.GeometryFiller(
    type="A",
    density=5.0,
    kT=1.0,
    geometry=plates)

integrator = hoomd.mpcd.Integrator(
    dt=0.1,
    streaming_method=stream,
    collision_method=collide,
    virtual_particle_fillers=[filler],
    mpcd_particle_sorter=hoomd.mpcd.tune.ParticleSorter(trigger=20))
simulation.operations.integrator = integrator