• Antelope Release 5.5 Mac OS X 10.8.5 2015-04-21

 

NAME

dmatrix - simple object class for double precision matrices

SYNOPSIS

class dmatrix
{
public:
  dmatrix();
  dmatrix(int nr, int nc);
  dmatrix(dmatrix& other);
  ~dmatrix();
  double &operator()(int rowindex, int colindex);
  void operator=(dmatrix& other);
  void operator+=(dmatrix& other);
  void operator-=(dmatrix& other);
  friend dmatrix operator+(dmatrix&, dmatrix&);
  friend dmatrix operator-(dmatrix&, dmatrix&);
  friend dmatrix operator*(dmatrix&, dmatrix&);
  friend dmatrix operator*(double&, dmatrix&);
  friend dmatrix operator/(dmatrix&, double&);
  friend dmatrix tr(dmatrix&);
  friend ostream& operator<<(ostream&, dmatrix&);
  friend istream& operator>>(istream&, dmatrix&);
  double* get_address(int r, int c);
  void zero(); // initializes all elements to 0
  int *size(); // returns 2 element size array (nrrXncc)
  int rows();  // returns just number of rows
  int columns(); // returns just number of columns
private:
   double *ary;
   int length;
   int nrr, ncc;
};

SUPPORT


Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.

FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.

DESCRIPTION

Matrix algebra is at the core of many numerical methods. This is a simple class description to do basic matrix methods without a huge concern about efficiency. It is most useful for small problems where the convenience of the object description is of more importance than the speed of the algorithm or the richness of the tools available. If you need a more sophisticated matrix toolbox get the source code for the Matrix Template Library toolbox (http://www.osl.iu.edu/research/mtl/ ) or other similar packages out there on the web. Note that this library is a crude implementation of the lapack_matrix class in MTL in dense storage. That is, matrices are stored in dense storage mode in FORTRAN order. This allows the library to work efficiently with lapack routines found in the perf or sunperf libraries. Note, however, that indexing is in C form starting with 0. Thus the indexing for an array of size nr by nc is 0:nr-1 for rows and 0:nc-1 for columns.

Most usage should be obvious. A likely exception are the get_address function and the overloaded & operator. The overloaded () operator is used to fetch a single element of a matrix as in

double x;
x=A(15,26);
The get_address function or the & operator return a pointer to the a requested row and column. This is most useful in constructs using the BLAS like the following example:
        dmatrix prod(x1.nrr,b.ncc);
        for(i=0;i<x1.nrr;i++)
        {
                for(j=0;j<b.ncc;j++)
                {
                        prod(i,j)=ddot(x1.ncc,x1.get_address(i,0),x1.nrr,
                                b.get_address(0,j),1);
                }
        }
which is a code fragment for the dmatrix operator * in this library. The choice of using the function for or the operator is largely a matter of taste. get_address is more verbose while the & operator is more concise at the possible expense of clarity.

The size() method returns a 2 element int array with the number of rows in element 0 and the number of columsn in element 1. If size() is called the user is responsible for deleting the returned array. Alternatively, just use the rows() or columns() function to retrieve the size elements individually.

The stream output operator writes out the matrix in row order with space characters between elements. This is done for the convenience of reading the result into matlab. For example, if a matrix produced by the >> operator is written to a file matrix.out, it can be read into matlab using:

      A=dlmread('matrix.out',' ');

This is a bare-bones library with basic constructors and a few basic operators. The usage should be obvious, but a few routines can throw an exception that needs to be handled. All exceptions are handled through a common interface and any questionable use of operators that throw exceptions should be enclosed in a try-catch block of this form:

try {
	code using dmatrix operator
} catch (dmatrix_error& de)
{
	de.log_error()
	--additional error handling code--
}
The log_error function will post a descriptive message to stderr. You can, of course, bypass this verbosity and handle the error by some other mechanism. The following operatores throw exceptions:
() - index out of range
+,-, * for inconsistent sizes
most numerically stable answers for matrices that are not square.

DIAGNOSTICS

The log_print exception handler function will normally give a reasonable explanation for a problem. You will typically need added output to resolve which matrix is involved in a more complex program.

BUGS AND CAVEATS

This is a fairly simple implementation of a matrix class. It is not exceptionally efficient on many operations because it tends to create temporary matrices and do more copying than would be necessary in all cases. Point is if efficiency is a prime consideration, consider alternatives.

The insistence on C indexing conventions will be a confusion to FORTRAN programmers. You must remember that the index of a matrix is 0:nr-1 in rows and 0:nc-1 in columns.

AUTHOR

Robert Pavlis
Pittsburg State University, Dept. of Chemistry
rpavlis@pittstate.edu

Contributed to Antelope with modifications by:
Gary Pavlis
Indiana University
pavlis@indiana.edu

Antelope User Group Contributed Software
Printer icon