Next: Utilities for Handling Cartesian Up: Some Functions and Methods Previous: Time Interval Handling Contents
Subsections

- Dimensions
- Matrix Class
- Matrix Sequences

## Matrix and Matrix Sequence handling

### Dimensions

In order to handle the dimensions of a matrix in a coherent manner a class `Dim` is defined. Objects of this class are used when constructing matrices and enquiring about their rank and index sizes.

  `Dim(i1, i2, i3...i` n)
  This constructor creates a Dim object with rank n, and each dimension given by i1, i2 etc respectively. e.g.

         #include "Qdos.h"
         Dim dVec(3);
         Dim dRotMatx(3,3);
         // sets up the dimension for a 3-vector and a 3x3 rotn matrix

  `size())`
  this method returns the number of elements in a matrix with this dimensionality, i.e.
  i1 * i2 * ... * in.
  e.g. `n_elems = dRotMatx.size();`
  In the above `n_elems` is 9 for a 3x3 Dim object.
  `rank())`
  this method returns the number of dimensions in a matrix with this dimensionality, i.e. n. e.g. `rank = dRotMatx.rank();`
  In the above `rank` is 2 for a 3x3 Dim object.
  `[]`
  The size of each index can be accessed by dereferencing using `[ ]`.

         #include "Qdos.h"
         Dim dRotMatx(3,3);
         iSize = dRotMatx[0];
         jSize = dRotMatx[1];
         for(i=0; i<iSize; i++)
           printf("\n", i, j);
           for (j=0; j<jSize; j++)
             printf("%d,%d  ", i, j);

  The above example prints
  0,0 0,1 0,2
  1,0 1,1 1,2
  2,0 2,1 2,2

### Matrix Class

Construction of a QdRMatrix object is achieved using a Dim object as first argument in the constructor. The elements in a QdRMatrix are all of type double.

  `QdRMatrix(const Dim &dim)`

         #include "Qdos.h"
         QdRMatrix_var Rmatx = new QdRMatrix (const Dim(3,3) );

  This example creates a var pointer to a 3x3 matrix (of doubles).

  `QdRMatrix( Dim &dim, double value)`
  creates a new QdRMatrix object with dimensions specified by the Dim object and all elements initialised to the value specified.

         #include "Qdos.h"
         QdRMatrix_var Rmatx = new QdRMatrix ( Dim(3,3), 0.0 );

  This example creates a var pointer to a 3x3 matrix and initialises all elements to the value 0.

  `[i1]...[in]`
  The elements of a matrix may be accessed directly by dereferencing using [ ].

        #include "Qdos.h"
        QdRMatrix_var mat = new QdRMatrix(Dim(10,5));
        QdRMatrix_var dif = new QdRMatrix(Dim(10));
        for(i=0; i<10; i++)
          (*dif)[i] = (*mat)[i][0] - (*mat)[i][4];

  Note we dereference the QdRMatrix_var pointer to the QdRMatrix using (*matrix) before accessing the elements using [n]. This example finds the difference between the last and first colums in a 10 x 5 matrix.

  `dimdata()`
  This method returns a dimension object of type Dim that describes the dimensionality of this QdRMatrix, e.g.

        #include "Qdos.h"
        QdRMatrix_var mat = QdRMatrix_var::narrow(obj);
        // handle 2D matrix iSize x kSize
        Dim mDim = mat->dimdata();

        if ( !mat.is_nil() && mDim.rank() != 2 ) {
          // handle 2D array
        }
        else{
          QplugAppendTextDisplay("Input object not a 2D Matrix\n");
          return QPLUG_FAILURE;

        }

  `dims()`
  This method returns an array with as many elements as the rank of the matrix, with the index size of each dimension as elements, e.g.

        #include "Qdos.h"
        QdRMatrix_var mat = QdRMatrix_var::narrow(obj);
        // handle 2D matrix iSize x kSize
        if ( !mat.is_nil() && (mat->dimdata()).rank() != 2 ) {
           iSize = (mat->dims())[0];
           kSize = (mat->dims())[1];

           double sumk[iSize];
           for(i=0; i<iSize; i++){
             sumk[i] = 0;
             for(k=0; k<kSize; k++)
               sumk[i] += mat[i][k];
          }
        }
        else{
          QplugAppendTextDisplay("Input object not a 2D Matrix\n");
          return QPLUG_FAILURE;

        }

  The above example finds the sizes of the two indices of a 2D matrix and them sums over the second index.
  `rank()`
  It is possible to access the rank of a matrix directly, without first getting the corresponding Dim object. For example, the line
  `if ( !mat.is_nil() && (mat->dimdata()).rank() != 2 ){`
  above could more simply be written
  `if ( !mat.is_nil() && mat->rank() != 2 ){`

### Matrix Sequences

A sequence of QdRMatrix objects is a QdRMatrixSeq, and this in turn may take a var pointer, QdRMatrixSeq_var.

  `QdRMatrixSeq()`
  This constructor returns an empty sequence of type QdRMatrixSeq_var.

        #include "Qdos.h"
        QdRMatrixSeq_var out_seq = new QdRMatrixSeq();

  The above example creates a new empty matrix sequence.

  `QdRMatrixSeq(int size, const Dim & dim)`
  This constructor returns a QdRMatrixSeq_var with `size` entries each of which is a QdRMatrix with dimensions given by the Dim object dim.

        #include "Qdos.h"
        QdRMatrixSeq_var in_seq = QdRMatrixSeq_var::narrow(dobj);
        int sz = in_seq->sequence_size();
        QdRMatrixSeq_var out_seq = new QdRMatrixSeq(sz, Dim(3));

  The above example creates a new sequence with the same number of entries as in_seq, but with dimension Dim(3).

  `[]`
  The QdRMatrix object at the i place in the sequence can be accessed using the simple dereference []. e.g.

        #include "Qdos.h"
        QdRMatrixSeq_var in_seq = QdRMatrixSeq_var::narrow(dobj);
        int sz = in_seq->sequence_size();
        QdRMatrixSeq_var out_seq = new QdRMatrixSeq();
        for (int i=0; i<sz; i++)
          if( UserTest(in_seq[i]) ) out_seq->push_back(in_seq[i]);

  The above example creates a new empty sequence and appends each QdRMatrix object from the input QdRMatrixSeq sequence that satisfies the user created function UserTest. The first [i] dereference on a QdRMatrixSeq_var accesses the QdRMatrix at index i, but subsequent sets of braces will extract the corresponding element inside the matrix, e.g.

        #include "Qdos.h"
        QdRMatrixSeq_var in_seq = QdRMatrixSeq_var::narrow(dobj);
        if( (in_seq[r]).rank() == 2){
          double val_ij = in_seq[r][i][j];
        }

  The above example sets val_ij equal to the value of the i,j element in the 2D array for the r matrix in the sequence (which corresponds to the r time tag in the attached TIME_TAGS xref). Note that the rank of a matrix is a property of each matrix and not the sequence (which MAY be inhomogeneous), so we access the r element of the sequence, `in_seq[r]`, before asking for the rank().

  Note that QdRMatrixSeq_var objects share the same generic methods as other QdObject_var objects and sequences, such as Factory::clone() and sequence_size(), etc.

Next: Utilities for Handling Cartesian Up: Some Functions and Methods Previous: Time Interval Handling Contents