hoomd.filter¶
Overview
Base class for all particle filters. |
|
Select all particles in the system. |
|
Base class for custom particle filters. |
|
Set intersection operation. |
|
Select no particles. |
|
Select particles based on inclusion in rigid bodies. |
|
Set difference operation. |
|
Select particles by tag. |
|
Select particles by type. |
|
Set union operation. |
|
An object that acts like a particle filter. |
Details
Particle filters.
Particle filters describe criteria to select subsets of particles in the
system for use by various operations throughout HOOMD. To maintain high
performance, filters are not re-evaluated on every use. Instead, each unique
particular filter (defined by the class name and hash) is mapped to a group,
an internally maintained list of the selected particles. Subsequent uses of the
same particle filter specification (in the same hoomd.Simulation
) will resolve
to the same group and the originally selected particles, even if the state
of the system has changed.
Groups are not completely static. HOOMD-blue automatically re-evaluates the
filter specifications and updates the group membership whenever the number of
particles in the simulation changes. Use hoomd.update.FilterUpdater
to
manually trigger updates to group membership.
For molecular dynamics simulations, each group maintains a count of the number
of degrees of freedom given to the group by integration methods. This count is
used by hoomd.md.compute.ThermodynamicQuantities
and the integration methods
themselves to compute the kinetic temperature. See
hoomd.State.update_group_dof
for details on when HOOMD-blue updates this
count.
- class hoomd.filter.ParticleFilter¶
Base class for all particle filters.
This class provides methods common to all particle filters.
Attention
Users should instantiate one of the subclasses. Calling
ParticleFilter
directly may result in an error.- __call__(state)¶
Evaluate the filter.
Note
This method may return tags that are only present on the local MPI rank. The full set of particles selected is the combination of these the lists across ranks with a set union operation.
Example:
locally_selected_tags = filter(simulation.state)
- __eq__(other)¶
Test for equality between two particle filters.
Example:
if filter == other: pass
- __hash__()¶
Return a hash of the filter parameters.
Example:
hash(filter)
- __str__()¶
Format a human readable string describing the filter.
Example:
print(str(filter))
- class hoomd.filter.All¶
Select all particles in the system.
Base:
ParticleFilter
Example:
all_ = hoomd.filter.All()
- class hoomd.filter.CustomFilter¶
Base class for custom particle filters.
The class allows the definition of particle filters in Python (see
ParticleFilter
).Subclasses of this class must implement
__hash__
,__eq__
, and__call__
methods. The__hash__
and__eq__
methods will be used to cache the particle tags associated with a filter, thus__eq__
must correctly disambiguate any filters that would choose different particles. For more information on the Python data model see https://docs.python.org/3/reference/datamodel.html#object.__hash__ and https://docs.python.org/3/reference/datamodel.html#object.__eq__.Example:
class MassRangeFilter(hoomd.filter.CustomFilter): def __init__(self, min_mass, max_mass): self.min_mass = min_mass self.max_mass = max_mass def __hash__(self): return hash((self.min_mass, self.max_mass)) def __eq__(self, other): return (isinstance(other, MassRangeFilter) and self.min_mass == other.min_mass and self.max_mass == other.max_mass) def __call__(self, state): with state.cpu_local_snapshot as snap: masses = snap.particles.mass indices = ((masses > self.min_mass) & (masses < self.max_mass)) return numpy.copy(snap.particles.tag[indices]) mass_range_filter = MassRangeFilter(1.0, 5.0) print(mass_range_filter(simulation.state))
Warning
Custom filters will not work with the set operation particle filters (i.e.
hoomd.filter.Union
,hoomd.filter.Intersection
, orhoomd.filter.SetDifference
). Implement any needed logic in your__call__
method.- abstract __call__(state)¶
Return the local particle tags that match the filter.
Returns the tags that match the particle filter. Tag numbers in a
hoomd.Snapshot
object are equal to their index.Note
In MPI domain decomposition simulation, the set union of the returned arrays from each MPI rank must contain all particle tags that match the filter.
Tip
To obtain the best performance, use local snaphots to access particle data, locally evaluate the filter on each rank, and return the list of local tags that match.
__call__
should not perform the set union, that is the caller’s responsibility.- Parameters:
state (
hoomd.State
) – The simulation state to return the filtered tags from.- Returns:
An array of particle tags filter.
- Return type:
(N,)
numpy.ndarray
ofnumpy.uint64
- class hoomd.filter.Intersection(f, g)¶
Set intersection operation.
- Parameters:
f (ParticleFilter) – First set in the intersection.
g (ParticleFilter) – Second set in the intersection.
Intersection
is a composite filter. It selects particles in the set intersection \(f \cap g\).Base:
ParticleFilter
Example:
intersection = hoomd.filter.Intersection(filter1, filter2)
- class hoomd.filter.Null¶
Select no particles.
Base:
ParticleFilter
Example:
null = hoomd.filter.Null()
- class hoomd.filter.Rigid(flags=('center',))¶
Select particles based on inclusion in rigid bodies.
- Parameters:
flags (
tuple
[str
], optional) – A tuple of strings of values “center”, “constituent”, or “free”. These string flags specify what kinds of particles to filter: “center” will include central particles in a rigid body, “constituent” will include non-central particles in a rigid body, and “free” will include all particles not in a rigid body. Specifying all three is the same ashoomd.filter.All
. The default is("center",)
Base:
ParticleFilter
Examples:
rigid_center_and_free = hoomd.filter.Rigid(flags=('center', 'free'))
rigid_center = hoomd.filter.Rigid(flags=('center',))
- class hoomd.filter.SetDifference(f, g)¶
Set difference operation.
- Parameters:
f (ParticleFilter) – First set in the difference.
g (ParticleFilter) – Second set in the difference.
SetDifference
is a composite filter. It selects particles in the set difference \(f \setminus g\).Base:
ParticleFilter
Example:
set_difference = hoomd.filter.SetDifference(filter1, filter2)
- class hoomd.filter.Tags(tags)¶
Select particles by tag.
A particle tag is a unique identifier assigned to each particle in the simulation state. When the state is first initialized, it assigns tags 0 through
N_particles
to the particles in the order provided.Base:
ParticleFilter
Example:
tags = hoomd.filter.Tags([0, 1, 2])
- class hoomd.filter.Type(types)¶
Select particles by type.
Base:
ParticleFilter
Example:
type_A_B = hoomd.filter.Type(['A', 'B'])
- class hoomd.filter.Union(f, g)¶
Set union operation.
- Parameters:
f (ParticleFilter) – First set in the union.
g (ParticleFilter) – Second set in the union.
Union
is a composite filter. It selects particles in the set union \(f \cup g\).Base:
ParticleFilter
Example:
union = hoomd.filter.Union(filter1, filter2)
- hoomd.filter.filter_like¶
An object that acts like a particle filter.
Either a subclass of
ParticleFilter
orCustomFilter
.alias of
ParticleFilter
|CustomFilter