mpcd.stream

Overview

Bulk

Bulk fluid.

BounceBack

Streaming with bounce-back rule for surfaces.

StreamingMethod

Base streaming method.

Details

MPCD streaming methods.

An MPCD streaming method is required to update the particle positions over time. It is meant to be used in conjunction with an mpcd.Integrator and CollisionMethod. Particle positions are propagated ballistically according to Newton’s equations using a velocity-Verlet scheme for a time \(\Delta t\):

\[ \begin{align}\begin{aligned}\mathbf{v}(t + \Delta t/2) &= \mathbf{v}(t) + (\mathbf{f}/m)(\Delta t / 2)\\\mathbf{r}(t+\Delta t) &= \mathbf{r}(t) + \mathbf{v}(t+\Delta t/2) \Delta t\\\mathbf{v}(t + \Delta t) &= \mathbf{v}(t + \Delta t/2) + (\mathbf{f}/m)(\Delta t / 2)\end{aligned}\end{align} \]

where r and v are the particle position and velocity, respectively, and f is the external force acting on the particles of mass m. For a list of forces that can be applied, see mpcd.force.

class hoomd.mpcd.stream.BounceBack(period, geometry, mpcd_particle_force=None)

Bases: StreamingMethod

Streaming with bounce-back rule for surfaces.

Parameters:

  • period (int) – Number of integration steps covered by streaming step.

  • geometry (hoomd.mpcd.geometry.Geometry) – Surface to bounce back from.

  • mpcd_particle_force (BodyForce) – Body force on MPCD particles.

One of the main strengths of the MPCD algorithm is that it can be coupled to complex boundaries, defined by a geometry. This StreamingMethod reflects the MPCD particles from boundary surfaces using specular reflections (bounce-back) rules consistent with either “slip” or “no-slip” hydrodynamic boundary conditions. The external force is only applied to the particles at the beginning and the end of this process.

Although a streaming geometry is enforced on the MPCD particles, there are a few important caveats:

  1. Embedded particles are not coupled to the boundary walls. They must be confined by an appropriate method, e.g., an external potential, an explicit particle wall, or a bounce-back method (hoomd.mpcd.methods.BounceBack).

  2. The geometry exists inside a fully periodic simulation box. Hence, the box must be padded large enough that the MPCD cells do not interact through the periodic boundary. Usually, this means adding at least one extra layer of cells in the confined dimensions. Your periodic simulation box will be validated by the geometry.

  3. It is an error for MPCD particles to lie “outside” the geometry. You must initialize your system carefully to ensure all particles are “inside” the geometry.

Examples:

Shear flow between moving parallel plates.

stream = hoomd.mpcd.stream.BounceBack(
    period=1,
    geometry=hoomd.mpcd.geometry.ParallelPlates(
        separation=6.0, speed=1.0, no_slip=True))
simulation.operations.integrator.streaming_method = stream

Pressure driven flow between parallel plates.

stream = hoomd.mpcd.stream.BounceBack(
    period=1,
    geometry=hoomd.mpcd.geometry.ParallelPlates(
        separation=6.0, no_slip=True),
    mpcd_particle_force=hoomd.mpcd.force.ConstantForce((1, 0, 0)))
simulation.operations.integrator.streaming_method = stream
geometry

Surface to bounce back from (read only).

Type:

hoomd.mpcd.geometry.Geometry

check_mpcd_particles()

Check if MPCD particles are inside geometry.

This method can only be called after this object is attached to a simulation.

Returns:

True if all MPCD particles are inside geometry.

Examples:

assert stream.check_mpcd_particles()
class hoomd.mpcd.stream.Bulk(period, mpcd_particle_force=None)

Bases: StreamingMethod

Bulk fluid.

Parameters:

  • period (int) – Number of integration steps covered by streaming step.

  • mpcd_particle_force (BodyForce) – Body force on MPCD particles.

Bulk streams the MPCD particles in a fully periodic geometry (2D or 3D). This geometry is appropriate for modeling bulk fluids, i.e., those that are not confined by any surfaces.

Examples:

Bulk streaming.

stream = hoomd.mpcd.stream.Bulk(period=1)
simulation.operations.integrator.streaming_method = stream

Bulk streaming with applied force.

stream = hoomd.mpcd.stream.Bulk(
    period=1,
    mpcd_particle_force=hoomd.mpcd.force.ConstantForce((1, 0, 0)))
simulation.operations.integrator.streaming_method = stream
class hoomd.mpcd.stream.StreamingMethod(period, mpcd_particle_force=None)

Bases: Operation

Base streaming method.

Parameters:

  • period (int) – Number of integration steps covered by streaming step.

  • mpcd_particle_force (BodyForce) – Force on MPCD particles.

period

Number of integration steps covered by streaming step (read only).

The MPCD particles will be streamed every time the timestep is a multiple of period. The streaming time is hence equal to period steps of the Integrator. Typically period should be equal to the period for the corresponding collision method. A smaller fraction of this may be used if an external force is applied, and more faithful numerical integration is needed.

Type:

int

mpcd_particle_force

Body force on MPCD particles.

The mpcd_particle_force cannot be changed after the StreamingMethod is constructed, but its attributes can be modified.

Type:

BodyForce