Skip navigation links

Package etomica.atom.iterator

Provides interfaces and classes for iteration of Atoms.

See: Description

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:

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.

Skip navigation links