Package etomica.atom.iterator

Provides interfaces and classes for iteration of Atoms.

See:
Description

Interface Summary

AtomIterator	Interface for classes that loop over a set of atoms.
AtomIteratorAtomDependent	Interface for an atom iterator that can be altered by setting of an atom.
AtomIteratorBoxDependent	Interface indicating that an atom iterator can determine appropriate atoms for iteration given an arbitrary box.
AtomLeafsetIterator	Interface for classes that loop over a set of atoms.
AtomsetIterator	Interface for classes that loop over a set of atoms.
AtomsetIteratorBasisDependent	Interface for an AtomIterator that can be conditioned with target and basis atoms.
AtomsetIteratorBoxDependent	Interface indicating that an iterator can determine appropriate atoms for iteration given an arbitrary box.
AtomsetIteratorDirectable	Interface for an iterator that can interpret specification of direction UP or DOWN.
AtomsetIteratorPDT	This is an interface for iterators that are box dependent, directable, and targetable.
AtomsetIteratorTargetable	Interface for an iterator that can be targeted at one or more atoms.
MoleculeIterator	Interface for classes that loop over a set of atoms.
MoleculeIteratorBoxDependent	Interface indicating that an atom iterator can determine appropriate atoms for iteration given an arbitrary box.
MoleculeIteratorMoleculeDependent	Interface for an atom iterator that can be altered by setting of an atom.
MoleculesetIterator	Interface for classes that loop over a set of atoms.
MoleculesetIteratorBoxDependent	Interface indicating that an iterator can determine appropriate atoms for iteration given an arbitrary box.
MoleculesetIteratorPDT	This is an interface for iterators that are box dependent, directable, and targetable.
MoleculesetIteratorTargetable	Interface for an iterator that can be targeted at one or more atoms.

Class Summary

ApiBuilder	Provides static methods for construction of some useful pair iterators.
ApiIndexList	Iterator that expires after returning a single atom pair, which is specified by a call to the setPair method.
ApiInnerVariable	Pair iterator synthesized from two atom iterators, such that the inner-loop iteration depends on the outer-loop atom.
ApiInterArrayList	Returns all pairs formed from two different untabbed lists of atoms.
ApiIntergroup	Iterator that returns pairs formed using two different basis atoms, so that the iterates are taken from two different groups.
ApiIntraArrayList	Returns all pairs formed from a single list of atoms.
ApiIntragroup	Returns iterates from the childList of a single basis atom.
ApiLeafAtoms	Iterator that returns all pairs that can be formed from all leaf atoms of a given box.
AtomIteratorAllLeafType	Iterator for all the molecules of a set of species in a box.
AtomIteratorArrayList	An atom iterator of the elements from an AtomArrayList (in proper sequence).
AtomIteratorArrayListAdjacent	Returns one or both of the atoms adjacent to a specified atom in its parent's child list.
AtomIteratorArrayListSimple	An atom iterator of the elements from an AtomArrayList (in proper sequence).
AtomIteratorBasis	Elementary basis-dependent iterator that gives atoms meeting specification of a basis and a target.
AtomIteratorBasisFilteredType
AtomIteratorLeafAtoms	Iterator that will loop over all leaf atoms in a box.
AtomIteratorLeafFilteredType
AtomIteratorNull	Static iterator that returns no atoms.
AtomIteratorSinglet	Iterator that expires after returning a single atom, which is specified by a call to the setAtom method, or via the constructor.
Atomset3IteratorIndexList	Atomset Iterator that iterates over set-of-three atoms
Atomset4IteratorIndexList	Atomset Iterator that iterates over set-of-four atoms
AtomsetIteratorAllLeafAtoms	Iterator for all the molecules of a set of species in a box.
IteratorDirective	Encapsulation of a set of instructions that an AtomsetIterator uses to select the atoms it presents on iteration.
IteratorDirective.Direction
IteratorDirective.PotentialCriterion	Class used to define a criterion that must be satisfied by a potential in order for its atoms to be approved for iteration by an iterator directive.
IteratorFactory	Class for construction of iterators of molecules.
MoleculeIteratorAll	Iterator for all the molecules of a set of species in a box.
MoleculeIteratorAllMolecules	Iterator for all the molecules in a box.
MoleculeIteratorArrayList	An atom iterator of the elements from an AtomArrayList (in proper sequence).
MoleculeIteratorArrayListSimple	An atom iterator of the elements from an AtomArrayList (in proper sequence).
MoleculeIteratorMolecule	Iterator for the molecules of a single species in a box.
MoleculeIteratorSinglet	Iterator that expires after returning a single atom, which is specified by a call to the setAtom method, or via the constructor.
MpiInnerFixed	Pair iterator synthesized from two atom iterators, such that the inner-loop iteration is independent of the outer-loop atom.
MpiInnerVariable	Pair iterator synthesized from two atom iterators, such that the inner-loop iteration depends on the outer-loop atom.
MpiInterspecies1A	Gives pairs formed from the molecules of two different species in a box, taking one molecule of one species with all molecules of the other.
MpiInterspeciesAA	Gives pairs formed from the molecules of two different species in a box.
MpiIntraspecies1A	Gives pairs formed from the molecules of a species in a box, taking one molecule the species with all of its other molecules.
MpiIntraspeciesAA	Gives pairs formed from the molecules of a single species in a box.
MpiMolecule	Adapater class that wraps three atomPair iterators, one suitable for iterating over all molecule pairs in a box (AA), another suitable for iterating over all molecule pairs formed with a target molecule (1A), and the third suitable for iterating over a single molecule pair (11).
TripletInnerSequential

Package etomica.atom.iterator Description

Provides interfaces and classes for iteration of Atoms. The AtomsetIterator defines the basic interface, and this is extended for the specific cases of iteration of Atoms and AtomPairs. The interfaces are defined such that all iterators support both external and internal iteration. With external iteration the client controls the iteration, typically through a whileloop construct: iterator.reset(); while(iterator.hasNext()) { Atom atom = iterator.next(); code using atom }
With internal iteration, the iterator controls. It is invoked by passing to the iterator an appropriate AtomsetAction, which the iterator performs on each iterate: iterator.allAtoms(action);

External iteration always requires invocation of reset before commencing iteration. Clients should always assume that an iterator requires resetting before use (all freshly constructed iterators require reset, for example). On the other hand, internal iteration my be performed without invoking reset. Note that any use of internal iteration will in general change the state of an external iteration, so they should not be used concurrently.

The behavior of many of the iterators is configurable, so they can provide a different set of iterates depending on their conditioning before iteration begins. Repeated iterations (invoking reset in between) will yield the same set of iterates as long as the conditioning isn't changed. Specific ways that iterators can be conditioned are documented with each iterator.

Several of the iterators are designed for iteration within the Atom tree (see etomica.atom). These iterators usually implement AtomIteratorBasisDependent, AtomIteratorTargetable, and/or AtomIteratorDirectable, indicating that they take specification of:

• a basis, which is the parent Atom of the iterates; the basis defines the Atoms subject to iteration (though other specifications may exclude some of these Atoms).
• a target, which is an atom that nominally appears in all iterates (e.g., it is one of the Atoms in every AtomPair iterate); "nominally" is used here because the iterate may be a related Atom, such as the target's parent.
• a direction, which specifies the direction of iteration from the nominal target ("UP" or "DOWN").

Specific behaviors when interpreting these specifications are documented with each iterator. The IteratorDirective class provides a portable specification of a target and direction (among other things that are infrequently used).

Several of the AtomPair iterators (with names beginning "Api") have designations "1A" and "AA". These indicate that the iterator provides (respectively) a specific Atom (1) paired with all (A) atoms matching some specification; or all (A) atoms formed with all (A) other atoms matching specifications given to the iterator.

Most of the pair iterators are implemented such that they return the same AtomPair instance for each iterate; the only change with each iteration is the identity of the Atoms in the pair. Thus one should treat the returned AtomPair as immutable. If the atoms in the instance are reassigned by the client, the iterator may function incorrectly when returning subsequent iterates. For similar reasons, pairs should be used immediately or copied to another AtomPair instance before obtaining the next pair iterate.

The class ApiBuilder provides static methods for constructing some useful AtomPair iterators. It does this by passing appropriate arguments or Atom iterators to configurable AtomPair iterators.

A comprehensive suite of JUnit tests have been developed to test the iterators. These may be consulted as examples for their use; etomica.junit.atom.iterator.