LatticeStepper.h

Classes

LatticeStepper -- Traverse a Lattice by cursor shape (full description)

class LatticeStepper: public LatticeNavigator

Types

enum hangOverPolicy

PAD
PAD is the default and means that the cursor size supplied by the user is kept fixed. But if the cursor overhangs the Lattice the part that overhangs is filled with a default value that is specified by the Iterator. Currently the default value is zero.
RESIZE
RESIZE means that the cursor shape is adjusted whenever it approaches the edges of the Lattice so that it is always the right size to include only the parts of the Lattice that are available. The user specified cursor shape now becomes the default and largest possible cursor shape.

Interface

Public Members
LatticeStepper (const IPosition& latticeShape, const IPosition& cursorShape, const uInt hangOverPolicy=PAD)
LatticeStepper (const IPosition& latticeShape, const IPosition& cursorShape, const IPosition& axisPath, const uInt hangOverPolicy=PAD)
LatticeStepper (const IPosition& latticeShape, const IPosition& cursorShape, const IPosition& cursorAxes, const IPosition& axisPath, const uInt hangOverPolicy=PAD)
LatticeStepper (const LatticeStepper& other)
~LatticeStepper()
LatticeStepper& operator= (const LatticeStepper& other)
virtual Bool operator++(int)
virtual Bool operator--(int)
virtual void reset()
virtual Bool atStart() const
virtual Bool atEnd() const
virtual uInt nsteps() const
virtual IPosition position() const
virtual IPosition relativePosition() const
virtual IPosition endPosition() const
virtual IPosition relativeEndPosition() const
virtual IPosition latticeShape() const
virtual IPosition subLatticeShape() const
void setCursorShape (const IPosition& cursorShape)
void setCursorShape (const IPosition& cursorShape, const IPosition& cursorAxes)
virtual IPosition cursorShape() const
virtual IPosition cursorAxes() const
virtual Bool hangOver() const
virtual void subSection (const IPosition& blc, const IPosition& trc)
virtual void subSection (const IPosition& blc, const IPosition& trc, const IPosition& inc)
virtual IPosition blc() const
virtual IPosition trc() const
virtual IPosition increment() const
virtual const IPosition& axisPath() const
virtual LatticeNavigator* clone() const
virtual Bool ok() const
Protected Members
virtual uInt calcCacheSize (const ROTiledStManAccessor&, uInt rowNumber) const
Private Members
LatticeStepper()
void padCursor()
Bool niceFit() const

Description

Review Status

Reviewed By:
Peter Barnes
Date Reviewed:
1999/10/30
Programs:
Tests:

Prerequisite

Etymology

LatticeStepper is so-called because it performs the calculations necessary to step through a Lattice. The next position is always one simple step forward from the current position. The step-size is calculated directly from the size of the LatticeIterator's cursor or window.

Synopsis

When you wish to traverse a Lattice (say, a PagedArray or an Image) you will usually create a LatticeIterator. Once created, you must attach a LatticeNavigator to the iterator. A LatticeStepper, is a concrete class derived from the abstract LatticeNavigator that allows you to move sequentially through the Lattice.

In constructing a LatticeStepper, you specify the Lattice shape and the shape of the "cursor" used to step through the data. The cursor position can be incremented or decremented to retrieve the next portion of the Lattice. The specified cursor shape can (and often will) have fewer dimensions that the Lattice itself. For example if we have a 4-dimensional Lattice with latticeShape = IPosition(4,64,64,4,16), then specifying a cursor of cursorShape = IPosition(1,64), will step through the hypercube row by row. When the cursor shape has fewer dimensions than the Lattice degenerate dimensions are added to the end of the cursor so that in the above example the specified cursor is assumed to mean cursorShape = IPosition(4,64,1,1,1). To access the data spectrum by spectrum (assuming the last axis is the spectral axis), you must use a 1-dimensional cursor of IPosition(4,1,1,1,16). The cursorShape function always returns a shape with as many dimensions as the underlying Lattice.

It is an error (and an exception will be thrown) if the cursor has more dimensions than the Lattice or if it is larger on any axis than the Lattice shape.
Also the cursor shape on all axes must be less than or equal to the Lattice shape on that axis. Otherwise an exception will be thrown.

In principle cursor axes with length 1 are degenerate axes. They are removed from the lattice cursor if the LatticeIterator cursor is accessed using e.g. the matrixCursor function. Using a special LatticeStepper constructor it is, however, possible to specify which cursor axes with length 1 have to be treated as normal axes. In that way one can be sure that a cursor is, for example, always 2D, even if an axis happens to have length 1.

    IPosition latticeShape(4,20,16,1,4);
    IPosition cursorAxes(2,1,2);
    IPosition cursorShape(2,16,1);
    IPosition axisPath;
    LatticeStepper stepper(latticeShape, cursorShape,
                           cursorAxes, axisPath);
    
This results in a cursor with shape [1,16,1,1]. The first and last axis are degenerate, so the cursor can also be accessed using matrixCursor (with shape [16,1]). Note that the cursor shape could also be specified as [1,16,1,1].

The "path" of the cursor through the Lattice can be controlled by specifying an axisPath during construction of the class. This is an IPosition which has exactly as many elements as the Lattice dimension. Each element must contain an integer between 0 -- Lattice_Dimension-1, and must be unique. For example,

    axisPath = IPosition(4,0,1,2,3) or
    axisPath = IPosition(4,3,1,2,0) 
    
are valid but
    axisPath = IPosition(4,1,2,3,4) or
    axisPath = IPosition(4,0,1,1,3) 
    
are not, given the latticeShape specified above. An exception is thrown if the AxisPath is bad.
The "axis path" defines which axis will be iterated through fastest as the cursor moves through the Lattice. With the above mentioned 4-dimensional Lattice and a single element cursor (cursorShape=IPosition(4,1,1,1,1)) setting an axisPath=IPosition(4,0,1,2,3) will move the cursor through all the columns, and then onto the next row, and again through all the columns in the second row. Once all the rows in the first plane have been exhausted the cursor will then iterate to the next plane, and eventually to the next spectral channel. If, however, the axisPath was axisPath=IPosition(4,3,0,1,2) then the cursor would iterate through each spectral channel first, before moving onto the next column in the first row.

The cursor never changes dimensionality as it traverses the Lattice. But it may change shape if the cursor shape is not a factor of the Lattice shape. A cursor shape is not a factor of the Lattice shape if the Lattice shape is not an integer multiple of the cursor shape on all axes. The integer multiplier need not to be the same for each axes. For example, for a Lattice of shape [10,10,10] a cursor of shape [8,5,2] is not a factor but one with a shape of [10,5,1] is.
When the cursor is not congruent with the Lattice moving the cursor through the Lattice will sometimes result in part of the cursor hanging over the edge of the Lattice. When this occurs the hangOver member function will return True. What to do in these situtations is specified by the hangOverPolicy enumerator.

  1. If the LatticeStepper::PAD option (the default) is used at construction time the cursor shape does not change. The parts of the cursor that hang over the edge of the Lattice are filled with a default value, usually zero, that is defined by the particular LatticeIterator used.
  2. If the LatticeStepper::RESIZE option is used at construction time the cursor shape does change to a smaller value when near the edge of the Lattice so that it is just big enough. For example with a Lattice shape of 10x10 and a cursor of 8x8 the cursor shape will initally be 8x8, then resize to 2x8 on the first step, then resize to 8x2 on the second step and finally resize to 2x2. The hangover function will return True for the last three steps, even though the cursor has resized.
The portion of the Lattice that the cursor will traverse can be restricted to a region defined by a top right corner, bottom left corner and a step size. This is done using the subSection function, which also resets the cursor position to the origin of the sub-Lattice. The cursor shape will remain unchanged. It is no error when the cursor shape exceeds the sub-Lattice shape (instead it is a hangover state).
If a sub-Lattice is defined then cursor positions relative to the sub-Lattice origins can be obtained using the relativePosition function rather than the position function, which always returns positions relative to the origin of the main Lattice.
To change the size of the sub-Lattice simply call the subSection function again with a different trc, blc & inc. This first clears the old sub-Lattice, then imposes the newly specified one, and finally moves the cursor to the origin of the new sub-Lattice.

Example

This example is of a global function that will iterate through a 4-dimensional Lattice. It is assumed that the axes are RA, Dec, Stokes & Frequency, and it will calculate the average flux in the I polarization on each frequency channel. Imagine it is passed a data set (ie. Lattice) of size 256 x 256 x 4 x 1024. This corresponds to 1GByte of data. However the iterator will page through this data using a cursor of size 256 x 256 (or 256kByte) and will only read (because of subsectioning) the relevant quarter of the data set. It is usually a good idea to set up the axis path as this is gives hints to data cache about which data to retrieve in advance.
    void averageFluxByChannel(const Lattice<Float>& data)
    {
      // for convenience, get the shape into a local variable
      IPosition latticeShape = data.shape();
      cout << "Data has shape: " << latticeShape << endl;
    
      // check that the data has 4 axes.
      DebugAssert(latticeShape.nelements() == 4, AipsError); 
        
      // specify the cursor, or window shape.  Here the cursor is a matrix 
      // that is the shape of the first plane of our Lattice.
      // For convenience, get the first two axis lengths into local vars
      uInt nCols = latticeShape(0);
      uInt nRows = latticeShape(1);
      IPosition cursorShape(2, nCols, nRows);
    
      // construct a stepper, which needs to know the shape of the lattice
      // and the shape of the iterator's cursor. By using cursorShape, which
      // is directly determined by the lattice's shape, we can be sure
      // that the cursor is a factor of the lattice, and thus that
      // all elements will be picked up efficiently during the traversal.
      // Because we will not be iterating through the stokes axis this axis
      // is made the slowest moving one. 
      IPosition axisPath(4, 0, 1, 3, 2)
      LatticeStepper stepper(latticeShape, cursorShape, axisPath);
    
      // Subsection the stepper so that it only iterates through the I
      // Stokes parameter (assumed to be when the third axis is zero)
      uInt nFreqs = latticeShape(3);
      IPosition blc(4, 0, 0, 0, 0), trc(4, nCols-1, nRows-1, 0, nFreqs-1);
      stepper.subSection(blc, trc);
     
      // construct the iterator.  Since we only want to read the Data,
      // use the read-only class, which disallows writing back to the cursor
      // (and hence is more efficient).
      RO_LatticeIterator<Float> iterator(data, stepper);
    
      Vector<Float> spectrum(nFreqs);
      spectrum = 0.0;
      uInt channel = 0;
      for (iterator.reset(); !iterator.atEnd(); iterator++) {
        const Matrix<Float>& cursor = iterator.matrixCursor();
        for (uInt col = 0; col < nCols; col++) {
          for (uInt row = 0; row < nRows; row++) {
            spectrum(channel) += cursor(col, row);
          }
        }
        channel++;
      } // for iterator
      cout << "Average spectrum is: " 
           << spectrum / cursorShape.product() << endl;
    }
    

Motivation

Moving through a Lattice by equal sized chunks, and without regard to the nature of the data, is a basic and common procedure.

Member Description

enum hangOverPolicy

The hangOverPolicy enumerator is used in the constructors to indicate what this class should do when the cursor shape hangs over the edge of the Lattice.

LatticeStepper (const IPosition& latticeShape, const IPosition& cursorShape, const uInt hangOverPolicy=PAD)

The first argument is the shape of the Lattice to be iterated and the second argument is the shape of the cursor. The cursor will increment initially along first axis, then the second and then the third (ie. axisPath = IPosition(ndim,0,1,2,...)) The dimensionality of the cursorShape can be less than the dimensionality of the lattice. It will be padded with 1s.
The cursorShape axes with length > 1 are seen as the true cursor axes. The other axes are degenerated and are removed by the functions vectorCursor(), etc., in class (RO_)LatticeIterator.

LatticeStepper (const IPosition& latticeShape, const IPosition& cursorShape, const IPosition& axisPath, const uInt hangOverPolicy=PAD)

Same as the above constructor except that the axis path is explicitly specified. The axis path is described in the synopsis above.

LatticeStepper (const IPosition& latticeShape, const IPosition& cursorShape, const IPosition& cursorAxes, const IPosition& axisPath, const uInt hangOverPolicy=PAD)

Same as the above constructor except that the cursor axes are explicitly specified. This can be useful to avoid that cursor axes with length=1 are treated as degenerated axes by the Iterator classes. The following rules have to be obeyed:
- cursorAxes.nelements() <= latticeShape.nelements()
- cursorShape.nelements() == latticeShape.nelements()
or cursorShape.nelements() == cursorAxes.nelements() The latter means that the cursorShape contains the axes mentioned in cursorAxes.
See also the example in the synopsis.

LatticeStepper (const LatticeStepper& other)

The copy constructor uses copy semantics.

~LatticeStepper()

LatticeStepper& operator= (const LatticeStepper& other)

The assignment operator uses copy semantics.

virtual Bool operator++(int)

Increment operator (postfix version) - move the cursor forward one step. Returns True if the cursor was moved.

virtual Bool operator--(int)

Decrement operator (postfix version) - move the cursor backwards one step. Returns True if the cursor was moved.

virtual void reset()

Function to move the cursor to the beginning of the (sub)-Lattice. Also resets the number of steps (nsteps function) to zero.

virtual Bool atStart() const

Function which returns "True" if the cursor is at the beginning of the (sub)-Lattice, otherwise, returns "False"

virtual Bool atEnd() const

Function which returns "True" if an attempt has been made to increment the cursor beyond the end of the (sub)-Lattice.

virtual uInt nsteps() const

Function to return the number of steps (increments & decrements) taken since construction (or since last reset). This is a running count of all cursor movement (operator++ or operator--), even though N-increments followed by N-decrements will ALWAYS leave the cursor in the original position.

virtual IPosition position() const
virtual IPosition relativePosition() const

Functions which return the current position of the beginning of the cursor. The position function is relative to the origin in the main Lattice and the relativePosition function is relative to the origin and increment used in the sub-Lattice (defined using the subSection function). If no sub-Lattice is defined the two functions return identical positions.

virtual IPosition endPosition() const
virtual IPosition relativeEndPosition() const

Functions which return the current position of the end of the cursor. The endPosition function is relative to the origin in the main Lattice and the relativeEndPosition function is relative to the origin and increment used in the sub-Lattice (defined using the subSection function). If no sub-Lattice is defined the two functions return identical positions.

Caution It returns the end position in the lattice and does not take overhang into account.

virtual IPosition latticeShape() const
virtual IPosition subLatticeShape() const

Functions which return the shape of the Lattice being iterated through. latticeShape always returns the shape of the main Lattice while subLatticeShape returns the shape of any sub-Lattice defined using the subSection function.

void setCursorShape (const IPosition& cursorShape)
void setCursorShape (const IPosition& cursorShape, const IPosition& cursorAxes)

Functions to change the cursor shape to a new one. They always reset the cursor to the beginning of the Lattice (and reset the number of steps to zero).

virtual IPosition cursorShape() const

Function which returns the shape of the cursor. This always includes all axes (ie. it includes degenerates axes)

virtual IPosition cursorAxes() const

Function which returns the axes of the cursor.

virtual Bool hangOver() const

Function which returns "True" if the increment/decrement operators have moved the cursor position such that part of the cursor beginning or end is hanging over the edge of the (sub)-Lattice.

virtual void subSection (const IPosition& blc, const IPosition& trc)
virtual void subSection (const IPosition& blc, const IPosition& trc, const IPosition& inc)

Functions to specify a "section" of the Lattice to step over. A section is defined in terms of the Bottom Left Corner (blc), Top Right Corner (trc), and step size (inc), on ALL of its axes, including degenerate axes. The step size defaults to one if not specified.

virtual IPosition blc() const
virtual IPosition trc() const
virtual IPosition increment() const

Return the bottom left hand corner (blc), top right corner (trc) or step size (increment) used by the current sub-Lattice. If no sub-Lattice has been defined (with the subSection function) these functions return blc=0, trc=latticeShape-1, increment=1, ie. the entire Lattice.

virtual const IPosition& axisPath() const

Return the axis path.

virtual LatticeNavigator* clone() const

Function which returns a pointer to dynamic memory of an exact copy of this instance. The pointer returned by this function must be deleted externally.

virtual Bool ok() const

Function which checks the internal data of this class for correct dimensionality and consistant values. Returns True if everything is fine otherwise returns False

virtual uInt calcCacheSize (const ROTiledStManAccessor&, uInt rowNumber) const

Calculate the cache size (in tiles) for this type of access to a lattice in the given row of the tiled hypercube.

LatticeStepper()

Prevent the default constructor from being used.

void padCursor()

Pad the cursor to the right number of dimensions.

Bool niceFit() const

Check if the cursor shape is a factor of the Lattice shape.