mpcd.stream

Overview

bulk Bulk fluid streaming geometry.
slit Parallel plate (slit) streaming geometry.
slit_pore Parallel plate (slit) pore streaming geometry.

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 integrator and collision method (see collide). 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.

Since one of the main strengths of the MPCD algorithm is that it can be coupled to complex boundaries, the streaming geometry can be configured. MPCD solvent particles will be reflected 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.) To help fully enforce the boundary conditions, “virtual” MPCD particles can be inserted near the boundary walls.

Although a streaming geometry is enforced on the MPCD solvent 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 (see mpcd.integrate).
  2. The confined 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 confined geometry.
  3. It is an error for MPCD particles to lie “outside” the confined geometry. You must initialize your system carefully using the snapshot interface to ensure all particles are “inside” the geometry. An error will be raised otherwise.
class hoomd.mpcd.stream.bulk(period=1)

Bulk fluid streaming geometry.

Parameters:period (int) – Number of integration steps between collisions.

bulk performs the streaming step for MPCD particles in a fully periodic geometry (2D or 3D). This geometry is appropriate for modeling bulk fluids. The streaming time \(\Delta t\) is equal to period steps of the integrator. For a pure MPCD fluid, typically period should be 1. When particles are embedded in the MPCD fluid through the collision step, period should be equal to the MPCD collision period for best performance. The MPCD particle positions will be updated every time the simulation timestep is a multiple of period. This is equivalent to setting a phase of 0 using the terminology of other periodic update methods.

Example for pure MPCD fluid:

mpcd.integrator(dt=0.1)
mpcd.collide.srd(seed=42, period=1, angle=130.)
mpcd.stream.bulk(period=1)

Example for embedded particles:

mpcd.integrator(dt=0.01)
mpcd.collide.srd(seed=42, period=10, angle=130., group=hoomd.group.all())
mpcd.stream.bulk(period=10)
disable()

Disable the streaming method

Examples:

method.disable()

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

enable()

Enable the streaming method

Examples:

method.enable()

Enabling the streaming method adds it to the current MPCD system definition. Only one streaming method can be attached to the system at any time. If another method is already set, disable() must be called first before switching. Streaming will occur when the timestep is the next multiple of period.

remove_force()

Remove the external force field for streaming.

Warning

This only removes the force on the MPCD particles. If you have embedded particles, you must separately disable any corresponding external force.

Example:

streamer.remove_force()
set_force(force)

Set the external force field for streaming.

Parameters:force (mpcd.force) – External force field to apply to MPCD particles.

Setting an external force will generate a flow of the MPCD particles subject to the boundary conditions of the streaming geometry. Note that the force field should be chosen in a way that makes sense for the geometry (e.g., so that the box is not continually accelerating).

Warning

The force applies only to the MPCD particles. If you have embedded particles, you should usually additionally specify a force from md.force for that particle group.

Examples:

f = mpcd.force.constant(field=(1.0,0.0,0.0))
streamer.set_force(f)
set_period(period)

Set the streaming period.

Parameters:period (int) – New streaming period.

The MPCD streaming 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.stream.slit(H, V=0.0, boundary='no_slip', period=1)

Parallel plate (slit) streaming geometry.

Parameters:
  • H (float) – channel half-width
  • V (float) – wall speed (default: 0)
  • boundary (str) – boundary condition at wall (“slip” or “no_slip””)
  • period (int) – Number of integration steps between collisions

The slit geometry represents a fluid confined between two infinite parallel plates. The slit is centered around the origin, and the walls are placed at \(z=-H\) and \(z=+H\), so the total channel width is 2H. The walls may be put into motion, moving with speeds \(-V\) and \(+V\) in the x direction, respectively. If combined with a no-slip boundary condition, this motion can be used to generate simple shear flow.

The “inside” of the slit is the space where \(|z| < H\).

Examples:

stream.slit(period=10, H=30.)
stream.slit(period=1, H=25., V=0.1)

New in version 2.6.

disable()

Disable the streaming method

Examples:

method.disable()

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

enable()

Enable the streaming method

Examples:

method.enable()

Enabling the streaming method adds it to the current MPCD system definition. Only one streaming method can be attached to the system at any time. If another method is already set, disable() must be called first before switching. Streaming will occur when the timestep is the next multiple of period.

remove_filler()

Remove the virtual particle filler.

Example:

slit.remove_filler()

New in version 2.6.

remove_force()

Remove the external force field for streaming.

Warning

This only removes the force on the MPCD particles. If you have embedded particles, you must separately disable any corresponding external force.

Example:

streamer.remove_force()
set_filler(density, kT, seed, type='A')

Add virtual particles to slit channel.

Parameters:
  • density (float) – Density of virtual particles.
  • kT (float) – Temperature of virtual particles.
  • seed (int) – Seed to pseudo-random number generator for virtual particles.
  • type (str) – Type of the MPCD particles to fill with.

The virtual particle filler draws particles within the volume outside the slit walls that could be overlapped by any cell that is partially inside the slit channel (between the parallel plates). The particles are drawn from the velocity distribution consistent with kT and with the given density. The mean of the distribution is zero in y and z, but is equal to the wall speed in x. Typically, the virtual particle density and temperature are set to the same conditions as the solvent.

The virtual particles will act as a weak thermostat on the fluid, and so energy is no longer conserved. Momentum will also be sunk into the walls.

Example:

slit.set_filler(density=5.0, kT=1.0, seed=42)

New in version 2.6.

set_force(force)

Set the external force field for streaming.

Parameters:force (mpcd.force) – External force field to apply to MPCD particles.

Setting an external force will generate a flow of the MPCD particles subject to the boundary conditions of the streaming geometry. Note that the force field should be chosen in a way that makes sense for the geometry (e.g., so that the box is not continually accelerating).

Warning

The force applies only to the MPCD particles. If you have embedded particles, you should usually additionally specify a force from md.force for that particle group.

Examples:

f = mpcd.force.constant(field=(1.0,0.0,0.0))
streamer.set_force(f)
set_params(H=None, V=None, boundary=None)

Set parameters for the slit geometry.

Parameters:
  • H (float) – channel half-width
  • V (float) – wall speed (default: 0)
  • boundary (str) – boundary condition at wall (“slip” or “no_slip””)

Changing any of these parameters will require the geometry to be constructed and validated, so do not change these too often.

Examples:

slit.set_params(H=15.0)
slit.set_params(V=0.2, boundary="no_slip")

New in version 2.6.

set_period(period)

Set the streaming period.

Parameters:period (int) – New streaming period.

The MPCD streaming 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.stream.slit_pore(H, L, boundary='no_slip', period=1)

Parallel plate (slit) pore streaming geometry.

Parameters:
  • H (float) – channel half-width
  • L (float) – pore half-length
  • boundary (str) – boundary condition at wall (“slip” or “no_slip””)
  • period (int) – Number of integration steps between collisions

The slit pore geometry represents a fluid partially confined between two parallel plates that have finite length in x. The slit pore is centered around the origin, and the walls are placed at \(z=-H\) and \(z=+H\), so the total channel width is 2H. They extend from \(x=-L\) to \(x=+L\) (total length 2L), where additional solid walls with normals in x prevent penetration into the regions above / below the plates. The plates are infinite in y. Outside the pore, the simulation box has full periodic boundaries; it is not confined by any walls. This model hence mimics a narrow pore in, e.g., a membrane.

_images/mpcd_slit_pore.png

The “inside” of the slit_pore is the space where \(|z| < H\) for \(|x| < L\), and the entire space where \(|x| \ge L\).

Examples:

stream.slit_pore(period=10, H=30., L=10.)
stream.slit_pore(period=1, H=25., L=25.)

New in version 2.7.

disable()

Disable the streaming method

Examples:

method.disable()

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

enable()

Enable the streaming method

Examples:

method.enable()

Enabling the streaming method adds it to the current MPCD system definition. Only one streaming method can be attached to the system at any time. If another method is already set, disable() must be called first before switching. Streaming will occur when the timestep is the next multiple of period.

remove_filler()

Remove the virtual particle filler.

Example:

slit_pore.remove_filler()
remove_force()

Remove the external force field for streaming.

Warning

This only removes the force on the MPCD particles. If you have embedded particles, you must separately disable any corresponding external force.

Example:

streamer.remove_force()
set_filler(density, kT, seed, type='A')

Add virtual particles to slit pore.

Parameters:
  • density (float) – Density of virtual particles.
  • kT (float) – Temperature of virtual particles.
  • seed (int) – Seed to pseudo-random number generator for virtual particles.
  • type (str) – Type of the MPCD particles to fill with.

The virtual particle filler draws particles within the volume outside the slit pore boundaries that could be overlapped by any cell that is partially inside the slit pore. The particles are drawn from the velocity distribution consistent with kT and with the given density. The mean of the distribution is zero in x, y, and z. Typically, the virtual particle density and temperature are set to the same conditions as the solvent.

The virtual particles will act as a weak thermostat on the fluid, and so energy is no longer conserved. Momentum will also be sunk into the walls.

Example:

slit_pore.set_filler(density=5.0, kT=1.0, seed=42)
set_force(force)

Set the external force field for streaming.

Parameters:force (mpcd.force) – External force field to apply to MPCD particles.

Setting an external force will generate a flow of the MPCD particles subject to the boundary conditions of the streaming geometry. Note that the force field should be chosen in a way that makes sense for the geometry (e.g., so that the box is not continually accelerating).

Warning

The force applies only to the MPCD particles. If you have embedded particles, you should usually additionally specify a force from md.force for that particle group.

Examples:

f = mpcd.force.constant(field=(1.0,0.0,0.0))
streamer.set_force(f)
set_params(H=None, L=None, boundary=None)

Set parameters for the slit geometry.

Parameters:
  • H (float) – channel half-width
  • L (float) – pore half-length
  • boundary (str) – boundary condition at wall (“slip” or “no_slip””)

Changing any of these parameters will require the geometry to be constructed and validated, so do not change these too often.

Examples:

slit_pore.set_params(H=15.0)
slit_pore.set_params(L=10.0, boundary="no_slip")
set_period(period)

Set the streaming period.

Parameters:period (int) – New streaming period.

The MPCD streaming 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)