Traverse a Lattice by cursor shape. More...

#include <LatticeStepper.h>

Inheritance diagram for casa::LatticeStepper:

Public Types
enum	hangOverPolicy { PAD, RESIZE }
	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. More...
Public Member Functions
	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.
	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.
	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.
	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.
virtual Bool	operator-- (int)
	Decrement operator (postfix version) - move the cursor backwards one step.
virtual void	reset ()
	Function to move the cursor to the beginning of the (sub)-Lattice.
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).
virtual IPosition	position () const
	Functions which return the current position of the beginning of the cursor.
virtual IPosition	relativePosition () const
virtual IPosition	endPosition () const
	Functions which return the current position of the end of the cursor.
virtual IPosition	relativeEndPosition () const
virtual IPosition	latticeShape () const
	Functions which return the shape of the Lattice being iterated through.
virtual IPosition	subLatticeShape () const
void	setCursorShape (const IPosition &cursorShape)
	Functions to change the cursor shape to a new one.
void	setCursorShape (const IPosition &cursorShape, const IPosition &cursorAxes)
virtual IPosition	cursorShape () const
	Function which returns the shape of the cursor.
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)
	Functions to specify a "section" of the Lattice to step over.
virtual void	subSection (const IPosition &blc, const IPosition &trc, const IPosition &inc)
virtual IPosition	blc () const
	Return the bottom left hand corner (blc), top right corner (trc) or step size (increment) used by the current sub-Lattice.
virtual IPosition	trc () const
virtual IPosition	increment () const
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.
virtual Bool	ok () const
	Function which checks the internal data of this class for correct dimensionality and consistant values.
virtual uInt	calcCacheSize (const IPosition &cubeShape, const IPosition &tileShape, uInt maxCacheSize, uInt bucketSize) const
	Calculate the cache size (in tiles) for this type of access to a lattice in the given row of the tiled hypercube.
Private Member Functions
	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.
Private Attributes
LatticeIndexer	itsIndexer
IPosition	itsCursorAxes
IPosition	itsCursorShape
IPosition	itsCursorPos
IPosition	itsAxisPath
uInt	itsNsteps
Bool	itsEnd
Bool	itsStart
Bool	itsNiceFit
Bool	itsHangover
uInt	itsPolicy

Detailed Description

Traverse a Lattice by cursor shape.

Intended use:

Public interface

Review Status

Reviewed By:: Peter Barnes
Date Reviewed:: 1999/10/30
Test programs:: tLatticeStepper

Prerequisite

LatticeNavigator

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.

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.
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.

Definition at line 267 of file LatticeStepper.h.

Member Enumeration Documentation

enum casa::LatticeStepper::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.

Enumerator:

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.

Definition at line 274 of file LatticeStepper.h.

Constructor & Destructor Documentation

casa::LatticeStepper::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 .

casa::LatticeStepper::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.

casa::LatticeStepper::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.

casa::LatticeStepper::LatticeStepper ( const LatticeStepper & other )

The copy constructor uses copy semantics.

casa::LatticeStepper::~LatticeStepper ( )

casa::LatticeStepper::LatticeStepper ( ) [private]

Prevent the default constructor from being used.

Member Function Documentation

virtual Bool casa::LatticeStepper::atEnd ( ) const [virtual]

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

virtual uInt casa::LatticeStepper::calcCacheSize	(	const IPosition &	cubeShape,
		const IPosition &	tileShape,
		uInt	maxCacheSize,
		uInt	bucketSize
	)		const `[virtual]`

void casa::LatticeStepper::setCursorShape	(	const IPosition &	cursorShape,
		const IPosition &	cursorAxes
	)

virtual void casa::LatticeStepper::subSection	(	const IPosition &	blc,
		const IPosition &	trc
	)		`[virtual]`

Public Types

Public Member Functions

Private Member Functions

Private Attributes