Module Arrays

Description (classes)

Review Status

Reviewed By:

UNKNOWN

Date Reviewed:

before2004/08/25

Etymology

Synopsis

The Lattices are a generalization of Arrays. They can handle memory- and disk-based arrays as well as other types of arrays (eg. expressions).

The module consists of various parts:

• Array is the basic array class.

  Vector, Matrix, and Cube are the one, two, and three dimensional specializations respectively of Array.

• MaskedArray is the class used to mask an Array for operations on that Array.

• ArrayError is the base class for all Array exception classes.

• ArrayIterator can be used to iterate in a simple way through an Array. Note that LatticeIterator can be used on a ArrayLattice object for more advanced iteration.

• Mathematical, logical, IO, and other useful operations are provided for Arrays and MaskedArrays.

• Orthogonal n-space descriptors - useful when a shape of an Array is needed or when a sub-region within an Array is required.
  • The IPosition class name is a concatenation of "Integer Position." IPosition objects are normally used to index into, and define the shapes of, Arrays and Lattices. For example, if you have a 5-dimensional array, you need an IPosition of length 5 to index into the array (or to define its shape, etc.). It is essentially a vector of integers. The IPosition vector may point to the "top right corner" of some shape, or it may be an indicator of a specific position in n-space. The interpretation is context dependent. The constructor consists of an initial argument which specifies the number of axes, followed by the appropriate number of respective axis lengths. Thus the constructor needs N+1 arguments for an IPosition of length N. IPositions have the standard integer math relationships defined. The dimensionality of the operator arguments must be the same.

        // Make a shape with three axes, x = 24, y = 48, z = 16;
        IPosition threeSpace(3, 24, 48, 16);
        
        // get the value of the ith axis (note: C++ is zero based!)
        Int xShape = threeSpace(0);
        Int zShape = threeSpace(2);
        
        // construct another with all three axes values equal to 666;
        IPosition threeSpaceAlso(3,666);
        
        // do math with the IPositions...
        threeSpace += threeSpaceAlso;
        AlwaysAssert(threeSpace(1) == 714, AipsError);
        

  • The Slicer class name may be thought of as a short form of "n-Dimensional Slice Specifier." This object is used to bundle into one place all the information necessary to specify a regular subregion within an Array or Lattice. In other words, Slicer holds the location of a "slice" of a greater whole. Construction is with up to 3 IPositions: the start location of the subspace within the greater space; the shape or end location of the subspace within the greater space; and the stride, or multiplier to be used for each axis. The stride gives the user the chance to use every i-th piece of data, rather than every position on the axis.
    It is possible to leave some values in the given start or end/length unspecified. Such unspecified values default to the boundaries of the array to which the slicer will be applied. It is also possible to use a non-zero origin when applying the slicer to an array.

        // Define the shape of an array.
        IPosition shape(2,20,30);
        
        // Also define an origin.
        IPosition origin(2,-5,15);
        
        // Now define some Slicers, initially only specify the start
        // Its length and stride will be 1.
        Slicer ns0(IPosition(2,0,24));
        
        // make some IPositions as holders for the rest of the information
        IPosition blc,trc,inc;
        
        // Use the shape and origin to fill our holders assuming we want to use
        // as much of the Array as possible.
        ns0.inferShapeFromSource (shape, origin, blc,trc,inc);
        
        // print out the new info ie. blc=[5,9],trc=[5,9],inc=[1,1]
        cout << blc << trc << inc << endl;
        
        // Build a slicer with temporaries for arguments. The arguments are:
        // start position, end position and step increment. The Slicer::endIsLast
        // argument specifies that the end position is the trc. The alternative
        // is Slicer::endIsLength which specifies that the end argument is the
        // shape of the resulting subregion.
        //
        Slicer ns1(IPosition(2,3,5), IPosition(2,13,21), IPosition(2,3,2),
                   Slicer::endIsLast);
        IPosition shp = ns1.inferShapeFromSource (shape, blc,trc,inc);
        //
        // print out the new info ie. shp=[4,9],blc=[3,5],trc=[12,21],inc=[3,2]
        cout << shp << blc << trc << inc << endl;
        

  The detailed discussions for the classes and global functions will describe how to use them.

  ---

  Classes

  52 Linear Algebra -- Linear algebra functions on Vectors and Matrices. (full description)

  Array IO -- Input/output operators for Arrays. (full description)

  Array general global functions -- General global functions for Arrays. (full description)

  Array logical operations -- Logical operations for Arrays. (full description)

  Array mathematical operations -- Mathematical operations for Arrays. (full description)

  Array -- A templated N-D Array class with zero origin (full description)

  Array -- Global functions for Matrix/Vector input/output using ASCII format. (full description)

  ArrayAccessor -- Fast 1D accessor/iterator for nD array classes (full description)

  ArrayAccessor_RT -- Specialization for run-time axes (full description)

  ArrayBase -- Non-templated base class for templated Array class. (full description)

  ArrayBaseAccessor -- Axis independent base for the ArrayAccessor classes (full description)

  ArrayConformanceError -- An error thrown when two arrays do not conform (full description)

  ArrayError -- The base class for all Array exception classes. (full description)

  ArrayIndexError -- An error thrown when an index is out of range (full description)

  ArrayIterator -- Iterate an Array cursor through another Array. (full description)

  ArrayIteratorError -- An error thrown by an ArrayIterator (full description)

  ArrayNDimError -- Thrown when two arrays have different dimensionality (full description)

  ArrayPositionIterator -- Iterate an IPosition through the shape of an Array (full description)

  ArrayShapeError -- An error thrown when two arrays have different shapes (full description)

  ArraySlicerError -- An error thrown by an Slicer member function (full description)

  AxesMapping -- Info about mapping array axes to another order. (full description)

  AxesSpecifier -- Specification of axes to keep or remove (full description)

  Axis -- Class to enumerate compile-time axis numeration (full description)

  AxisN -- Class to specify run-time axis values (full description)

  Cube -- A 3-D Specialization of the Array class (full description)

  ExtendSpecifier -- Specification of new and stretched lattice axes (full description)

  IPosition Arithmetic -- Arithmetic Operations for IPosition's (full description)

  IPosition Indexing -- Indexing functions for IPosition's (full description)

  IPosition Logical -- Logical operations for IPosition's (full description)

  IPosition -- A Vector of integers, for indexing into Array objects. (full description)

  LogicalArray forwards -- Forward declarations for LogicalArrays. (full description)

  LogicalArray -- Logical valued Arrays. (full description)

  LogicalCube -- Logical valued Cubes. (full description)

  LogicalMatrix -- Logical valued Matrices. (full description)

  LogicalVector -- Logical valued Vectors. (full description)

  MaskedArray IO -- Ascii input/output operations for MaskedArrays. (full description)

  MaskedArray general global functions -- General global functions for MaskedArrays, and MaskedArrays and Arrays. (full description)

  MaskedArray logical operations -- Logical operations for MaskedArrays, and between MaskedArrays and Arrays. (full description)

  MaskedArray mathematical operations -- Mathematical operations for MaskedArrays (and with Arrays) (full description)

  MaskedArray -- Class for masking an Array for operations on that Array. (full description)

  MaskedLogicalArray forwards -- Forward declarations for MaskedLogicalArrays. (full description)

  MaskedLogicalArray -- Masked LogicalArrays. (full description)

  Matrix -- A 2-D Specialization of the Array class (full description)

  MatrixIterator -- Iterate a Matrix cursor through another Array. (full description)

  ReadOnlyArrayIterator -- Iterate a const Array cursor through a const Array. (full description)

  ReadOnlyMatrixIterator -- Iterate a Matrix cursor through a R/O Array. (full description)

  ReadOnlyVectorIterator -- Iterate a Vector cursor through another Array. (full description)

  Slice -- define a (start,length,increment) along an axis (full description)

  Slicer IO -- IO functions for Slicer's (full description)

  Slicer -- Specify which elements to extract from an n-dimensional array (full description)

  StorageInitPolicy -- A global enum used by some Array constructors. (full description)

  Vector -- A 1-D Specialization of the Array class (full description)

  VectorIterator -- Iterate an Vector cursor through another Array. (full description)

  VectorSTLIterator -- AIPS++ Vector iterator (full description)

  concatenateArray -- Concatenate two Arrays. (full description)

  partialFuncHelper -- Helper function for partialX functions (full description)

  reorderArray -- Reorder the axes of an array. (full description)

  reorderArrayHelper -- Helper function for function reorderArray.. (full description)

  stringToVector -- Split a String into its elements. (full description)