hoomd.filter

Overview

`ParticleFilter`	Base class for all particle filters.
`All`	Select all particles in the system.
`CustomFilter`	Abstract base class for custom particle filters.
`Intersection`	Set intersection operation.
`Null`	Select no particles.
`Rigid`	Select particles based on inclusion in rigid bodies.
`SetDifference`	Set difference operation.
`Tags`	Select particles by tag.
`Type`	Select particles by type.
`Union`	Set union operation.
`filter_like`	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.

Returns: The particle tags selected by this filter.
Return type: list[int]

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.

__eq__(other): Test for equality between two particle filters.

__hash__(): Return a hash of the filter parameters.

__str__(): Format a human readable string describing the filter.

class hoomd.filter.All

Select all particles in the system.

Base: ParticleFilter

class hoomd.filter.CustomFilter

Abstract base class for custom particle filters.

The class allows the definition of particle filters in Python (see ParticleFilter).

Subclasses of this class must have __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__.

The example below creates a custom filter that filters out particles above and below a certain mass, and uses that filter in a hoomd.write.GSD object.

Example:

class MassFilter(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, MassFilter)
                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 np.copy(snap.particles.tag[indices])

# All particles with 1.0 < mass < 5.0
filter_ = MassFilter(1.0, 5.0)
gsd = hoomd.write.GSD('example.gsd', 100, filter=filter_)

Warning

Custom filters will not work with the set operation particle filters (i.e. hoomd.filter.Union, hoomd.filter.Intersection, or hoomd.filter.SetDifference). This restriction may be lifted in a future version.

abstract __call__(state)

Return the local particle tags that match the filter.

Returns the tags that are local to an MPI rank that match the particle filter. Tag numbers in a hoomd.Snapshot object are just their index.

Note

The exact requirements for the tags returned by custom filters on each MPI rank is that the set union of the returned arrays from each MPI rank be all particles that match the filter. For general use, however, it is recommended that each rank only return the tags for particles that are in the local MPI rank (excluding ghost particles). This is preferable for ease of use with local snapshots to avoid accidentally attempting to access invalid array indices from tags outside of the MPI rank.

Parameters: state (hoomd.State) – The simulation state to return the filtered tags from.
Returns: An array of MPI local tags that match the filter.
Return type: (N,) numpy.ndarray of numpy.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

class hoomd.filter.Null

Select no particles.

Base: ParticleFilter

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 as hoomd.filter.All. The default is ("center",)

Base: ParticleFilter

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

class hoomd.filter.Tags(tags)

Select particles by tag.

Parameters: tags (list[int]) – List of particle tags to select.

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

property tags

List of particle tags to select.

Type: list[int]

class hoomd.filter.Type(types)

Select particles by type.

Parameters: types (list[str]) – List of particle type names to select.

Base: ParticleFilter

property types

List of particle type names to select.

Type: list[str]

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

hoomd.filter.filter_like

An object that acts like a particle filter.

Either a subclass of ParticleFilter or CustomFilter.

alias of Union[ParticleFilter, CustomFilter]