hoomd.data

Overview

hoomd.data.SnapshotParticleData Snapshot of particle data properties.
hoomd.data.angle_data_proxy Access a single angle via a proxy.
hoomd.data.bond_data_proxy Access a single bond via a proxy.
hoomd.data.boxdim Define box dimensions.
hoomd.data.constraint_data_proxy Access a single constraint via a proxy.
hoomd.data.dihedral_data_proxy Access a single dihedral via a proxy.
hoomd.data.force_data_proxy Access the force on a single particle via a proxy.
hoomd.data.gsd_snapshot Read a snapshot from a GSD file.
hoomd.data.particle_data_proxy Access a single particle via a proxy.
hoomd.data.make_snapshot Make an empty snapshot.
hoomd.data.system_data Access system data

Details

Access system configuration data.

Code in the data package provides high-level access to all of the particle, bond and other data that define the current state of the system. You can use python code to directly read and modify this data, allowing you to analyze simulation results while the simulation runs, or to create custom initial configurations with python code.

There are two ways to access the data.

  1. Snapshots record the system configuration at one instant in time. You can store this state to analyze the data, restore it at a future point in time, or to modify it and reload it. Use snapshots for initializing simulations, or when you need to access or modify the entire simulation state.
  2. Data proxies directly access the current simulation state. Use data proxies if you need to only touch a few particles or bonds at a a time.

Snapshots

Relevant methods:

Examples:

snapshot = system.take_snapshot()
system.restore_snapshot(snapshot)
snapshot = data.make_snapshot(N=100, particle_types=['A', 'B'], box=data.boxdim(L=10))
# ... populate snapshot with data ...
init.read_snapshot(snapshot)

Snapshot and MPI

In MPI simulations, the snapshot is only valid on rank 0 by default. make_snapshot, read_snapshot, and take_snapshot, restore_snapshot are collective calls, and need to be called on all ranks. But only rank 0 can access data in the snapshot:

snapshot = system.take_snapshot(all=True)
if comm.get_rank() == 0:
    s = init.create_random(N=100, phi_p=0.05);numpy.mean(snapshot.particles.velocity))
    snapshot.particles.position[0] = [1,2,3];

system.restore_snapshot(snapshot);
snapshot = data.make_snapshot(N=10, box=data.boxdim(L=10))
if comm.get_rank() == 0:
    snapshot.particles.position[:] = ....
init.read_snapshot(snapshot)

You can explicitly broadcast the information contained in the snapshot to all other ranks, using broadcast.

snapshot = system.take_snapshot(all=True) snapshot.broadcast() # broadcast from rank 0 to all other ranks using MPI snapshot.broadcast_all() # broadcast from partition 0 to all other ranks and partitions using MPI

Simulation box

You can access the simulation box from a snapshot:

>>> print(snapshot.box)
Box: Lx=17.3646569289 Ly=17.3646569289 Lz=17.3646569289 xy=0.0 xz=0.0 yz=0.0 dimensions=3

and can change it:

>>> snapshot.box = data.boxdim(Lx=10, Ly=20, Lz=30, xy=1.0, xz=0.1, yz=2.0)
>>> print(snapshot.box)
Box: Lx=10 Ly=20 Lz=30 xy=1.0 xz=0.1 yz=2.0 dimensions=3

All particles must be inside the box before using the snapshot to initialize a simulation or restoring it. The dimensionality of the system (2D/3D) cannot change after initialization.

Particle properties

Particle properties are present in snapshot.particles. Each property is stored in a numpy array that directly accesses the memory of the snapshot. References to these arrays will become invalid when the snapshot itself is garbage collected.

  • N is the number of particles in the particle data snapshot:

    >>> print(snapshot.particles.N)
    64000
    
  • Change the number of particles in the snapshot with resize. Existing particle properties are preserved after the resize. Any newly created particles will have default values. After resizing, existing references to the numpy arrays will be invalid, access them again from snapshot.particles.*:

    >>> snapshot.particles.resize(1000);
    
  • The list of all particle types in the simulation can be accessed and modified:

    >>> print(snapshot.particles.types)
    ['A', 'B', 'C']
    >>> snapshot.particles.types = ['1', '2', '3', '4'];
    
  • Individual particles properties are stored in numpy arrays. Vector quantities are stored in Nx3 arrays of floats (or doubles) and scalar quantities are stored in N length 1D arrays:

    >>> print(snapshot.particles.position[10])
    [ 1.2398  -10.2687  100.6324]
    
  • Various properties can be accessed of any particle, and the numpy arrays can be sliced or passed whole to other routines:

    >>> print(snapshot.particles.typeid[10])
    2
    >>> print(snapshot.particles.velocity[10])
    (-0.60267972946166992, 2.6205904483795166, -1.7868227958679199)
    >>> print(snapshot.particles.mass[10])
    1.0
    >>> print(snapshot.particles.diameter[10])
    1.0
    
  • Particle properties can be set in the same way. This modifies the data in the snapshot, not the current simulation state:

    >>> snapshot.particles.position[10] = [1,2,3]
    >>> print(snapshot.particles.position[10])
    [ 1.  2.  3.]
    
  • Snapshots store particle types as integers that index into the type name array:

    >>> print(snapshot.particles.typeid)
    [ 0.  1.  2.  0.  1.  2.  0.  1.  2.  0.]
    >>> snapshot.particles.types = ['A', 'B', 'C'];
    >>> snapshot.particles.typeid[0] = 2;   # C
    >>> snapshot.particles.typeid[1] = 0;   # A
    >>> snapshot.particles.typeid[2] = 1;   # B
    

For a list of all particle properties in the snapshot see hoomd.data.SnapshotParticleData.

Bonds

Bonds are stored in snapshot.bonds. hoomd.data.system_data.take_snapshot() does not record the bonds by default, you need to request them with the argument bonds=True.

  • N is the number of bonds in the bond data snapshot:

    >>> print(snapshot.bonds.N)
    100
    
  • Change the number of bonds in the snapshot with resize. Existing bonds are preserved after the resize. Any newly created bonds will be initialized to 0. After resizing, existing references to the numpy arrays will be invalid, access them again from snapshot.bonds.*:

    >>> snapshot.bonds.resize(1000);
    
  • Bonds are stored in an Nx2 numpy array group. The first axis accesses the bond i. The second axis j goes over the individual particles in the bond. The value of each element is the tag of the particle participating in the bond:

    >>> print(snapshot.bonds.group)
    [[0 1]
    [1 2]
    [3 4]
    [4 5]]
    >>> snapshot.bonds.group[0] = [10,11]
    
  • Snapshots store bond types as integers that index into the type name array:

    >>> print(snapshot.bonds.typeid)
    [ 0.  1.  2.  0.  1.  2.  0.  1.  2.  0.]
    >>> snapshot.bonds.types = ['A', 'B', 'C'];
    >>> snapshot.bonds.typeid[0] = 2;   # C
    >>> snapshot.bonds.typeid[1] = 0;   # A
    >>> snapshot.bonds.typeid[2] = 1;   # B
    

Angles, dihedrals and impropers

Angles, dihedrals, and impropers are stored similar to bonds. The only difference is that the group array is sized appropriately to store the number needed for each type of bond.

  • snapshot.angles.group is Nx3
  • snapshot.dihedrals.group is Nx4
  • snapshot.impropers.group is Nx4

Special pairs

Special pairs are exactly handled like bonds. The snapshot entry is called pairs.

Constraints

Pairwise distance constraints are added and removed like bonds. They are defined between two particles. The only difference is that instead of a type, constraints take a distance as parameter.

  • N is the number of constraints in the constraint data snapshot:

    >>> print(snapshot.constraints.N)
    99
    
  • Change the number of constraints in the snapshot with resize. Existing constraints are preserved after the resize. Any newly created constraints will be initialized to 0. After resizing, existing references to the numpy arrays will be invalid, access them again from snapshot.constraints.*:

    >>> snapshot.constraints.resize(1000);
    
  • Bonds are stored in an Nx2 numpy array group. The first axis accesses the constraint i. The second axis j goes over the individual particles in the constraint. The value of each element is the tag of the particle participating in the constraint:

    >>> print(snapshot.constraints.group)
    [[4 5]
    [6 7]
    [6 8]
    [7 8]]
    >>> snapshot.constraints.group[0] = [10,11]
    
  • Snapshots store constraint distances as floats:

    >>> print(snapshot.constraints.value)
    [ 1.5 2.3 1.0 0.1 ]
    

data_proxy Proxy access

For most of the cases below, it is assumed that the result of the initialization command was saved at the beginning of the script:

system = init.read_xml(filename="input.xml")

Warning

The performance of the proxy access is very slow. Use snapshots to access the whole system configuration efficiently.

Simulation box

You can access the simulation box:

>>> print(system.box)
Box: Lx=17.3646569289 Ly=17.3646569289 Lz=17.3646569289 xy=0.0 xz=0.0 yz=0.0

and can change it:

>>> system.box = data.boxdim(Lx=10, Ly=20, Lz=30, xy=1.0, xz=0.1, yz=2.0)
>>> print(system.box)
Box: Lx=10 Ly=20 Lz=30 xy=1.0 xz=0.1 yz=2.0

All particles must always remain inside the box. If a box is set in this way such that a particle ends up outside of the box, expect errors to be thrown or for hoomd to just crash. The dimensionality of the system cannot change after initialization.

Particle properties

For a list of all particle properties that can be read and/or set, see hoomd.data.particle_data_proxy. The examples here only demonstrate changing a few of them.

system.particles is a window into all of the particles in the system. It behaves like standard python list in many ways.

  • Its length (the number of particles in the system) can be queried:

    >>> len(system.particles)
    64000
    
  • A short summary can be printed of the list:

    >>> print(system.particles)
    Particle Data for 64000 particles of 1 type(s)
    
  • The list of all particle types in the simulation can be accessed:

    >>> print(system.particles.types)
    ['A']
    >>> print system.particles.types
    Particle types: ['A']
    
  • Particle types can be added between hoomd.run() commands:

    >>> system.particles.types.add('newType')
    
  • Individual particles can be accessed at random:

    >>> i = 4
    >>> p = system.particles[i]
    
  • Various properties can be accessed of any particle (note that p can be replaced with system.particles[i] and the results are the same):

    >>> p.tag
    4
    >>> p.position
    (27.296911239624023, -3.5986068248748779, 10.364067077636719)
    >>> p.velocity
    (-0.60267972946166992, 2.6205904483795166, -1.7868227958679199)
    >>> p.mass
    1.0
    >>> p.diameter
    1.0
    >>> p.type
    'A'
    >>> p.tag
    4
    
  • Particle properties can be set in the same way:

    >>> p.position = (1,2,3)
    >>> p.position
    (1.0, 2.0, 3.0)
    
  • Finally, all particles can be easily looped over:

    for p in system.particles:
        p.velocity = (0,0,0)
    

Particles may be added at any time in the job script, and a unique tag is returned:

>>> system.particles.add('A')
>>> t = system.particles.add('B')

Particles may be deleted by index:

>>> del system.particles[0]
>>> print(system.particles[0])
tag         : 1
position    : (23.846603393554688, -27.558368682861328, -20.501256942749023)
image       : (0, 0, 0)
velocity    : (0.0, 0.0, 0.0)
acceleration: (0.0, 0.0, 0.0)
charge      : 0.0
mass        : 1.0
diameter    : 1.0
type        : A
typeid      : 0
body        : 4294967295
orientation : (1.0, 0.0, 0.0, 0.0)
net_force   : (0.0, 0.0, 0.0)
net_energy  : 0.0
net_torque  : (0.0, 0.0, 0.0)

Note

The particle with tag 1 is now at index 0. No guarantee is made about how the order of particles by index will or will not change, so do not write any job scripts which assume a given ordering.

To access particles in an index-independent manner, use their tags. For example, to remove all particles of type ‘A’, do:

tags = []
for p in system.particles:
    if p.type == 'A'
        tags.append(p.tag)

Then remove each of the particles by their unique tag:

for t in tags:
    system.particles.remove(t)

Particles can also be accessed through their unique tag:

t = system.particles.add('A')
p = system.particles.get(t)

Any defined group can be used in exactly the same way as system.particles above, only the particles accessed will be those just belonging to the group. For a specific example, the following will set the velocity of all particles of type A to 0:

groupA = group.type(name="a-particles", type='A')
for p in groupA:
    p.velocity = (0,0,0)

Bond Data

Bonds may be added at any time in the job script:

>>> system.bonds.add("bondA", 0, 1)
>>> system.bonds.add("bondA", 1, 2)
>>> system.bonds.add("bondA", 2, 3)
>>> system.bonds.add("bondA", 3, 4)

Individual bonds may be accessed by index:

>>> bnd = system.bonds[0]
>>> print(bnd)
tag          : 0
typeid       : 0
a            : 0
b            : 1
type         : bondA
>>> print(bnd.type)
bondA
>>> print(bnd.a)
0
>>> print(bnd.b)
1

Warning

The order in which bonds appear by index is not static and may change at any time!

Bonds may be deleted by index:

>>> del system.bonds[0]
>>> print(system.bonds[0])
tag          : 3
typeid       : 0
a            : 3
b            : 4
type         : bondA

To access bonds in an index-independent manner, use their tags. For example, to delete all bonds which connect to particle 2, first loop through the bonds and build a list of bond tags that match the criteria:

tags = []
for b in system.bonds:
    if b.a == 2 or b.b == 2:
        tags.append(b.tag)

Then remove each of the bonds by their unique tag:

for t in tags:
    system.bonds.remove(t)

Bonds can also be accessed through their unique tag:

t = system.bonds.add('polymer',0,1)
p = system.bonds.get(t)

Angle, Dihedral, and Improper Data

Angles, Dihedrals, and Impropers may be added at any time in the job script:

>>> system.angles.add("angleA", 0, 1, 2)
>>> system.dihedrals.add("dihedralA", 1, 2, 3, 4)
>>> system.impropers.add("dihedralA", 2, 3, 4, 5)

Individual angles, dihedrals, and impropers may be accessed, deleted by index or removed by tag with the same syntax as described for bonds, just replace bonds with angles, dihedrals, or, impropers and access the appropriate number of tag elements (a,b,c for angles) (a,b,c,d for dihedrals/impropers).

Constraints

Constraints may be added and removed from within the job script.

To add a constraint of length 1.5 between particles 0 and 1:

>>> t = system.constraints.add(0, 1, 1.5)

To remove it again:

>>> system.constraints.remove(t)

Forces

Forces can be accessed in a similar way:

>>> lj = pair.lj(r_cut=3.0)
>>> lj.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0)
>>> print(lj.forces[0])
tag         : 0
force       : (-0.077489577233791351, -0.029512746259570122, -0.13215918838977814)
virial      : -0.0931386947632
energy      : -0.0469368174672
>>> f0 = lj.forces[0]
>>> print(f0.force)
(-0.077489577233791351, -0.029512746259570122, -0.13215918838977814)
>>> print(f0.virial)
-0.093138694763n
>>> print(f0.energy)
-0.0469368174672

In this manner, forces due to the lj pair force, bonds, and any other force commands in hoomd can be accessed independently from one another. See hoomd.data.force_data_proxy for a definition of each data field.

For advanced code using the particle data access from python, it is important to understand that the hoomd particles, forces, bonds, et cetera, are accessed as proxies. This means that after:

p = system.particles[i]

is executed, p does not store the position, velocity, … of particle i. Instead, it stores i and provides an interface to get/set the properties on demand. This has some side effects you need to be aware of.

  • First, it means that p (or any other proxy reference) always references the current state of the particle. As an example, note how the position of particle p moves after the run() command:

    >>> p.position
    (-21.317455291748047, -23.883811950683594, -22.159387588500977)
    >>> run(1000)
    ** starting run **
    ** run complete **
    >>> p.position
    (-19.774742126464844, -23.564577102661133, -21.418502807617188)
    
  • Second, it means that copies of the proxy reference cannot be changed independently:

    p.position
    >>> a = p
    >>> a.position
    (-19.774742126464844, -23.564577102661133, -21.418502807617188)
    >>> p.position = (0,0,0)
    >>> a.position
    (0.0, 0.0, 0.0)
    
class hoomd.data.SnapshotParticleData

Snapshot of particle data properties.

Users should not create SnapshotParticleData directly. Use hoomd.data.make_snapshot() or hoomd.data.system_data.take_snapshot() to make snapshots.

N

Number of particles in the snapshot

Type:int
types

List of string type names (assignable)

Type:list
position

(Nx3) numpy array containing the position of each particle (float or double)

Type:numpy.ndarray
orientation

(Nx4) numpy array containing the orientation quaternion of each particle (float or double)

Type:numpy.ndarray
velocity

(Nx3) numpy array containing the velocity of each particle (float or double)

Type:numpy.ndarray
acceleration

(Nx3) numpy array containing the acceleration of each particle (float or double)

Type:numpy.ndarray
typeid

Length N numpy array containing the type id of each particle (32-bit unsigned int)

Type:numpy.ndarray
mass

Length N numpy array containing the mass of each particle (float or double)

Type:numpy.ndarray
charge

Length N numpy array containing the charge of each particle (float or double)

Type:numpy.ndarray
diameter

Length N numpy array containing the diameter of each particle (float or double)

Type:numpy.ndarray
image

(Nx3) numpy array containing the image of each particle (32-bit int)

Type:numpy.ndarray
body

Length N numpy array containing the body of each particle (32-bit unsigned int). -1 indicates a free particle, and larger negative numbers indicate floppy bodies.

Type:numpy.ndarray
moment_inertia

(Nx3) numpy array containing the principal moments of inertia of each particle (float or double)

Type:numpy.ndarray
angmom

(Nx4) numpy array containing the angular momentum quaternion of each particle (float or double)

Type:numpy.ndarray

See also

hoomd.data

resize(N)

Resize the snapshot to hold N particles.

Parameters:N (int) – new size of the snapshot.

resize() changes the size of the arrays in the snapshot to hold N particles. Existing particle properties are preserved after the resize. Any newly created particles will have default values. After resizing, existing references to the numpy arrays will be invalid, access them again from snapshot.particles.*

class hoomd.data.angle_data_proxy(adata, tag)

Access a single angle via a proxy.

angle_data_proxy provides access to all of the properties of a single angle in the system. See hoomd.data for examples.

tag

A unique integer attached to each angle (not in any particular range). A angle’s tag remains fixed during its lifetime. (Tags previously used by removed angles may be recycled).

Type:int
typeid

Type id of the angle.

Type:int
a

The tag of the first particle in the angle.

Type:int
b

The tag of the second particle in the angle.

Type:int
c

The tag of the third particle in the angle.

Type:int
type

angle type name.

Type:str

In the current version of the API, only already defined type names can be used. A future improvement will allow dynamic creation of new type names from within the python API.

class hoomd.data.bond_data_proxy(bdata, tag)

Access a single bond via a proxy.

bond_data_proxy provides access to all of the properties of a single bond in the system. See hoomd.data for examples.

tag

A unique integer attached to each bond (not in any particular range). A bond’s tag remains fixed during its lifetime. (Tags previously used by removed bonds may be recycled).

Type:int
typeid

Type id of the bond.

Type:int
a

The tag of the first particle in the bond.

Type:int
b

The tag of the second particle in the bond.

Type:int
type

Bond type name.

Type:str

In the current version of the API, only already defined type names can be used. A future improvement will allow dynamic creation of new type names from within the python API.

class hoomd.data.boxdim(Lx=1.0, Ly=1.0, Lz=1.0, xy=0.0, xz=0.0, yz=0.0, dimensions=3, L=None, volume=None)

Define box dimensions.

Parameters:
  • Lx (float) – box extent in the x direction (distance units)
  • Ly (float) – box extent in the y direction (distance units)
  • Lz (float) – box extent in the z direction (distance units)
  • xy (float) – tilt factor xy (dimensionless)
  • xz (float) – tilt factor xz (dimensionless)
  • yz (float) – tilt factor yz (dimensionless)
  • dimensions (int) – Number of dimensions in the box (2 or 3).
  • L (float) – shorthand for specifying Lx=Ly=Lz=L (distance units)
  • volume (float) – Scale the given box dimensions up to the this volume (area if dimensions=2)

Simulation boxes in hoomd are specified by six parameters, Lx, Ly, Lz, xy, xz and yz. For full details, see TODO: ref page. A boxdim provides a way to specify all six parameters for a given box and perform some common operations with them. Modifying a boxdim does not modify the underlying simulation box in hoomd. A boxdim can be passed to an initialization method or to assigned to a saved sysdef variable (system.box = new_box) to set the simulation box.

Access attributes directly:

b = data.boxdim(L=20);
b.xy = 1.0;
b.yz = 0.5;
b.Lz = 40;

Two dimensional systems

2D simulations in hoomd are embedded in 3D boxes with short heights in the z direction. To create a 2D box, set dimensions=2 when creating the boxdim. This will force Lz=1 and xz=yz=0. init commands that support 2D boxes will pass the dimensionality along to the system. When you assign a new boxdim to an already initialized system, the dimensionality flag is ignored. Changing the number of dimensions during a simulation run is not supported.

In 2D boxes, volume is in units of area.

Shorthand notation

data.boxdim accepts the keyword argument L=x as shorthand notation for Lx=x, Ly=x, Lz=x in 3D and Lx=x, Ly=z, Lz=1 in 2D. If you specify both L= and Lx,Ly, or Lz, then the value for L will override the others.

Examples:

  • Cubic box with given volume: data.boxdim(volume=V)
  • Triclinic box in 2D with given area: data.boxdim(xy=1.0, dimensions=2, volume=A)
  • Rectangular box in 2D with given area and aspect ratio: data.boxdim(Lx=1, Ly=aspect, dimensions=2, volume=A)
  • Cubic box with given length: data.boxdim(L=10)
  • Fully define all box parameters: data.boxdim(Lx=10, Ly=20, Lz=30, xy=1.0, xz=0.5, yz=0.1)
get_lattice_vector(i)

Get a lattice vector.

Parameters:i (int) – (=0,1,2) direction of lattice vector
Returns:The lattice vector (3-tuple) along direction i.
get_volume()

Get the box volume.

Returns:The box volume (area in 2D).
make_fraction(v)

Scale a vector to fractional coordinates.

Parameters:v (tuple) – The vector to convert to fractional coordinates

make_fraction() takes a vector in a box and computes a vector where all components are between 0 and 1.

Returns:The scaled vector.
min_image(v)

Apply the minimum image convention to a vector using periodic boundary conditions.

Parameters:v (tuple) – The vector to apply minimum image to
Returns:The minimum image as a tuple.
scale(sx=1.0, sy=1.0, sz=1.0, s=None)

Scale box dimensions.

Parameters:
  • sx (float) – scale factor in the x direction
  • sy (float) – scale factor in the y direction
  • sz (float) – scale factor in the z direction
  • s (float) – Shorthand for sx=s, sy=x, sz=s

Scales the box by the given scale factors. Tilt factors are not modified.

Returns:A reference to the modified box.
set_volume(volume)

Set the box volume.

Parameters:volume (float) – new box volume (area if dimensions=2)

Scale the box to the given volume (or area).

Returns:A reference to the modified box.
wrap(v, img=(0, 0, 0))

Wrap a vector using the periodic boundary conditions.

Parameters:
  • v (tuple) – The vector to wrap
  • img (tuple) – A vector of integer image flags that will be updated (optional)
Returns:

The wrapped vector and the image flags in a tuple.

class hoomd.data.constraint_data_proxy(cdata, tag)

Access a single constraint via a proxy.

constraint_data_proxy provides access to all of the properties of a single constraint in the system. See hoomd.data for examples.

tag

A unique integer attached to each constraint (not in any particular range). A constraint’s tag remains fixed during its lifetime. (Tags previously used by removed constraints may be recycled).

Type:int
d

The constraint distance.

Type:float
a

The tag of the first particle in the constraint.

Type:int
b

The tag of the second particle in the constraint.

Type:int
class hoomd.data.dihedral_data_proxy(ddata, tag)

Access a single dihedral via a proxy.

dihedral_data_proxy provides access to all of the properties of a single dihedral in the system. See hoomd.data for examples.

tag

A unique integer attached to each dihedral (not in any particular range). A dihedral’s tag remains fixed during its lifetime. (Tags previously used by removed dihedrals may be recycled).

Type:int
typeid

Type id of the dihedral.

Type:int
a

The tag of the first particle in the dihedral.

Type:int
b

The tag of the second particle in the dihedral.

Type:int
c

The tag of the third particle in the dihedral.

Type:int
d

The tag of the fourth particle in the dihedral.

Type:int
type

dihedral type name.

Type:str

In the current version of the API, only already defined type names can be used. A future improvement will allow dynamic creation of new type names from within the python API.

class hoomd.data.force_data_proxy(force, tag)

Access the force on a single particle via a proxy.

force_data_proxy provides access to the current force, virial, and energy of a single particle due to a single force computation. See hoomd.data for examples.

force

(float, x, y, z) - the current force on the particle (force units)

Type:tuple
virial

This particle’s contribution to the total virial tensor.

Type:tuple
energy

This particle’s contribution to the total potential energy (energy units)

Type:float
torque

(float x, y, z) - current torque on the particle (torque units)

Type:float
hoomd.data.gsd_snapshot(filename, frame=0)

Read a snapshot from a GSD file.

Parameters:
  • filename (str) – GSD file to read the snapshot from.
  • frame (int) – Frame to read from the GSD file. Negative values index from the end of the file.

hoomd.data.gsd_snapshot() opens the given GSD file and reads a snapshot from it.

hoomd.data.make_snapshot(N, box, particle_types=['A'], bond_types=[], angle_types=[], dihedral_types=[], improper_types=[], pair_types=[], dtype='float')

Make an empty snapshot.

Parameters:
  • N (int) – Number of particles to create.
  • box (hoomd.data.boxdim) – Simulation box parameters.
  • particle_types (list) – Particle type names (must not be zero length).
  • bond_types (list) – Bond type names (may be zero length).
  • angle_types (list) – Angle type names (may be zero length).
  • dihedral_types (list) – Dihedral type names (may be zero length).
  • improper_types (list) – Improper type names (may be zero length).
  • pair_types (list) – Special pair type names (may be zero length). .. versionadded:: 2.1
  • dtype (str) – Data type for the real valued numpy arrays in the snapshot. Must be either ‘float’ or ‘double’.

Examples:

snapshot = data.make_snapshot(N=1000, box=data.boxdim(L=10))
snapshot = data.make_snapshot(N=64000, box=data.boxdim(L=1, dimensions=2, volume=1000), particle_types=['A', 'B'])
snapshot = data.make_snapshot(N=64000, box=data.boxdim(L=20), bond_types=['polymer'], dihedral_types=['dihedralA', 'dihedralB'], improper_types=['improperA', 'improperB', 'improperC'])
... set properties in snapshot ...
init.read_snapshot(snapshot);

hoomd.data.make_snapshot() creates all particles with default properties. You must set reasonable values for particle properties before initializing the system with hoomd.init.read_snapshot().

The default properties are:

  • position 0,0,0
  • velocity 0,0,0
  • image 0,0,0
  • orientation 1,0,0,0
  • typeid 0
  • charge 0
  • mass 1.0
  • diameter 1.0
class hoomd.data.particle_data_proxy(pdata, tag)

Access a single particle via a proxy.

particle_data_proxy provides access to all of the properties of a single particle in the system. See hoomd.data for examples.

tag

A unique name for the particle in the system. Tags run from 0 to N-1.

Type:int
acceleration

A 3-tuple of floats (x, y, z). Acceleration is a calculated quantity and cannot be set. (in acceleration units)

Type:tuple
typeid

The type id of the particle.

Type:int
position

(x, y, z) (float, in distance units).

Type:tuple
image

(x, y, z) (int).

Type:tuple
velocity

(x, y, z) (float, in velocity units).

Type:tuple
charge

Particle charge.

Type:float
mass

(in mass units).

Type:float
diameter

(in distance units).

Type:float
type

Particle type name.

Type:str
body

Body id. -1 for free particles, 0 or larger for rigid bodies, and -2 or lesser for floppy bodies.

Type:int
orientation

(w,x,y,z) (float, quaternion).

Type:tuple
net_force

Net force on particle (x, y, z) (float, in force units).

Type:tuple
net_energy

Net contribution of particle to the potential energy (in energy units).

Type:float
net_torque

Net torque on the particle (x, y, z) (float, in torque units).

Type:tuple
net_virial

Net virial for the particle (xx,yy,zz, xy, xz, yz)

Type:tuple
class hoomd.data.system_data(sysdef)

Access system data

system_data provides access to the different data structures that define the current state of the simulation. See hoomd.data for a full explanation of how to use by example.

box
Type:hoomd.data.boxdim
particles
Type:hoomd.data.particle_data_proxy
bonds
Type:hoomd.data.bond_data_proxy
angles
Type:hoomd.data.angle_data_proxy
dihedrals
Type:hoomd.data.dihedral_data_proxy
impropers
Type:hoomd.data.dihedral_data_proxy
constraint
Type:hoomd.data.constraint_data_proxy
pairs

New in version 2.1.

Type:hoomd.data.bond_data_proxy
replicate(nx=1, ny=1, nz=1)

Replicates the system along the three spatial dimensions.

Parameters:
  • nx (int) – Number of times to replicate the system along the x-direction
  • ny (int) – Number of times to replicate the system along the y-direction
  • nz (int) – Number of times to replicate the system along the z-direction

This method replicates particles along all three spatial directions, as opposed to replication implied by periodic boundary conditions. The box is resized and the number of particles is updated so that the new box holds the specified number of replicas of the old box along all directions. Particle coordinates are updated accordingly to fit into the new box. All velocities and other particle properties are replicated as well. Also bonded groups between particles are replicated.

Examples:

system = init.read_xml("some_file.xml")
system.replicate(nx=2,ny=2,nz=2)

Note

The dimensions of the processor grid are not updated upon replication. For example, if an initially cubic box is replicated along only one spatial direction, this could lead to decreased performance if the processor grid was optimal for the original box dimensions, but not for the new ones.

restore_snapshot(snapshot)

Re-initializes the system from a snapshot.

Parameters:snapshot – . The snapshot to initialize the system from.

Snapshots temporarily store system data. Snapshots contain the complete simulation state in a single object. They can be used to restart a simulation.

Example use cases in which a simulation may be restarted from a snapshot include python-script-level Monte-Carlo schemes, where the system state is stored after a move has been accepted (according to some criterion), and where the system is re-initialized from that same state in the case when a move is not accepted.

Example:

system = init.read_xml("some_file.xml")

... run a simulation ...

snapshot = system.take_snapshot(all=True)
...
system.restore_snapshot(snapshot)

Warning

restore_snapshot() may invalidate force coefficients, neighborlist r_cut values, and other per type quantities if called within a callback during a run(). You can restore a snapshot during a run only if the snapshot is of a previous state of the currently running system. Otherwise, you need to use restore_snapshot() between run() commands to ensure that all per type coefficients are updated properly.

take_snapshot(particles=True, bonds=False, pairs=False, integrators=False, all=False, dtype='float')

Take a snapshot of the current system data.

Parameters:
  • particles (bool) – When True, particle data is included in the snapshot.
  • bonds (bool) – When true, bond, angle, dihedral, improper and constraint data is included.
  • pairs (bool) – When true, special pair data is included .. versionadded:: 2.1
  • integrators (bool) – When true, integrator data is included the snapshot.
  • all (bool) – When true, the entire system state is saved in the snapshot.
  • dtype (str) – Datatype for the snapshot numpy arrays. Must be either ‘float’ or ‘double’.
Returns:

The snapshot object.

This functions returns a snapshot object. It contains the current. partial or complete simulation state. With appropriate options it is possible to select which data properties should be included in the snapshot

Examples:

snapshot = system.take_snapshot()
snapshot = system.take_snapshot()
snapshot = system.take_snapshot(bonds=true)