mpcd.data

Overview

snapshot MPCD system snapshot
system MPCD system data
make_snapshot Creates an empty MPCD system snapshot

Details

MPCD data structures

MPCD and HOOMD

MPCD data is currently initialized in a secondary step from HOOMD using a snapshot interface. Even if only MPCD particles are present in the system, an empty HOOMD system must first be created. Once the HOOMD system has been initialized (see hoomd.init), an MPCD snapshot can be created using:

>>> snap = mpcd.data.make_snapshot(100)

The MPCD system can then initialized from the snapshot (see hoomd.mpcd.init):

>>> mpcd.init.read_snapshot(snap)

Because the MPCD data is stored separately from the HOOMD data, special care must be taken when using certain commands that operate on the HOOMD system data. For example, the HOOMD box size is not permitted to be changed after the MPCD particle data has been initialized (see hoomd.mpcd.init), so any resizes or replications of the HOOMD system must occur before then:

>>> hoomd_sys.replicate(2,2,2)
>>> snap.replicate(2,2,2)
>>> mpcd_sys = mpcd.init.read_snapshot(snap)
>>> hoomd_sys.replicate(2,1,1)
**ERROR**

Similarly, box_resize will also fail after the MPCD system has been initialized.

During a simulation, the MPCD particle data can be read, modified, and restored using take_snapshot() and restore_snapshot():

snap = mpcd_sys.take_snapshot()
# modify snapshot
mpcd_sys.restore_snapshot(snap)

MPCD and MPI

MPCD supports MPI parallelization through domain decomposition. The MPCD data in the snapshot is only valid on rank 0, and is distributed to all ranks through the snapshot collective calls.

Particle data

All MPCD particle data is accessible through the particles snapshot property. The size of the MPCD particle data N can be resized:

>>> snap.particles.resize(200)
>>> print(snap.particles.N)
200

Because the number of MPCD particles in a simulation is large, fewer particle properties are tracked per particle than for standard HOOMD particles. All particle data can be set as for standard snapshots using numpy arrays. Each particle is assigned a tag from 0 to N (exclusive) that is tracked. The following particle properties are recorded:

  • Particle positions are stored as an Nx3 numpy array:

    >>> snap.particles.position[4] = [1., 2., 3.]
    >>> print(snap.particles.position[4])
    [ 1. 2. 3.]
    

    By default, all positions are initialized with zeros.

  • Particle velocities can similarly be manipulated as an Nx3 numpy array:

    >>> snap.particles.velocity[2] = [0.5, 1.5, -0.25]
    >>> print(snap.particles.velocity[2])
    [0.5 1.5 -0.25]
    

    By default, all velocities are initialized with zeros. It is important to reassign these to a sensible value consistent with the temperature of the system.

  • Each particle can be assigned a type (a name for the kind of the particle). First, a list of possible types for the system should be set:

    >>> snap.particles.types = ['A','B']
    print(snapshot.particles.types)
    

    Then, an index is assigned to each particle corresponding to the type:

    >>> snap.particles.typeid[1] = 1 # B
    >>> snap.particles.typeid[2] = 0 # A
    

    By default, all particles are assigned a type index of 0, and no types are set. If no types are specified, type A is created by default at initialization.

  • All MPCD particles have the same mass, which can be accessed or set:

    >>> snap.particles.mass = 1.5
    >>> print(snap.mass)
    1.5
    

    By default, all particles are assigned unit mass.

hoomd.mpcd.data.make_snapshot(N=0)

Creates an empty MPCD system snapshot

Parameters:N (int) – Number of MPCD particles in the snapshot
Returns:MPCD snapshot
Return type:snap (hoomd.mpcd.data.snapshot)

Examples:

snap = mpcd.data.make_snapshot()
snap = mpcd.data.make_snapshot(N=50)

Notes

The HOOMD system must be initialized before the MPCD snapshot is taken, or an error will be raised.

class hoomd.mpcd.data.snapshot(sys_snap)

MPCD system snapshot

Parameters:sys_snap (object) – The C++ representation of the system data snapshot

The MPCD system snapshot must be initialized after the HOOMD system.

This class is not intended to be initialized directly by the user, but rather returned by make_snapshot() or take_snapshot().

particles

MPCD particle data snapshot

replicate(nx=1, ny=1, nz=1)

Replicate the MPCD system snapshot

Parameters:
  • nx (int) – Number of times to replicate snapshot in x
  • ny (int) – Number of times to replicate snapshot in y
  • nz (int) – Number of times to replicate snapshot in z

Examples:

snap.replicate(nx=2,ny=1,nz=3)

This method is intended only to be used with hoomd.data.system_data.replicate() prior to initialization of the MPCD system. The MPCD snapshot must be replicated to a size consistent with the system at the time of initialization. An error will be raised otherwise.

class hoomd.mpcd.data.system(sysdata)

MPCD system data

Parameters:sysdata (object) – C++ representation of the MPCD system data

This class is not intended to be initialized by the user, but is the result returned by hoomd.mpcd.init.

restore_snapshot(snapshot)

Replaces the current MPCD system state

Parameters:snapshot (hoomd.mpcd.data.snapshot) – MPCD system snapshot

The MPCD system data is replaced by the contents of snapshot.

Examples:

snap = mpcd_sys.take_snapshot()
snap.particles.typeid[2] = 1
mpcd_sys.restore_snapshot(snap)
set_params(cell=None)

Set parameters of the MPCD system

Parameters:cell (float) – Edge length of an MPCD cell.

Every MPCD system is given a cell list for binning particles (see mpcd.collide). The size of the cell list sets the length scale over which hydrodynamic interactions are resolved. By default, the system is given a cell size of 1.0, i.e., the cell sets the unit of length, which is typical for most use cases. If your simulation has a different fundamental unit of length, you can adjust the cell size, but be aware that this will also change the fluid properties.

take_snapshot(particles=True)

Takes a snapshot of the current state of the MPCD system

Parameters:particles (bool) – If true, include particle data in snapshot

Examples:

snap = mpcd_sys.take_snapshot()