hoomd.group

Overview

hoomd.group.all Groups all particles.
hoomd.group.charged Groups particles that are charged.
hoomd.group.cuboid Groups particles in a cuboid.
hoomd.group.difference Create a new group from the set difference or complement of two existing groups.
hoomd.group.group Defines a group of particles
hoomd.group.intersection Create a new group from the set intersection of two existing groups.
hoomd.group.nonrigid Groups particles that do not belong to rigid bodies.
hoomd.group.rigid Groups particles that belong to rigid bodies.
hoomd.group.rigid_center Groups particles that are center particles of rigid bodies.
hoomd.group.tag_list Groups particles by tag list.
hoomd.group.tags Groups particles by tag.
hoomd.group.type Groups particles by type.
hoomd.group.union Create a new group from the set union of two existing groups.

Details

Commands for grouping particles

This package contains various commands for making groups of particles

hoomd.group.all()

Groups all particles.

Creates a particle group from all particles in the simulation.

Examples:

all = group.all()
hoomd.group.charged(name='charged')

Groups particles that are charged.

Parameters:name (str) – User-assigned name for this group.

Creates a particle group containing all particles that have a non-zero charge.

Warning

This group currently does not support being updated when the number of particles changes.

Examples:

a = group.charged()
b = group.charged(name="cp")
hoomd.group.cuboid(name, xmin=None, xmax=None, ymin=None, ymax=None, zmin=None, zmax=None)

Groups particles in a cuboid.

Parameters:
  • name (str) – User-assigned name for this group
  • xmin (float) – (if set) Lower left x-coordinate of the cuboid (in distance units)
  • xmax (float) – (if set) Upper right x-coordinate of the cuboid (in distance units)
  • ymin (float) – (if set) Lower left y-coordinate of the cuboid (in distance units)
  • ymax (float) – (if set) Upper right y-coordinate of the cuboid (in distance units)
  • zmin (float) – (if set) Lower left z-coordinate of the cuboid (in distance units)
  • zmax (float) – (if set) Upper right z-coordinate of the cuboid (in distance units)

If any of the above parameters is not set, it will automatically be placed slightly outside of the simulation box dimension, allowing easy specification of slabs.

Creates a particle group from particles that fall in the defined cuboid. Membership tests are performed via xmin <= x < xmax (and so forth for y and z) so that directly adjacent cuboids do not have overlapping group members.

Note

Membership in cuboid is defined at time of group creation. Once created, any particles added to the system will not be added to the group. Any particles that move into the cuboid region will not be added automatically, and any that move out will not be removed automatically.

Between runs, you can force a group to update its membership with the particles currently in the originally defined region using hoomd.group.group.force_update().

Examples:

slab = group.cuboid(name="slab", ymin=-3, ymax=3)
cube = group.cuboid(name="cube", xmin=0, xmax=5, ymin=0, ymax=5, zmin=0, zmax=5)
run(100)
# Remove particles that left the region and add particles that entered the region.
cube.force_update()
hoomd.group.difference(name, a, b)

Create a new group from the set difference or complement of two existing groups.

Parameters:
  • name (str) – User-assigned name for this group.
  • a (group) – First group.
  • b (group) – Second group.

The set difference of a and b is defined to be the set of particles that are in a and not in b. This can be useful for inverting the sense of a group (see below).

A new group called name is created.

Warning

The group is static and will not update if particles are added to or removed from the system.

Examples:

groupA = group.type(name='groupA', type='A')
all = group.all()
nottypeA = group.difference(name="particles-not-typeA", a=all, b=groupA)
class hoomd.group.group(name, cpp_group)

Defines a group of particles

group should not be created directly in user code. The following methods can be used to create particle groups.

The above functions assign a descriptive name based on the criteria chosen. That name can be easily changed if desired:

groupA = group.type('A')
groupA.name = "my new group name"

Once a group has been created, it can be combined with others via set operations to form more complicated groups. Available operations are:

Note

Groups need to be consistent with the particle data. If a particle member is removed from the simulation, it will be temporarily removed from the group as well, that is, even though the group reports that tag as a member, it will act as if the particle was not existent. If a particle with the same tag is later added to the simulation, it will become member of the group again.

Examples:

# create a group containing all particles in group A and those with
# tags 100-199
groupA = group.type('A')
group100_199 = group.tags(100, 199);
group_combined = group.union(name="combined", a=groupA, b=group100_199);

# create a group containing all particles in group A that also have
# tags 100-199
group_combined2 = group.intersection(name="combined2", a=groupA, b=group100_199);

# create a group containing all particles that are not in group A
all = group.all()
group_notA = group.difference(name="notA", a=all, b=groupA)

A group can also be queried with python sequence semantics.

Examples:

groupA = group.type('A')
# print the number of particles in group A
print len(groupA)
# print the position of the first particle in the group
print groupA[0].position
# set the velocity of all particles in groupA to 0
for p in groupA:
    p.velocity = (0,0,0)

For more information and examples on accessing the data in this way, see hoomd.data.

force_update()

Force an update of the group.

Re-evaluate all particles against the original group selection criterion and build a new member list based on the current state of the system. For example, call hoomd.group.group.force_update() set set a cuboid group’s membership to particles that are currently in the defined region.

Groups made by a combination (union, intersection, difference) of other groups will not update their membership, they are always static.

hoomd.group.intersection(name, a, b)

Create a new group from the set intersection of two existing groups.

Parameters:
  • name (str) – User-assigned name for this group.
  • a (group) – First group.
  • b (group) – Second group.

A new group is created that contains all particles of a that are also in b, and is given the name name.

Warning

The group is static and will not update if particles are added to or removed from the system.

Examples:

groupA = group.type(name='groupA', type='A')
group100_199 = group.tags(name='100_199', tag_min=100, tag_max=199);
groupC = group.intersection(name="groupC", a=groupA, b=group100_199)
hoomd.group.nonrigid()

Groups particles that do not belong to rigid bodies.

Creates a particle group from particles. All particles that do not belong to a rigid body will be added to the group. The group is always named ‘nonrigid’.

Examples:

nonrigid = group.nonrigid()
hoomd.group.rigid()

Groups particles that belong to rigid bodies.

Creates a particle group from particles. All particles that belong to a rigid body will be added to the group. The group is always named ‘rigid’.

Examples:

rigid = group.rigid()
hoomd.group.rigid_center()

Groups particles that are center particles of rigid bodies.

Creates a particle group from particles. All particles that are central particles of rigid bodies be added to the group. The group is always named ‘rigid_center’.

Examples:

rigid = group.rigid_center()
hoomd.group.tag_list(name, tags)

Groups particles by tag list.

Parameters:
  • tags (list) – List of particle tags to include in the group
  • name (str) – User-assigned name for this group.

Creates a particle group from particles with the given tags. Can be used to implement advanced grouping not available with existing group commands.

Examples:

a = group.tag_list(name="a", tags = [0, 12, 18, 205])
b = group.tag_list(name="b", tags = range(20,400))
hoomd.group.tags(tag_min, tag_max=None, name=None, update=False)

Groups particles by tag.

Parameters:
  • tag_min (int) – First tag in the range to include (inclusive)
  • tag_max (int) – Last tag in the range to include (inclusive)
  • name (str) – User-assigned name for this group. If a name is not specified, a default one will be generated.
  • update (bool) – When True, update list of group members when particles are added to or removed from the simulation.

Creates a particle group from particles that match the given tag range.

The tag_max is optional. If it is not specified, then a single particle with tag=tag_min will be added to the group.

Examples:

half1 = group.tags(name="first-half", tag_min=0, tag_max=999)
half2 = group.tags(name="second-half", tag_min=1000, tag_max=1999)
hoomd.group.type(type, name=None, update=False)

Groups particles by type.

Parameters:
  • type (str) – Name of the particle type to add to the group.
  • name (str) – User-assigned name for this group. If a name is not specified, a default one will be generated.
  • update (bool) – When true, update list of group members when particles are added to or removed from the simulation.

Creates a particle group from particles that match the given type. The group can then be used by other hoomd_script commands (such as analyze.msd) to specify which particles should be operated on.

Note

Membership in hoomd.group.type() is defined at time of group creation. Once created, any particles added to the system will be added to the group if update is set to True. However, if you change a particle type it will not be added to or removed from this group.

Between runs, you can force a group to update its membership with the particles currently in the originally specified type using hoomd.group.group.force_update().

Examples:

groupA = group.type(name='a-particles', type='A')
groupB = group.type(name='b-particles', type='B')
groupB = group.type(name='b-particles', type='B',update=True)
hoomd.group.union(name, a, b)

Create a new group from the set union of two existing groups.

Parameters:
  • name (str) – User-assigned name for this group.
  • a (group) – First group.
  • b (group) – Second group.

A new group is created that contains all particles present in either group a or b, and is given the name name.

Warning

The group is static and will not update if particles are added to or removed from the system.

Examples:

groupA = group.type(name='groupA', type='A')
groupB = group.type(name='groupB', type='B')
groupAB = group.union(name="ab-particles", a=groupA, b=groupB)