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.

$\bullet$

Dim(i1, i2, i3...in)
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

$\bullet$

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.

$\bullet$

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.

$\bullet$

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

$\bullet$

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

$\bullet$

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.

$\bullet$

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

$\bullet$

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;

  }

$\bullet$

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.

$\bullet$

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.

$\bullet$

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.

$\bullet$

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

$\bullet$

[]
The QdRMatrix object at the i$^{th}$ 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$^{th}$ matrix in the sequence (which corresponds to the r$^{th}$ 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$^{th}$ 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.