Package etomica.nbr.molecule

Provides classes that implement neighbor-listing capabilities.

See: Description

Interface Summary

Interface	Description
NeighborCriterionMolecular	Atom filter used to specify whether two atoms are considered neighbors, for the purpose of tabulating neighbor lists.

Class Summary

Class	Description
CriterionAdapterMolecular	Wraps another criterion while adding additional criteria to the acceptance decision.
CriterionAllMolecular	Specifies that all atoms pairs are to be considered neighbors.
CriterionSimpleMolecular	Simple neighbor criterion based on distance between the two molecules If the molecule moves further than r^2; the update method will kick in to update the neighborlist.
CriterionSpecies	Filters molecule to match a given species.
CriterionSpeciesPair	Filters molecule pairs to match a given pair of Species.
PotentialMasterNbrMolecular

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:

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.

• 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 definition, neighbors.

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.