Package etomica.nbr.list 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 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.
- How do I access the neighbor manager?
- In the simulation instance, a field referencing the neighbor manager can be made via
NeighborManager nbrManager = ((PotentialMasterNbr)potentialMaster).getNeighborManager();
- What does the neighbor manager do?
- at START or INITIALIZE, it performs a PotentialCalculationAgents calculation to add concrete
potentials to the NeighborManagerAgents of the AtomTypes to which they apply, and it invokes assignCellAll
in the neighbor manager to put all interacting atoms in their cells
- in response to interval events, it updates the neighbor lists if needed
- Where does each atom hold its neighbor lists?
- its sequencer (seq field), which is an instance of AtomSequencerNbr. This has two AtomArrayList
arrays, one for uplist neighbors, and the other for downlist neighbors. Each array element holds a
list of neighbors for interaction with a specific potential.
- What causes each atom to have the neighbor-list sequencer?
- An AtomSequencerFactory that makes AtomSequencerNbr is passed to the AtomFactory constructor.
This factory is obtained from the potential master via the sequencerFactory method, which
is invoked when the Species subclass makes its AtomFactory.
- How do the neighbor lists get updated?
- How are the neighbor lists constructed initially?
- What determines if an atom is a neighbor of another atom?
- How do the cell lists get updated?
- How are the cell lists constructed initially?
- How are the cell sizes specified?
- How are multiple boxs handled?
- How do the potentials get added to the neighborManagerAgents in the atom types?
- the neighbor manager does this in response to a START or INITIALIZE interval event,
by sending a PotentialCalculationAgents instance through the potential master
int nCells = (int)(2*Default.BOX_SIZE/(neighborRangeFac*sqwLambda*Default.ATOM_SIZE));
NeighborCriterion nbrCriterion = new CriterionSimple(space,potential.getRange(),neighborRangeFac*potential.getRange());
How to use
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).
How it works
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.