Arrays
[casa core modules (libcasa)]

---

Detailed Description

A module implementing multidimensional arrays and operations.

See below for an overview of the classes in this module.

Review Status

Reviewed By:

UNKNOWN

Date Reviewed:

before2004/08/25

Etymology

This module provides classes and global functions for multidimensional arrays.

Synopsis

Arrays have traditionally played an important role in scientific computation. While it is certainly true that some of the reliance on arrays was due to the paucity of other data structures in FORTRAN, it is also true that computation on arrays reflects the common occurrence of regularly sampled multi-dimensioned data in science.

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.

Modules
	Arrays_internal_classes
	Internal Arrays classes and functions.
Classes
class	casa::Array< T >
	template <class T, class U> class vector; A templated N-D Array class with zero origin Array<T> is a templated, N-dimensional, Array class. The origin is zero, but by default indices are zero-based. This Array class is the base class for specialized Vector<T>, Matrix<T>, and Cube<T> classes. More...
class	casa::ArrayAccessor< T, Axis< U > >
	Fast 1D accessor/iterator for nD array classes. More...
class	casa::ArrayAccessor_RT< T, AxisN >
	Specialization for run-time axes. More...
class	casa::ArrayBase
	Non-templated base class for templated Array class. More...
struct	casa::ArrayBase_global_functions_Array_general_global_functions
	General global functions for Arrays. More...
class	casa::ArrayError
	The base class for all Array exception classes. More...
class	casa::ArrayIndexError
	An error thrown when an index is out of range. More...
class	casa::ArrayConformanceError
	An error thrown when two arrays do not conform. More...
class	casa::ArrayNDimError
	Thrown when two arrays have different dimensionality. More...
class	casa::ArrayShapeError
	An error thrown when two arrays have different shapes. More...
class	casa::ArrayIteratorError
	An error thrown by an ArrayIterator. More...
class	casa::ArraySlicerError
	An error thrown by an Slicer member function. More...
struct	casa::ArrayIO_global_functions_Array_IO
	Input/output operators for Arrays. More...
struct	casa::ArrayIO_global_functions_Array_binary_IO
	Global functions to read/write binary arrays from/to a file. More...
struct	casa::ArrayIO_global_functions_Array_Ascii_IO
	Global functions for Matrix/Vector input/output using ASCII format. More...
class	casa::ArrayIterator< T >
	Iterate an Array cursor through another Array. More...
class	casa::ReadOnlyArrayIterator< T >
	Iterate a const Array cursor through a const Array. More...
struct	casa::ArrayLogical_global_functions_Array_logical_operations
	Logical operations for Arrays. More...
struct	casa::ArrayMath_global_functions_Array_mathematical_operations
	Mathematical operations for Arrays. More...
struct	casa::ArrayMath_global_functions_partialFuncHelper
	Helper function for partialX functions. More...
class	casa::ArrayPositionIterator
	Iterate an IPosition through the shape of an Array. More...
struct	casa::ArrayUtil_global_functions_stringToVector
	Split a String into its elements. More...
struct	casa::ArrayUtil_global_functions_concatenateArray
	Concatenate two Arrays. More...
struct	casa::ArrayUtil_global_functions_reorderArray
	Reorder the axes of an array. More...
class	casa::AxesSpecifier
	Specification of axes to keep or remove. More...
class	casa::Cube< T >
	A 3-D Specialization of the Array class. More...
class	casa::IPosition
	A Vector of integers, for indexing into Array<T> objects. More...
struct	casa::IPosition_global_functions_IPosition_Arithmetic
	Arithmetic Operations for IPosition's Element by element arithmetic on IPositions. More...
struct	casa::IPosition_global_functions_IPosition_Logical
	Logical operations for IPosition's Element by element boolean operations on IPositions. More...
struct	casa::IPosition_global_functions_IPosition_Indexing
	Indexing functions for IPosition's Convert between IPosition and offset in an array. More...
struct	casa::LogiArray_global_functions_LogicalArray
	Logical valued Arrays. More...
struct	casa::LogiArrayFwd_global_functions_LogicalArray_forwards
	Forward declarations for LogicalArrays. More...
struct	casa::LogiCube_global_functions_LogicalCube
	Logical valued Cubes. More...
struct	casa::LogiMatrix_global_functions_LogicalMatrix
	Logical valued Matrices. More...
struct	casa::LogiVector_global_functions_LogicalVector
	Logical valued Vectors. More...
struct	casa::MaskArrIO_global_functions_MaskedArray_IO
	Ascii input/output operations for MaskedArrays. More...
struct	casa::MaskArrLogi_global_functions_MaskedArray_logical_operations
	Logical operations for MaskedArrays, and between MaskedArrays and Arrays. More...
struct	casa::MaskArrMath_global_functions_MaskedArray_mathematical_operations
	Mathematical operations for MaskedArrays (and with Arrays). More...
class	casa::MaskedArray< T >
	Class for masking an Array for operations on that Array. More...
struct	casa::MaskedArray_global_functions_MaskedArray_general_global_functions
	General global functions for MaskedArrays, and MaskedArrays and Arrays. More...
struct	casa::MaskLogiArr_global_functions_MaskedLogicalArray
	Masked LogicalArrays. More...
struct	casa::MaskLogiArrFwd_global_functions_MaskedLogicalArray_forwards
	Forward declarations for MaskedLogicalArrays. More...
class	casa::Matrix< T >
	A 2-D Specialization of the Array class. More...
class	casa::MatrixIterator< T >
	Iterate a Matrix cursor through another Array. More...
class	casa::ReadOnlyMatrixIterator< T >
	Iterate a Matrix cursor through a R/O Array. More...
struct	casa::MatrixMath_global_functions_Linear_Algebra
	Linear algebra functions on Vectors and Matrices. More...
class	casa::Slice
	define a (start,length,increment) along an axis More...
class	casa::Slicer
	Specify which elements to extract from an n-dimensional array. More...
struct	casa::Slicer_global_functions_Slicer_IO
	IO functions for Slicer's . More...
class	casa::Vector< T >
	A 1-D Specialization of the Array class. More...
class	casa::VectorIterator< T >
	Iterate an Vector cursor through another Array. More...
class	casa::ReadOnlyVectorIterator< T >
	Iterate a Vector cursor through another Array. More...
class	casa::VectorSTLIterator< T >
	AIPS++ Vector iterator. More...
Enumerations
enum	casa::StorageInitPolicy
	A global enum used by some Array constructors. More...

---

Enumeration Type Documentation

enum casa::StorageInitPolicy

A global enum used by some Array constructors.

Synopsis

StorageInitPolicy is used in functions where an array is formed from a shape and an ordinary pointer. This enum should be in Array but that causes gcc to be unhappy.

Definition at line 46 of file ArrayBase.h.

---