def type(type, name=None, update=False):
R""" Groups particles by type.
Args:
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
commands (such as analyze.msd) to specify which particles should be operated on.
Note:
Membership in :py:func:`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 :py:meth:`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)
"""
type = str(type);
# check if initialization has occurred
if not hoomd.init.is_initialized():
raise RuntimeError('Cannot create a group before initialization\n');
if name is None:
name = 'type ' + type;
# get a list of types from the particle data
ntypes = hoomd.context.current.system_definition.getParticleData().getNTypes();
type_list = [];
for i in range(0,ntypes):
type_list.append(hoomd.context.current.system_definition.getParticleData().getNameByType(i));
if type not in type_list:
hoomd.context.current.device.cpp_msg.warning(str(type) + " does not exist in the system, creating an empty group\n");
cpp_list = _hoomd.std_vector_uint();
cpp_group = _hoomd.ParticleGroup(hoomd.context.current.system_definition, cpp_list);
else:
type_id = hoomd.context.current.system_definition.getParticleData().getTypeByName(type);
selector = _hoomd.ParticleSelectorType(hoomd.context.current.system_definition, type_id, type_id);
cpp_group = _hoomd.ParticleGroup(hoomd.context.current.system_definition, selector, update);
# notify the user of the created group
hoomd.context.current.device.cpp_msg.notice(2, 'Group "' + name + '" created containing ' + str(cpp_group.getNumMembersGlobal()) + ' particles\n');
# return it in the wrapper class
return group(name, cpp_group);
def rigid():
R""" 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.util.print_status_line()
# check if initialization has occurred
if not hoomd.init.is_initialized():
hoomd.context.msg.error(
"Cannot create a group before initialization\n")
raise RuntimeError('Error creating group')
# create the group
name = 'rigid'
selector = _hoomd.ParticleSelectorRigid(
hoomd.context.current.system_definition, True)
cpp_group = _hoomd.ParticleGroup(hoomd.context.current.system_definition,
selector)
# notify the user of the created group
hoomd.context.msg.notice(
2, 'Group "' + name + '" created containing ' +
str(cpp_group.getNumMembersGlobal()) + ' particles\n')
# return it in the wrapper class
return group(name, cpp_group)
def tag_list(name, tags):
R""" Groups particles by tag list.
Args:
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))
"""
# check if initialization has occurred
if not hoomd.init.is_initialized():
raise RuntimeError('Cannot create a group before initialization\n');
# build a vector of the tags
cpp_list = _hoomd.std_vector_uint();
for t in tags:
cpp_list.append(t);
# create the group
cpp_group = _hoomd.ParticleGroup(hoomd.context.current.system_definition, cpp_list);
# notify the user of the created group
hoomd.context.current.device.cpp_msg.notice(2, 'Group "' + name + '" created containing ' + str(cpp_group.getNumMembersGlobal()) + ' particles\n');
# return it in the wrapper class
return group(name, cpp_group);
def body():
R""" Groups particles that belong to any bodies.
Creates a particle group from particles. All particles that belong to a body will be added to the group.
The group is always named 'body'.
Examples::
body = group.body()
"""
# check if initialization has occurred
if not hoomd.init.is_initialized():
raise RuntimeError('Cannot create a group before initialization\n');
# create the group
name = 'body';
selector = _hoomd.ParticleSelectorBody(hoomd.context.current.system_definition,True);
cpp_group = _hoomd.ParticleGroup(hoomd.context.current.system_definition, selector);
# notify the user of the created group
hoomd.context.current.device.cpp_msg.notice(2, 'Group "' + name + '" created containing ' + str(cpp_group.getNumMembersGlobal()) + ' particles\n');
# return it in the wrapper class
return group(name, cpp_group);
def rigid_center():
R""" 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()
"""
# check if initialization has occurred
if not hoomd.init.is_initialized():
raise RuntimeError('Cannot create a group before initialization\n');
# create the group
name = 'rigid_center';
selector = _hoomd.ParticleSelectorRigidCenter(hoomd.context.current.system_definition);
cpp_group = _hoomd.ParticleGroup(hoomd.context.current.system_definition, selector, True);
# notify the user of the created group
hoomd.context.current.device.cpp_msg.notice(2, 'Group "' + name + '" created containing ' + str(cpp_group.getNumMembersGlobal()) + ' particles\n');
if cpp_group.getNumMembersGlobal() == 0:
hoomd.context.current.device.cpp_msg.notice(2, 'It is OK if there are zero particles in this group. The group will be updated after run().\n');
# return it in the wrapper class
return group(name, cpp_group);
def tags(tag_min, tag_max=None, name=None, update=False):
R""" Groups particles by tag.
Args:
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.util.print_status_line()
# check if initialization has occurred
if not hoomd.init.is_initialized():
hoomd.context.msg.error(
"Cannot create a group before initialization\n")
raise RuntimeError('Error creating group')
# handle the optional argument
if tag_max is not None:
if name is None:
name = 'tags ' + str(tag_min) + '-' + str(tag_max)
else:
# if the option is not specified, tag_max is set equal to tag_min to include only that particle in the range
# and the name is chosen accordingly
tag_max = tag_min
if name is None:
name = 'tag ' + str(tag_min)
# create the group
selector = _hoomd.ParticleSelectorTag(
hoomd.context.current.system_definition, tag_min, tag_max)
cpp_group = _hoomd.ParticleGroup(hoomd.context.current.system_definition,
selector, update)
# notify the user of the created group
hoomd.context.msg.notice(
2, 'Group "' + name + '" created containing ' +
str(cpp_group.getNumMembersGlobal()) + ' particles\n')
# return it in the wrapper class
return group(name, cpp_group)
def all():
R""" Groups all particles.
Creates a particle group from all particles in the simulation.
Examples::
all = group.all()
"""
hoomd.util.print_status_line()
# check if initialization has occurred
if not hoomd.init.is_initialized():
hoomd.context.msg.error(
"Cannot create a group before initialization\n")
raise RuntimeError('Error creating group')
name = 'all'
# the all group is special: when the first one is created, it is cached in the context and future calls to group.all()
# return the cached version
if hoomd.context.current.group_all is not None:
expected_N = hoomd.context.current.system_definition.getParticleData(
).getNGlobal()
if len(hoomd.context.current.group_all) != expected_N:
hoomd.context.msg.error(
"hoomd.context.current.group_all does not appear to be the group of all particles!\n"
)
raise RuntimeError('Error creating group')
return hoomd.context.current.group_all
# create the group
selector = _hoomd.ParticleSelectorAll(
hoomd.context.current.system_definition)
cpp_group = _hoomd.ParticleGroup(hoomd.context.current.system_definition,
selector, True)
# notify the user of the created group
hoomd.context.msg.notice(
2, 'Group "' + name + '" created containing ' +
str(cpp_group.getNumMembersGlobal()) + ' particles\n')
# cache it and then return it in the wrapper class
hoomd.context.current.group_all = group(name, cpp_group)
return hoomd.context.current.group_all
def cuboid(name,
xmin=None,
xmax=None,
ymin=None,
ymax=None,
zmin=None,
zmax=None):
R""" Groups particles in a cuboid.
Args:
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 :py:class:`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 :py:meth:`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.util.print_status_line()
# check if initialization has occurred
if not hoomd.init.is_initialized():
hoomd.context.msg.error(
"Cannot create a group before initialization\n")
raise RuntimeError('Error creating group')
# handle the optional arguments
box = hoomd.context.current.system_definition.getParticleData(
).getGlobalBox()
if xmin is None:
xmin = box.getLo().x - 0.5
if xmax is None:
xmax = box.getHi().x + 0.5
if ymin is None:
ymin = box.getLo().y - 0.5
if ymax is None:
ymax = box.getHi().y + 0.5
if zmin is None:
zmin = box.getLo().z - 0.5
if zmax is None:
zmax = box.getHi().z + 0.5
ll = _hoomd.Scalar3()
ur = _hoomd.Scalar3()
ll.x = float(xmin)
ll.y = float(ymin)
ll.z = float(zmin)
ur.x = float(xmax)
ur.y = float(ymax)
ur.z = float(zmax)
# create the group
selector = _hoomd.ParticleSelectorCuboid(
hoomd.context.current.system_definition, ll, ur)
cpp_group = _hoomd.ParticleGroup(hoomd.context.current.system_definition,
selector)
# notify the user of the created group
hoomd.context.msg.notice(
2, 'Group "' + name + '" created containing ' +
str(cpp_group.getNumMembersGlobal()) + ' particles\n')
# return it in the wrapper class
return group(name, cpp_group)
