Skip navigation links

Package etomica.nbr

Provides classes that implement neighbor-listing capabilities.

See: Description

Package etomica.nbr 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:
  1. Provide an instance of PotentialMasterNbr as an argument to the Simulation constructor.
  2. 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.
  3. 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.

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: 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.
Skip navigation links