mspass::utility::dmatrix Class Reference

Lightweight, simple matrix object. More...

#include <dmatrix.h>

Inheritance diagram for mspass::utility::dmatrix:

Public Member Functions
	dmatrix ()
	dmatrix (const size_t nr, const size_t nc)
	dmatrix (const dmatrix &other)
	~dmatrix ()
double	operator() (const size_t rowindex, const size_t colindex) const
double &	operator() (size_t r, size_t c)
dmatrix &	operator= (const dmatrix &other)
dmatrix &	operator+= (const dmatrix &other)
	Add one matrix to another.
dmatrix &	operator-= (const dmatrix &other)
	Subtract one matrix to another.
dmatrix	operator+ (const dmatrix &other) const
dmatrix	operator- (const dmatrix &other) const
dmatrix	operator* (double s) const noexcept
double *	get_address (size_t r, size_t c) const
size_t	rows () const
size_t	columns () const
std::vector< size_t >	size () const
	Return a vector with 2 elements giving the size.
void	zero ()

Protected Attributes
std::vector< double >	ary
size_t	length
size_t	nrr
size_t	ncc

Friends
class	boost::serialization::access
dmatrix	operator* (const dmatrix &A, const dmatrix &B)
	Procedure to multiply two matrices. This could be implemented with a dmatrix::operator but this was an existing procedure known to work that I didn't choose to mess with. Sizes must be compatible or an exception will be thrown.
dmatrix	operator* (const double &s, const dmatrix &A) noexcept
	Scale a matrix by a constant.
dmatrix	tr (const dmatrix &A) noexcept
	Transpose a matrix.
std::ostream &	operator<< (std::ostream &os, dmatrix &A)
	Text output operator.

Detailed Description

Lightweight, simple matrix object.

This class defines a lightweight, simple double precision matrix. Provides basic matrix functionality. Note that elements of the matrix are stored internally in FORTRAN order but using C style indexing. That is, all indices begin at 0, not 1 and run to size - 1. Further, FORTRAN order means the elements are actually ordered in columns as in FORTRAN in a continuous, logical block of memory. This allow one to use the BLAS functions to access the elements of the matrix. As usual be warned this is useful for efficiency and speed, but completely circumvents the bounds checking used by methods in the object.

Author

Robert R and Gary L. Pavlis

Constructor & Destructor Documentation

dmatrix() [1/3]

mspass::utility::dmatrix::dmatrix

(

)

Default constructor. Produces a 1x1 matrix as a place holder.

                 {
  nrr = 0;
  ncc = 0;
  length = 0;
  ary.reserve(0);
}

dmatrix() [2/3]

mspass::utility::dmatrix::dmatrix	(	const size_t	nr,
		const size_t	nc
	)

Basic constructor. Allocates space for nr x nc array and initializes to zeros.

Parameters

nr	number of rows to allocate for this matrix.
nc	number of columns to allocate for this matrix.

                                                 {
  nrr = nr;
  ncc = nc;
  length = nr * nc;
  if (length < 1) {
    length = 1;
    nrr = ncc = 0;
  }
  /* This std::vector method allocates space so zero method can just
   * use indexing. */
  ary.resize(length);
  this->zero();
}

References zero().

dmatrix() [3/3]

mspass::utility::dmatrix::dmatrix

(

const dmatrix &

other

)

Standard copy constructor.

                                     {
  nrr = other.nrr;
  ncc = other.ncc;
  length = other.length;
  ary = other.ary;
}

~dmatrix()

mspass::utility::dmatrix::~dmatrix

(

)

Destructor - releases any matrix memory.

                  {
  // if(ary!=NULL) delete [] ary;
}

Member Function Documentation

columns()

size_t mspass::utility::dmatrix::columns

(

)

const

Return number of columns in this matrix.

{ return (ncc); }

get_address()

double * mspass::utility::dmatrix::get_address	(	size_t	r,
		size_t	c
	)		const

                                                                   {
  double *ptr;
  int out_of_range = 0;
  if (rowindex >= nrr)
    out_of_range = 1;
  if (rowindex < 0)
    out_of_range = 1;
  if (colindex >= ncc)
    out_of_range = 1;
  if (colindex < 0)
    out_of_range = 1;
  if (out_of_range)
    throw dmatrix_index_error(nrr, ncc, rowindex, colindex);
  /* This is somewhat contradictory to the const qualifier of the method
     but not really.  const in that position implies the method itself
     does not alter the object, but a pointer that is not const is
     always something that allows data to be changed*/
  ptr = const_cast<double *>(&(ary[rowindex + (nrr) * (colindex)]));
  return (ptr);
}

operator()() [1/2]

double mspass::utility::dmatrix::operator()	(	const size_t	rowindex,
		const size_t	colindex
	)		const

Indexing operator to fetch an array element.

Can also be used to set an element as a left hand side (e.g. A(2,4)=2.0;).

Parameters

rowindex	row to fetch
colindex	column to fetch.

Returns

value of matrix element at position (rowindex,colindex)

Exceptions

dmatrix_index_error

is thrown if request is out of range

                                                                             {
  int out_of_range = 0;
  if (rowindex >= nrr)
    out_of_range = 1;
  if (rowindex < 0)
    out_of_range = 1;
  if (colindex >= ncc)
    out_of_range = 1;
  if (colindex < 0)
    out_of_range = 1;
  if (out_of_range)
    throw dmatrix_index_error(nrr, ncc, rowindex, colindex);
  double result = ary[rowindex + (nrr) * (colindex)];
  return result;
}

operator()() [2/2]

double & mspass::utility::dmatrix::operator()	(	size_t	r,
		size_t	c
	)

                                                                        {
  int out_of_range = 0;
  if (rowindex >= nrr)
    out_of_range = 1;
  if (rowindex < 0)
    out_of_range = 1;
  if (colindex >= ncc)
    out_of_range = 1;
  if (colindex < 0)
    out_of_range = 1;
  if (out_of_range)
    throw dmatrix_index_error(nrr, ncc, rowindex, colindex);
  return (ary[rowindex + (nrr) * (colindex)]);
}

operator*()

dmatrix mspass::utility::dmatrix::operator* ( double  s ) const

noexcept

                                                  {
  double *ptr;
  dmatrix result(*this);
  ptr = result.get_address(0, 0);
  dscal(length, x, ptr, 1);
  return result;
}

operator+()

dmatrix mspass::utility::dmatrix::operator+

(

const dmatrix &

other

)

const

Operator to add two matrices.

This operator is similar to += but is the operator used in constructs like X=A+B. Like += other and this must be the same size or an exception will be thrown.

Parameters

other

matrix to be added

Exceptions

throws

a dmatrix_size_error if other and this are not the same size.

                                                     {
  try {
    dmatrix result(*this);
    result += other;
    return result;
  } catch (...) {
    throw;
  };
}

operator+=()

dmatrix & mspass::utility::dmatrix::operator+=

(

const dmatrix &

other

)

Add one matrix to another.

Matrix addition is a standard operation but demands the two matrices to be added are the same size. Hence, an exception will happen if you use this operator with a size mismatch.

Parameters

A	is the matrix to be added to this.

Exceptions

throws

a dmatrix_size_error if other and this are not the same size.

                                                 {
  size_t i;
  if ((nrr != other.nrr) || (length != other.length))
    throw dmatrix_size_error(nrr, ncc, other.nrr, other.length);
  for (i = 0; i < length; i++)
    ary[i] += other.ary[i];
  return *this;
}

operator-()

dmatrix mspass::utility::dmatrix::operator-

(

const dmatrix &

other

)

const

Operator to add two matrices.

This operator is similar to -= but is the operator used in constructs like X=A-B. Like -= other and this must be the same size or an exception will be thrown.

Parameters

other

matrix to be added

Exceptions

throws

a dmatrix_size_error if other and this are not the same size.

                                                     {
  try {
    dmatrix result(*this);
    result -= other;
    return result;
  } catch (...) {
    throw;
  };
}

operator-=()

dmatrix & mspass::utility::dmatrix::operator-=

(

const dmatrix &

other

)

Subtract one matrix to another.

Matrix subtraction is a standard operation but demands the two matrices to be added are the same size. Hence, an exception will happen if you use this operator with a size mismatch.

Parameters

other

is the matrix to be subracted from to this.

Exceptions

throws

a dmatrix_size_error if other and this are not the same size.

                                                 {
  size_t i;
  if ((nrr != other.nrr) || (length != other.length))
    throw dmatrix_size_error(nrr, ncc, other.nrr, other.length);
  for (i = 0; i < length; i++)
    ary[i] -= other.ary[i];
  return *this;
}

operator=()

dmatrix & mspass::utility::dmatrix::operator=

(

const dmatrix &

other

)

Standard assignment operator

                                                {
  if (&other != this) {
    ncc = other.ncc;
    nrr = other.nrr;
    length = other.length;
    ary = other.ary;
  }
  return *this;
}

rows()

size_t mspass::utility::dmatrix::rows

(

)

const

Return number of rows in this matrix.

{ return (nrr); }

size()

vector< size_t > mspass::utility::dmatrix::size

(

)

const

Return a vector with 2 elements giving the size.

This function returns an std::vector with 2 elements with size information. first component is rows, second is columns. This simulates the matlab size function.

                                   {
  vector<size_t> sz;
  sz.push_back(nrr);
  sz.push_back(ncc);
  return (sz);
}

zero()

void mspass::utility::dmatrix::zero

(

)

Initialize a matrix to all zeros.

                   {
  for (size_t i = 0; i < length; ++i)
    ary[i] = 0.0;
}

Friends And Related Symbol Documentation

operator* [1/2]

dmatrix operator* ( const dmatrix &  A, const dmatrix &  B  )

friend

Procedure to multiply two matrices. This could be implemented with a dmatrix::operator but this was an existing procedure known to work that I didn't choose to mess with. Sizes must be compatible or an exception will be thrown.

Parameters

A	is the left matrix for the multiply.
B	is the right matrix for the multiply.

Exceptions

dmatrix_size_error

will be thrown if the columns in A are not equal to the rows in B.

Returns

A*B

                                                       {
  size_t i, j;
  /* The computed length in last arg to the error object is a relic*/
  if (x1.columns() != b.rows())
    throw dmatrix_size_error(x1.rows(), x1.columns(), b.rows(),
                             b.rows() * b.columns());
  dmatrix prod(x1.rows(), b.columns());
  for (i = 0; i < x1.rows(); i++)
    for (j = 0; j < b.columns(); j++) {
      double *x1ptr, *bptr;
      x1ptr = const_cast<dmatrix &>(x1).get_address(i, 0);
      bptr = const_cast<dmatrix &>(b).get_address(0, j);
      /* This temporary seems necessary */
      double *dptr;
      dptr = prod.get_address(i, j);
      *dptr = ddot(x1.columns(), x1ptr, x1.rows(), bptr, 1);
    }
  return prod;
}

operator* [2/2]

dmatrix operator* ( const double &  s, const dmatrix &  A  )

friend

Scale a matrix by a constant.

This procedure will multiply all elements of a matrix by a constant. The linear algebra concept of scaling a matrix.

Parameters

s	is the scaling factor
A	is the matrix to be scaled

Returns

sA

                                                               {
  size_t i;
  dmatrix tempmat(zx.rows(), zx.columns());
  size_t lenary = zx.rows() * zx.columns();
  double *zptr, *dptr;
  zptr = const_cast<dmatrix &>(zx).get_address(0, 0);
  dptr = tempmat.get_address(0, 0);
  for (i = 0; i < lenary; ++i) {
    (*dptr) = x * (*zptr);
    ++dptr;
    ++zptr;
  }
  return tempmat;
}

operator<<

std::ostream & operator<< ( std::ostream &  os, dmatrix &  A  )

friend

Text output operator.

Output is ascii data written in the matrix layout. Note this can create huge lines and a lot of output for a large matrix so use carefully.

Parameters

os	is the std::ostream to contain data.
A	is the data to be written

tr

dmatrix tr ( const dmatrix &  A )

friend

Transpose a matrix.

A standard matrix operation is to transpose a matrix (reversing rows and columns). This takes input A and returns A^T.

Parameters

A	- matrix to transpose.

Returns

A transposed

                                       {
  size_t i, j;
  dmatrix temp(x1.columns(), x1.rows());
  for (i = 0; i < x1.rows(); i++)
    for (j = 0; j < x1.columns(); j++) {
      temp(j, i) = x1(i, j);
    }
  return temp;
}

---

The documentation for this class was generated from the following files:

• /home/runner/work/mspass/mspass/cxx/include/mspass/utility/dmatrix.h
• /home/runner/work/mspass/mspass/cxx/src/lib/utility/dmatrix.cc