casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Public Member Functions | Protected Member Functions | Private Member Functions | Private Attributes
casa::Matrix< T > Class Template Reference

A 2-D Specialization of the Array class. More...

#include <Matrix.h>

Inheritance diagram for casa::Matrix< T >:
casa::Array< T > casa::ArrayBase

List of all members.

Public Member Functions

 Matrix ()
 A Matrix of length zero in each dimension; zero origin.
 Matrix (uInt l1, uInt l2)
 A Matrix with "l1" rows and "l2" columns.
 Matrix (uInt l1, uInt l2, const T &initialValue)
 A Matrix with "l1" rows and "l2" columns.
 Matrix (const IPosition &len)
 A matrix of shape with shape "len".
 Matrix (const IPosition &len, const T &initialValue)
 A matrix of shape with shape "len".
 Matrix (const Matrix< T > &other)
 The copy constructor uses reference semantics.
 Matrix (const Array< T > &other)
 Construct a Matrix by reference from "other".
 Matrix (const IPosition &shape, T *storage, StorageInitPolicy policy=COPY)
 Create an Matrix of a given shape from a pointer.
 Matrix (const IPosition &shape, const T *storage)
 Create an Matrix of a given shape from a pointer.
virtual ~Matrix ()
 Define a destructor, otherwise the (SUN) compiler makes a static one.
virtual void assign (const Array< T > &other)
 Assign the other array (which must be dimension 2) to this matrix.
virtual void reference (const Array< T > &other)
 Make this matrix a reference to other.
void resize (uInt nx, uInt ny, Bool copyValues=False)
 Resize to the given shape (must be 2-dimensional).
virtual void resize ()
 Make this array a different shape.
virtual void resize (const IPosition &newShape, Bool copyValues=False)
Matrix< T > & operator= (const Matrix< T > &other)
 Copy the values from other to this Matrix.
virtual Array< T > & operator= (const Array< T > &other)
 Copy the values in other to this.
Array< T > & operator= (const T &val)
 Copy val into every element of this Matrix; i.e.
Matrix< T > & operator= (const MaskedArray< T > &marray)
 Copy to this those values in marray whose corresponding elements in marray's mask are True.
T & operator() (const IPosition &i)
 Single-pixel addressing.
const T & operator() (const IPosition &i) const
T & operator() (uInt i1, uInt i2)
const T & operator() (uInt i1, uInt i2) const
MaskedArray< T > operator() (const LogicalArray &mask) const
 The array is masked by the input LogicalArray.
MaskedArray< T > operator() (const LogicalArray &mask)
 Return a MaskedArray.
MaskedArray< T > operator() (const MaskedLogicalArray &mask) const
 The array is masked by the input MaskedLogicalArray.
MaskedArray< T > operator() (const MaskedLogicalArray &mask)
 Return a MaskedArray.
Vector< T > row (uInt i)
 Returns a reference to the i'th row.
const Vector< T > row (uInt i) const
Vector< T > column (uInt j)
 Returns a reference to the j'th column.
const Vector< T > column (uInt j) const
Vector< T > diagonal ()
 Returns a diagonal from the Matrix.
const Vector< T > diagonal () const
Vector< T > diagonal (Int n)
 n==0 is the main diagonal.
const Vector< T > diagonal (Int n) const
Matrix< T > operator() (const Slice &sliceX, const Slice &sliceY)
 Take a slice of this matrix.
const Matrix< T > operator() (const Slice &sliceX, const Slice &sliceY) const
Array< T > operator() (const IPosition &blc, const IPosition &trc, const IPosition &incr)
 Slice using IPositions.
const Array< T > operator() (const IPosition &blc, const IPosition &trc, const IPosition &incr) const
Array< T > operator() (const IPosition &blc, const IPosition &trc)
 Get a reference to an array section extending from start to end (inclusive).
const Array< T > operator() (const IPosition &blc, const IPosition &trc) const
Array< T > operator() (const Slicer &slicer)
 Get a reference to an array section using a Slicer.
const Array< T > operator() (const Slicer &slicer) const
void shape (Int &s1, Int &s2) const
 The length of each axis of the Matrix.
const IPosition & shape () const
 The length of each axis.
uInt nrow () const
 The number of rows in the Matrix, i.e.
uInt ncolumn () const
 The number of columns in the Matrix, i.e.
virtual void takeStorage (const IPosition &shape, T *storage, StorageInitPolicy policy=COPY)
 Replace the data values with those in the pointer storage.
virtual void takeStorage (const IPosition &shape, const T *storage)
 Since the pointer is const, a copy is always taken.
virtual Bool ok () const
 Checks that the Matrix is consistent (invariants check out).

Protected Member Functions

virtual void doNonDegenerate (const Array< T > &other, const IPosition &ignoreAxes)
 Remove the degenerate axes from other and store result in this matrix.

Private Member Functions

void makeIndexingConstants ()
 Helper fn to calculate the indexing constants.

Private Attributes

Int xinc_p
 Cached constants to improve indexing.
Int yinc_p

Detailed Description

template<class T>
class casa::Matrix< T >

A 2-D Specialization of the Array class.

Review Status

Reviewed By:
UNKNOWN
Date Reviewed:
before2004/08/25
Matrix objects are two-dimensional specializations (e.g., more convenient
and efficient indexing) of the general Array class. You might also want
to look at the Array documentation to see inherited functionality. A
tutorial on using the array classes in general is available in the
"AIPS++ Programming Manual".

Generally the member functions of Array are also available in
Matrix versions which take a pair of integers where the array 
needs an IPosition. Since the Matrix
is two-dimensional, the IPositions are overkill, although you may
use those versions if you want to.

    Matrix<Int> mi(100,100);  // Shape is 100x100
    mi.resize(50,50);         // Shape now 50x50

Slices may be taken with the Slice class. To take a slice, one "indexes" with one Slice(start, length, inc) for each axis, where end and inc are optional. Additionally, there are row(), column() and diagonal() member functions which return Vector's which refer to the storage back in the Matrix: 

    Matrix<Float> mf(100, 100);
    mf.diagonal() = 1;

Correct indexing order of a matrix is: 

    Matrix<Int> mi(n1,n2)                  // [nrow, ncolumn]
    for (uInt j=0; j<mi.ncolumn(); j++) {
       for (uInt i=0; i<mi.nrow(); i++) {
          mi(i,j) = i*j;
       }      
    }

Element-by-element arithmetic and logical operations are available (in aips/ArrayMath.h and aips/ArrayLogical.h). Other Matrix operations (e.g. LU decomposition) are available, and more appear periodically.

As with the Arrays, if the preprocessor symbol AIPS_DEBUG is defined at compile time invariants will be checked on entry to most member functions. Additionally, if AIPS_ARRAY_INDEX_CHECK is defined index operations will be bounds-checked. Neither of these should be defined for production code.

Definition at line 93 of file Matrix.h.

Constructor & Destructor Documentation

template<class T>
casa::Matrix< T >::Matrix ( )

A Matrix of length zero in each dimension; zero origin.

template<class T>
casa::Matrix< T >::Matrix ( uInt  l1,
uInt  l2 
)

A Matrix with "l1" rows and "l2" columns.

template<class T>
casa::Matrix< T >::Matrix ( uInt  l1,
uInt  l2,
const T &  initialValue 
)

A Matrix with "l1" rows and "l2" columns.

Fill it with the initial value.

template<class T>
casa::Matrix< T >::Matrix ( const IPosition &  len)

A matrix of shape with shape "len".

template<class T>
casa::Matrix< T >::Matrix ( const IPosition &  len,
const T &  initialValue 
)

A matrix of shape with shape "len".

Fill it with the initial value.

template<class T>
casa::Matrix< T >::Matrix ( const Matrix< T > &  other)

The copy constructor uses reference semantics.

template<class T>
casa::Matrix< T >::Matrix ( const Array< T > &  other)

Construct a Matrix by reference from "other".

"other must have ndim() of 2 or less.

template<class T>
casa::Matrix< T >::Matrix ( const IPosition &  shape,
T *  storage,
StorageInitPolicy  policy = COPY 
)

Create an Matrix of a given shape from a pointer.

template<class T>
casa::Matrix< T >::Matrix ( const IPosition &  shape,
const T *  storage 
)

Create an Matrix of a given shape from a pointer.

Because the pointer is const, a copy is always made.

template<class T>
virtual casa::Matrix< T >::~Matrix ( ) [virtual]

Define a destructor, otherwise the (SUN) compiler makes a static one.

Member Function Documentation

template<class T>
virtual void casa::Matrix< T >::assign ( const Array< T > &  other) [virtual]

Assign the other array (which must be dimension 2) to this matrix.

If the shapes mismatch, this array is resized.

Reimplemented from casa::Array< T >.

Referenced by casa::VisibilityResampler::setFreqMaps(), and casa::ConvolutionFunction::setSpwFreqSelection().

template<class T>
Vector<T> casa::Matrix< T >::column ( uInt  j)

Returns a reference to the j'th column.

Referenced by casa::PixelCanvas::drawColoredPoints().

template<class T>
const Vector<T> casa::Matrix< T >::column ( uInt  j) const
template<class T>
Vector<T> casa::Matrix< T >::diagonal ( ) [inline]

Returns a diagonal from the Matrix.

The Matrix must be square.

Definition at line 247 of file Matrix.h.

Referenced by casa::Matrix< uInt >::diagonal().

template<class T>
const Vector<T> casa::Matrix< T >::diagonal ( ) const [inline]

Definition at line 253 of file Matrix.h.

Referenced by casa::Matrix< uInt >::diagonal().

template<class T>
Vector<T> casa::Matrix< T >::diagonal ( Int  n)

n==0 is the main diagonal.

n>0 is above the main diagonal, n<0 is below it.

template<class T>
const Vector<T> casa::Matrix< T >::diagonal ( Int  n) const
template<class T>
virtual void casa::Matrix< T >::doNonDegenerate ( const Array< T > &  other,
const IPosition &  ignoreAxes 
) [protected, virtual]

Remove the degenerate axes from other and store result in this matrix.

An exception is thrown if removing degenerate axes does not result in a matrix.

Reimplemented from casa::Array< T >.

template<class T>
void casa::Matrix< T >::makeIndexingConstants ( ) [private]

Helper fn to calculate the indexing constants.

template<class T>
uInt casa::Matrix< T >::ncolumn ( ) const [inline]

The number of columns in the Matrix, i.e.

the length of the 2nd axis.

Definition at line 311 of file Matrix.h.

Referenced by casa::PlotRasterMatrixData< T >::PlotRasterMatrixData().

template<class T>
uInt casa::Matrix< T >::nrow ( ) const [inline]

The number of rows in the Matrix, i.e.

the length of the first axis.

Definition at line 307 of file Matrix.h.

Referenced by casa::PlotRasterMatrixData< T >::PlotRasterMatrixData().

template<class T>
virtual Bool casa::Matrix< T >::ok ( ) const [virtual]

Checks that the Matrix is consistent (invariants check out).

Reimplemented from casa::Array< T >.

template<class T>
T& casa::Matrix< T >::operator() ( const IPosition &  i) [inline]

Single-pixel addressing.

If AIPS_ARRAY_INDEX_CHECK is defined, bounds checking is performed.

Reimplemented from casa::Array< T >.

Definition at line 169 of file Matrix.h.

Referenced by casa::Matrix< uInt >::operator()().

template<class T>
const T& casa::Matrix< T >::operator() ( const IPosition &  i) const [inline]

Reimplemented from casa::Array< T >.

Definition at line 171 of file Matrix.h.

template<class T>
T& casa::Matrix< T >::operator() ( uInt  i1,
uInt  i2 
) [inline]

Definition at line 173 of file Matrix.h.

template<class T>
const T& casa::Matrix< T >::operator() ( uInt  i1,
uInt  i2 
) const [inline]

Definition at line 182 of file Matrix.h.

template<class T>
MaskedArray<T> casa::Matrix< T >::operator() ( const LogicalArray &  mask) const [inline]

The array is masked by the input LogicalArray.

This mask must conform to the array.

Return a MaskedArray.

Reimplemented from casa::Array< T >.

Definition at line 198 of file Matrix.h.

template<class T>
MaskedArray<T> casa::Matrix< T >::operator() ( const LogicalArray &  mask) [inline]

Return a MaskedArray.

Reimplemented from casa::Array< T >.

Definition at line 202 of file Matrix.h.

template<class T>
MaskedArray<T> casa::Matrix< T >::operator() ( const MaskedLogicalArray &  mask) const [inline]

The array is masked by the input MaskedLogicalArray.

The mask is effectively the AND of the internal LogicalArray and the internal mask of the MaskedLogicalArray. The MaskedLogicalArray must conform to the array.

Return a MaskedArray.

Reimplemented from casa::Array< T >.

Definition at line 215 of file Matrix.h.

template<class T>
MaskedArray<T> casa::Matrix< T >::operator() ( const MaskedLogicalArray &  mask) [inline]

Return a MaskedArray.

Reimplemented from casa::Array< T >.

Definition at line 219 of file Matrix.h.

template<class T>
Matrix<T> casa::Matrix< T >::operator() ( const Slice &  sliceX,
const Slice &  sliceY 
)

Take a slice of this matrix.

Slices are always indexed starting at zero. This uses reference semantics, i.e. changing a value in the slice changes the original. 

        Matrix<Double> vd(100,100);
        //..\.
        vd(Slice(0,10),Slice(10,10)) = -1.0; // 10x10 sub-matrix set to -1.0
template<class T>
const Matrix<T> casa::Matrix< T >::operator() ( const Slice &  sliceX,
const Slice &  sliceY 
) const
template<class T>
Array<T> casa::Matrix< T >::operator() ( const IPosition &  blc,
const IPosition &  trc,
const IPosition &  incr 
) [inline]

Slice using IPositions.

Required to be defined, otherwise the base class versions are hidden.

Reimplemented from casa::Array< T >.

Definition at line 282 of file Matrix.h.

template<class T>
const Array<T> casa::Matrix< T >::operator() ( const IPosition &  blc,
const IPosition &  trc,
const IPosition &  incr 
) const [inline]

Reimplemented from casa::Array< T >.

Definition at line 285 of file Matrix.h.

template<class T>
Array<T> casa::Matrix< T >::operator() ( const IPosition &  start,
const IPosition &  end 
) [inline]

Get a reference to an array section extending from start to end (inclusive).

Reimplemented from casa::Array< T >.

Definition at line 288 of file Matrix.h.

template<class T>
const Array<T> casa::Matrix< T >::operator() ( const IPosition &  blc,
const IPosition &  trc 
) const [inline]

Reimplemented from casa::Array< T >.

Definition at line 290 of file Matrix.h.

template<class T>
Array<T> casa::Matrix< T >::operator() ( const Slicer &  ) [inline]

Get a reference to an array section using a Slicer.

Reimplemented from casa::Array< T >.

Definition at line 292 of file Matrix.h.

template<class T>
const Array<T> casa::Matrix< T >::operator() ( const Slicer &  slicer) const [inline]

Reimplemented from casa::Array< T >.

Definition at line 294 of file Matrix.h.

template<class T>
Matrix<T>& casa::Matrix< T >::operator= ( const Matrix< T > &  other)

Copy the values from other to this Matrix.

If this matrix has zero elements then it will resize to be the same shape as other; otherwise other must conform to this. Note that the assign function can be used to assign a non-conforming matrix.

Referenced by casa::Matrix< uInt >::operator=().

template<class T>
virtual Array<T>& casa::Matrix< T >::operator= ( const Array< T > &  other) [virtual]

Copy the values in other to this.

If the array on the left hand side has no elements, then it is resized to be the same size as as the array on the right hand side. Otherwise, the arrays must conform (same shapes). 

        IPosition shape(2,10,10);     // some shape
        Array<Double> ad(shape);
        //..\.
        Array<Double> ad2;            // N.B. ad2.nelements() == 0
        ad2 = ad;                     // ad2 resizes, then elements
                                      //     are copied.
        shape = 20;
        Array<Double> ad3(shape);
        ad3 = ad;                     // Error: arrays do not conform

Note that the assign function can be used to assign a non-conforming array.

Reimplemented from casa::Array< T >.

template<class T>
Array<T>& casa::Matrix< T >::operator= ( const T &  val) [inline]

Copy val into every element of this Matrix; i.e.

behaves as if val were a constant conformant matrix.

Reimplemented from casa::Array< T >.

Definition at line 157 of file Matrix.h.

template<class T>
Matrix<T>& casa::Matrix< T >::operator= ( const MaskedArray< T > &  marray) [inline]

Copy to this those values in marray whose corresponding elements in marray's mask are True.

Reimplemented from casa::Array< T >.

Definition at line 162 of file Matrix.h.

template<class T>
virtual void casa::Matrix< T >::reference ( const Array< T > &  other) [virtual]

Make this matrix a reference to other.

Other must be of dimensionality 2 or less.

Reimplemented from casa::Array< T >.

Referenced by casa::VBStore::reference().

template<class T>
void casa::Matrix< T >::resize ( uInt  nx,
uInt  ny,
Bool  copyValues = False 
)

Resize to the given shape (must be 2-dimensional).

Resize without argument is equal to resize(0,0).

Referenced by ASDM_TABLE_BASE::_2CASAString2D(), ASDM_TABLE_BASE::at2CASA2D(), ASDM_TABLE_BASE::ati2CASA2D(), ASDM_TABLE_BASE::basic2CASA2D(), casa::WorldCanvas::ColorIndexedImage_::clear(), ASDM_TABLE_BASE::enum2CASA2D(), ASDM_TABLE_BASE::ext2CASA2D(), ASDM_TABLE_BASE::interval2CASA2D(), casa::MSUvDistParse::reset(), casa::MSSpwParse::reset(), and casa::MSTimeParse::reset().

template<class T>
virtual void casa::Matrix< T >::resize ( ) [virtual]

Make this array a different shape.

If copyValues==True the old values are copied over to the new array. Copying is done on a per axis basis, thus a subsection with the minimum of the old and new shape is copied.
Resize without argument is equal to resize(IPosition()).
It is important to note that if multiple Array objects reference the same data storage, this Array object still references the same data storage as the other Array objects if the shape does not change. Otherwise this Array object references newly allocated storage, while the other Array objects still reference the existing data storage.
If you want to be sure that the data storage of this Array object is not referenced by other Array objects, the function unique should be called first.

Reimplemented from casa::Array< T >.

template<class T>
virtual void casa::Matrix< T >::resize ( const IPosition &  newShape,
Bool  copyValues = False 
) [virtual]

Reimplemented from casa::Array< T >.

template<class T>
Vector<T> casa::Matrix< T >::row ( uInt  i)

Returns a reference to the i'th row.

template<class T>
const Vector<T> casa::Matrix< T >::row ( uInt  i) const
template<class T>
void casa::Matrix< T >::shape ( Int &  s1,
Int &  s2 
) const [inline]

The length of each axis of the Matrix.

Definition at line 300 of file Matrix.h.

Referenced by casa::WorldCanvas::ColorIndexedImage_::maskValid(), casa::PlotRasterMatrixData< T >::PlotRasterMatrixData(), and casa::vi::VisBuffer2Adapter::uvw().

template<class T>
const IPosition& casa::Matrix< T >::shape ( ) const [inline]

The length of each axis.

Reimplemented from casa::ArrayBase.

Definition at line 302 of file Matrix.h.

template<class T>
virtual void casa::Matrix< T >::takeStorage ( const IPosition &  shape,
T *  storage,
StorageInitPolicy  policy = COPY 
) [virtual]

Replace the data values with those in the pointer storage.

The results are undefined is storage does not point at nelements() or more data elements. After takeStorage() is called, unique() is True.

Reimplemented from casa::Array< T >.

template<class T>
virtual void casa::Matrix< T >::takeStorage ( const IPosition &  shape,
const T *  storage 
) [virtual]

Since the pointer is const, a copy is always taken.

Reimplemented from casa::Array< T >.

Member Data Documentation

template<class T>
Int casa::Matrix< T >::xinc_p [private]

Cached constants to improve indexing.

Definition at line 337 of file Matrix.h.

Referenced by casa::Matrix< uInt >::operator()().

template<class T>
Int casa::Matrix< T >::yinc_p [private]

Definition at line 337 of file Matrix.h.

Referenced by casa::Matrix< uInt >::operator()().

The documentation for this class was generated from the following file:
Generated on Sat May 4 2013 15:46:26 for casa by   doxygen 1.8.0