• 4.4.1 Design philosophy
• 4.4.2 The PtMatrix class
• 4.4.3 Public functions and operators for the PtMatrix class
  • Functions and Operators to access entries of the Matrix:
  • Constructors:
  • Comparison operators:
  • Conversion operators:
  • Destructive replacement operators:
  • Non-destructive operators (these return a new matrix):
  • Non-member binary operators:
  • Miscellaneous functions:
• 4.4.4 Writing stars and programs using the PtMatrix class
  • Memory management
  • Naming conventions
  • Include files
  • Input portholes
  • Allowing delays on inputs
  • Matrix outputs
• 4.4.5 Future extensions

4.4.1 Design philosophy

The Ptolemy PtMatrix class stores data as a simple C array, and therefore uses row-major ordering. Row-major ordering also seems more natural for operations such as image and video processing, but it might make it more difficult to interface Ptolemy's PtMatrix class with Fortran library calls. The limits of interfacing Ptolemy's PtMatrix class with other software is discussed in Section 4.4.5 on page 4-33.

The design decision to store data entries in a C array rather than as an array of vector objects has a greater effect on performance than the decision whether to use row major or column major ordering. There are a couple of advantages to implementing a matrix class as an array of vector class objects: referencing an entry may be faster, and it is easier to do operations on a whole row or column of the matrix, depending on whether the format is an array of column vectors or an array of row vectors. An entry lookup in an array of row vectors requires two index lookups: one to find the desired row vector in the array and one to find the desired entry of that row. A linear array, in contrast, requires a multiplication to find the location of first element of the desired row and then an index lookup to find the column in that row. For example, A[row][col] is equivalent to looking up &data + (row*numRows + col) if the entries are stored in a C array data[], whereas it is *(&rowArray + row) + col if looking up the entry in an array of vectors format.

Although the array of vectors format has faster lookups, it is also more expensive to create and delete the matrix. Each vector of the array must be created in the matrix constructor, and each vector must also be deleted by the matrix destructor. The array of vectors format also requires more memory to store the data and the extra array of vectors.

With the advantages and disadvantages of the two systems in mind, we chose to implement the PtMatrix class with the data stored in a standard C array. Ptolemy's environment is such that matrices are created and deleted constantly as needed by stars: this negates much of the speedup gained from faster lookups. Also, we felt it was important to keep the design of the class simple and the memory usage efficient because of Ptolemy's increasing size and complexity.

4.4.2 The PtMatrix class

As explained previously, there are currently four data-specific matrix classes: ComplexMatrix, FixMatrix, FloatMatrix, and IntMatrix. Each of these classes stores its entries in a standard C array named data, which is an array of data objects corresponding to the PtMatrix type: Complex, Fix, double, or int. These four matrix classes implement a common set of operators and functions; in addition, the ComplexMatrix class has a few special methods such as conjugate() and hermitian() and the FixMatrix class has a number of special constructors that allow the user to specify the precision of the entries in the matrix. Generally, all entries of a FixMatrix will have the same precision.

The matrix classes were designed to take full advantage of operator overloading in C++ so that operations on matrix objects can be written much like operations on scalar ones. For example, the two-operand multiply operator * has been defined so that if A and B are matrices, A * B will return a third matrix that is the matrix product of A and B.

4.4.3 Public functions and operators for the PtMatrix class

• XXX refers to one of the following: Complex, Fix, Float, or Int
• xxx refers to one of the following: Complex, Fix, double, or int

Functions and Operators to access entries of the Matrix:

Example: if(A.isA("FixMatrix")) then ...
Return TRUE if the argument string matches the type string of the matrix.

4.4.4 Writing stars and programs using the PtMatrix class

This section describes how to use the matrix data classes when writing stars. Some examples will be given here but the programmer should refer to the stars in $PTOLEMY/src/domains/sdf/matrix/stars/*.pl and $PTOLEMY/src/domains/sdf/image/stars/*.pl for more examples

Memory management

The most important thing to understand about the use of matrix data classes in the Ptolemy environment is that stars that intend to output the matrix in a particle should allocate memory for the matrix but never delete that matrix. Memory reclamation is done automatically by the reference-counting mechanism of the Message class. Strange errors will occur if the star deletes the matrix before it is used by another star later in the execution sequence.

Naming conventions

Stars that implement general-purpose matrix operations usually have names with the _M suffix to distinguish them from stars that operate on scalar particles. For example, the SDFGain_M star multiplies an input matrix by a scalar value and outputs the resulting matrix. This is in contrast to SDFGain, which multiplies an input value held in a FloatParticle by a double and puts that result in an output FloatParticle.

Include files

For a star to use the PtMatrix classes, it must include the file Matrix.h in either its .h or .cc file. If the star has a matrix data member, then the declaration

hinclude { "Matrix.h" } needs to be in the Star definition. Otherwise, the declaration

ccinclude { "Matrix.h" } is sufficient.

To declare an input porthole that accepts matrices, the following syntax is used:

input {
name { inputPortHole }
type { FLOAT_MATRIX_ENV }
} The syntax is the same for output portholes. The type field can be COMPLEX_MATRIX_ENV, FLOAT_MATRIX_ENV, FIX_MATRIX_ENV, or INT_MATRIX_ENV. The icons created by Ptolemy will have terminals that are thicker and that have larger arrow points than the terminals for scalar particle types. The colors of the terminals follow the pattern of colors for scalar data types (e.g., blue represents Float and FloatMatrix).

Input portholes

The syntax to extract a matrix from the input porthole is:

Envelope inPkt;
(inputPortHole%0).getMessage(inPkt);
const FloatMatrix& inputMatrix =
*(const FloatMatrix *)inPkt.myData(); The first line declares an Envelope, which is used to access the matrix. Details of the Envelope class are given in "Use of the Envelope class" on page 4-17. The second line fills the envelope with the input matrix. Note that, because of the reference-counting mechanism, this line does not make a copy of the matrix. The last two lines extract a reference to the matrix from the envelope. It is up to the programmer to make sure that the cast agrees with the definition of the input port.

Because multiple envelopes might reference the same matrix, a star is generally not permitted to modify the matrix held by the Envelope. Thus, the function myData() returns a const Message *. We cast that to be a const FloatMatrix * and then de-reference it and assign the value to inputMatrix. It is generally better to handle matrices by reference instead of by pointer because it is clearer to write "A + B" rather than "*A + *B" when working with matrix operations. Stars that wish to modify an input matrix should access it using the writableCopy method, as explained in "Use of the Envelope class" on page 4-17.

Allowing delays on inputs

The cast to (const FloatMatrix *) above is not always safe. Even if the source star is known to provide matrices of the appropriate type, a delay on the arc connecting the two stars can cause problems. In particular, delays in dataflow domains are implemented as initial particles on the arcs. These initial particles are given the value "zero" as defined by the type of particle. For Message particles, a "zero" is an uninitialized Message particle containing a "dummy" data value. This dummy Message will be returned by the myData method in the third line of the above code fragment. The dummy message is not a FloatMatrix, rendering the above cast invalid. A star that expects matrix inputs must have code to handle empty particles. An example is:

if(inPkt.empty()) {
FloatMatrix& result = *(new FloatMatrix(int(numRows),
int(numCols)));
result = 0.0;
output%0 << result;
}
There are many ways that an empty input can be interpreted by a star that operates on matrices. For example, a star multiplying two matrices can simply output a zero matrix if either input is empty. A star adding two matrices can output whichever input is not empty. Note above that we create an output matrix that has the dimensions as set by the state parameters of the star so that any star that uses this output will have valid data.

A possible alternative to outputting a zero matrix is to simply pass that empty MessageParticle along. This approach, however, can lead to counterintuitive results. Suppose that empty message reaches a display star like TkText, which will attempt to call the print() method of the object. An empty message has a print() method that results in a message like

<type>: no print method

This is likely to prove extremely confusing to users, so we strongly recommend that each matrix star handle the empty input in a reasonable way, and produce a non-empty output.

Matrix outputs

To put a matrix into an output porthole, the syntax is:

FloatMatrix& outMatrix =*(new FloatMatrix(someRow,someCol));
// ... do some operations on the outMatrix
outputPortHole%0 << outMatrix; The last line is similar to outputting a scalar value. This is because we have overloaded the << operator for MatrixEnvParticles to support PtMatrix class inputs. The standard use of the MessageParticle class requires you to put your message into an envelope first and then use << on the envelope (see "Use of the Envelope class" on page 4-17), but we have specialized this so that the extra operation of creating an envelope first is not explicit.

Here is an example of a complete star definition that inputs and outputs matrices:

defstar {
name { Mpy_M }
domain { SDF }
desc {
Does a matrix multiplication of two input Float matrices A and B to
produce matrix C.
Matrix A has dimensions (numRows,X).
Matrix B has dimensions (X,numCols).
Matrix C has dimensions (numRows,numCols).
The user need only specify numRows and numCols. An error will be
generated automatically if the number of columns in A does not match
the number of columns in B.
}
input {
name { Ainput }
type { FLOAT_MATRIX_ENV }
}
input {
name { Binput }
type { FLOAT_MATRIX_ENV }
}
output {
name { output }
type { FLOAT_MATRIX_ENV }
}
defstate {
name { numRows }
type { int }
default { 2 }
desc { The number of rows in Matrix A and Matrix C.}
}
defstate {
name { numCols }
type { int }
default { 2 }
desc { The number of columns in Matrix B and Matrix C}
}
ccinclude { "Matrix.h" }
go {
// get inputs
Envelope Apkt;
(Ainput%0).getMessage(Apkt);
const FloatMatrix& Amatrix =
*(const FloatMatrix *)Apkt.myData();

Envelope Bpkt;
(Binput%0).getMessage(Bpkt);
const FloatMatrix& Bmatrix =
*(const FloatMatrix *)Bpkt.myData();

// check for "null" matrix inputs, which could be
// caused by delays on the input line
if(Apkt.empty() || Bpkt.empty()) {
// if either input is empty, return a zero
// matrix with the state dimensions
FloatMatrix& result =
*(new FloatMatrix(int(numRows),
int(numCols)));
result = 0.0;
output%0 << result;
}
else {
// Amatrix and Bmatrix are both valid
if((Amatrix.numRows() != int(numRows)) ||
(Bmatrix.numCols() != int(numCols))) {
Error::abortRun(*this,
"Dimension size of FloatMatrix inputs do ",
"not match the given state parameters.");
return;
}
// do matrix multiplication
FloatMatrix& result =
*(new FloatMatrix(int(numRows),
int(numCols)));
// we could write
// result = Amatrix * Bmatrix;
// but the following is faster
multiply(Amatrix,Bmatrix,result);

output%0 << result;
}
}
}

4.4.5 Future extensions

After reviewing the libraries of numerical analysis software that is freely available on the Internet, it is clear that it would be beneficial to extend the PtMatrix class by adding those well-tested libraries as callable functions. Unfortunately, many of those libraries are currently only available in Fortran, and there are some incompatibilities with Fortran's column major ordering and C's row major ordering. Those problems would still exist even if the Fortran code was converted to C. There are a few groups which are currently working on C++ ports of the numerical analysis libraries. One notable group is the Lapack++² project which is developing a flexible matrix class of their own, besides porting the Fortran algorithms of Lapack into C++. This might possibly be incorporated in a future release.

---

---

¹ We recommend, however, that you do not adapt this method to your own types, but use the standard method of adding new message types described in Section 4.3. The method currently used for the matrix classes may not be supported in future releases.

² LAPACK++: A Design Overview of Object-Oriented Extensions for High Performance Linear Algebra, by Jack J. Dongarra, Roldan Pozo, and David W. Walker, available on netlib.

Copyright © 1990-1997, University of California. All rights reserved.