mpcd.stream¶
Overview
Bulk fluid streaming geometry. 

Parallel plate (slit) streaming geometry. 

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 velocityVerlet
scheme for a time \(\Delta t\):
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 (bounceback) rules consistent with either “slip” or “noslip” 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:
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 bounceback method (see
mpcd.integrate
).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.
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 theintegrator
. 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 periodicupdate
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
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 noslip 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
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
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
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.
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
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
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)