OOF2: The Manual

Components
	Indices and Iterators

Name

Components — Iterable object containing a set of FieldIndexes

Synopses

C++ Synopsis

#include "engine/fieldindex.h"

class Components {
  virtual ComponentIteratorP begin() const;
  virtual ComponentIteratorP end() const;
}

Python Synopsis

from ooflib.SWIG.engine.fieldindex import Components

class Components:
  def begin(self)
  def end(self)
  def __iter__(self)

Source Files

SRC/engine/fieldindex.h: C++ header
SRC/engine/fieldindex.C: C++ source code
SRC/engine/fieldindex.swg: SWIG source code
SRC/engine/fieldindex.spy: Python code included in the SWIG output

Description

Subclasses of Components are container-like objects that can be iterated over to produce the FieldIndexes for the different components of a Field, Flux, or Equation. They aren't real containers, but they simulate them for the purposes of iteration. In C++ they have begin() and end() methods that can be used as STL iterators:

for(ComponentIteratorP i = field.components()->begin(); i != field.components()->end(); i++) {
    IndexP index = *i;
    ...
}

for(IndexP index : *field.components()) {
    ...
}

The Components base class exists in Python, but is usually hidden. In Python, Field::components() returns a generator function that loops over the components, using the Components class and its begin() and end() methods under the hood. When used like this

for index in field.components():
    ...    index is a FieldIndex object

the Components object and its iterators never need to be referred to explicitly. The subclasses are not defined in Python, since their methods are available via the base class.

The various subclasses of Field, Flux, and Equation have components() methods that return pointers to instances of the appropriate subclass of Components. These pointers point to static objects and do not have to (must not) be deleted.

Methods

`virtual ComponentIteratorP begin() const`

begin() returns a ComponentIteratorP pointing to the first component.

`virtual ComponentIteratorP end() const`

end() returns a ComponentIteratorP pointing past the last component.

`iter(self)`

__iter__ is a generator function that yields ComponentIterators for all of the components in turn. (Python only.)

Subclasses

Instances of these subclasses are only created by the Fields, Fluxes, and other iterable objects that use the same Components methods. The details of the constructors are therefore not discussed here. The subclasses have no methods other than those discussed above.

The begin() and end() methods of each subclass return ComponentIterators of the appropriate type wrapped in a ComponentIteratorP. The list below includes the FieldIndex and ComponentIterator type for each Components subclass.

EmptyFieldComponents. The components of an object that has no components. There is no FieldIndex class. The iterator class is EmptyFieldIterator.
ScalarFieldComponents. The single component of a scalar quantity, such as a scalar Field or the divergence of a vector Flux. The index and iterator classes are ScalarFieldIndex ScalarFieldIterator.
VectorFieldComponents. The components of a vector quantity, such as a vector Field or the divergence of a tensor Flux. Whether or not all of the components are included, or only the in- or out-of-plane ones, is determined by the Planarity argument of the components() function call that created the VectorFieldComponents. The index and iterator classes are VectorFieldIndex and VectorFieldIterator.
OutOfPlaneVectorFieldComponents. The out-of-plane components of a vector quantity. The difference between OutOfPlaneVectorFieldComponents and VectorFieldComponents with out-of-plane Planarity is that OutOfPlaneVectorFieldComponents is appropriate for iterating over a list or array of components that only includes the out-of-plane components, while VectorFieldComponents iterates over the out-of-plane components in a list that includes all of the components. The index and iterator classes are OutOfPlaneVectorFieldIndex and OutOfPlaneVectorFieldIterator.
SymTensorComponents . All of the components of a 3×3 symmetric tensor. The index and iterator classes are SymTensorIndex and SymTensorIterator^[70].
SymTensorInPlaneComponents . The in-plane components of a 3×3 symmetric tensor object, such as a SymmetricTensorFlux or SymmMatrix3. The index and iterator classes are SymTensorIndex and SymTensorIterator^[70].
SymTensorOutOfPlaneComponents. The out-of-plane components of a 3×3 symmetric tensor object, such as a SymmetricTensorFlux or SymmMatrix3. This iterates over the components assuming that they are part of a larger list or array that contains all of the components. Iterating generates SymTensorIndex objects with Voigt indices 2, 3, and 4, and FieldIndex::integer() values 2, 3, and 4. The index and iterator classes are SymTensorIndex and SymTensorOutOfPlaneIterator^[70].
OutOfPlaneSymTensorComponents. The out-of-plane components of a 3×3 symmetric tensor object, such as a SymmetricTensorFlux or SymmMatrix3. The difference between this and SymTensorOutOfPlaneComponents is that this version is appropriate for looping over a list or array containing only the out-of-plane components. Iterating produces OutOfPlaneSymTensorIndex objects with Voigt indices 2, 3, and 4, and FieldIndex::integer() values 0, 1, and 2. The index and iterator classes are OutOfPlaneSymTensorIndex and OutOfPlaneSymTensorIterator^[70].

^[70] SymTensorComponents and related classes need to be cleaned up. They should use Planarity arguments, like VectorFieldComponents, and reduce the number of subclasses.


OutOfPlaneSymTensorIndex		ComponentIterator