Atom filter used to specify whether two atoms are considered neighbors,
for the purpose of tabulating neighbor lists.
Package etomica.nbr.molecule Description
Provides classes that implement neighbor-listing capabilities. Neighbor-listing is
an efficiency used to speed the calculation of the interatomic interactions. With it,
each atom carries with it a list of all the other atoms that are currently
close enough to it to be considered "neighbors", and thus to interact with it. The neighbor
list must be regularly updated as the atoms move around.
To enable neighbor listing:
- Provide an instance of PotentialMasterNbr as an argument to the Simulation constructor.
- Specify the criterion that defines "neighbors", if not using the default criterion.
The neighbor criterion can be specified separately for each potential, and is
accomplished via the setSpecies method of the PotentialMasterNbr instance.
- Register the neighborManager of the PotentialMasterNbr instance as a listener with
all Integrators used in the simulation (the neighbor manager can be accessed via the
getNeighborManager method of PotentialMasterNbr).
Neighbor-list facility is implemented as follows. Neighbor lists are held
by the atom's sequencer (AtomSequencerNbr). Lists are keyed to the potential,
so given an atom it is possible to iterate over all
current neighbors interacting
with it via a particular potential. Such lists are kept only for "real" potentials,
not potential groups. PotentialMaster constructs a NeighborManager, which needs to listen
for interval events, and must therefore be registered with all integrators as
an interval listener. The neighborManager is responsible for keeping the neighbor
lists up to date. The NeighborCriterion interface includes methods that allow it to flag whether an atom has
moved sufficiently far to require that its neighbor list be updated.
With each interval event it loops through all atoms and checks
whether any of the neighbor criteria associated with each indicates that its neighbor list
needs updating. If this situation
is observed for one atom, the neighbor lists of all atoms are updated (with the idea that
they will very soon need to be updated even if they are currently ok).
Once specified via the setSpecies method, NeighborCriterion instances are recorded
in three places.
- Each criterion is held by this NeighborManager, which keeps a master list only to
be able to setBox for all of them when an update is initiated.
- Each criterion is also kept by the AtomType of each atom (using a NeighborManagerAgent
field held by each AtomType instance), and these are used to
identify all criteria applying to an atom when checking if neighbor updates are needed.
- Each criterion is used to wrap a AtomIteratorFiltered instance around the
iterator for the potential, so that any atom pairs yielded by the iterator are, by
There is also a calculate method in PotentialMasterNbr that takes specifically a
PotentialCalculationNbrSetup instance. If this is invoked, the full potential
hierarchy is traversed, and any pair of atoms given to the potential calculation will
have each put on the other's neighbor list -- any pairs given to it are by definition
"neighbors". Pairs are weeded out before reaching the neighbor-setup potential calculation
in two ways:
- A cell-based neighbor list is established automatically with the neighbor-list
facility, so an atom pair will be formed only if the atoms are in molecules that
the cell-list gives as neighbors
- The NeighborCriterion associated with the potential filters out any pair that
do not meet the criterion's definition of "neighbors".
For those atoms identified as neighbors, the calculate method of PotentialMasterNbr
(the one not defined specifically for PotentialCalculationNbrSetup) is configured
to perform neighbor-list iteration
directly -- the iterator for forming pairs of neighboring atoms is defined inside of
PotentialMasterNbr. It performs neighbor iteration for any (leaf or group) atom that has
a non-zero list of potentials applying to it. This will happen if the atom has
any concrete (non-group) potential acting on it (concrete potentials are sometimes defined
for atom groups, not just leaf atoms).
to update the neighbor lists if invoked with
a PotentialCalculationNbrSetup instance.