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
	Get a pointer to the location of a matrix component.

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);
}

References ary, length, ncc, and nrr.

◆ 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 ary, length, ncc, nrr, and 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;
}

References ary, length, ncc, and nrr.

◆ ~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.

216{ return (ncc); }

References ncc.

◆ get_address()

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

Get a pointer to the location of a matrix component.

Although a sharp knife it is useful at times to get a raw pointer to the data in a dmatrix. A common one is using the BLAS to do vector operations for speed. Users of this method must note that the data for a dmatrix is stored as a single rowXcolumn std::vector container. The matrix is stored in Fortran order (column1, column2, ...). The contiguous memory guarantee of std::vector allows vector operations with the BLAS to work by rows or columns.

Parameters

r	is the row index of the desired address
c	is the column index of the desired memory address.

Returns: pointer to component at row r and column c.

Exceptions

dmatrix_size_error will be throw if r or c are outside matrix dimensions.

                                                                   {
  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);
}

References ary, ncc, and nrr.

◆ 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;
}

References ary, ncc, and nrr.

◆ operator()() [2/2]

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

Mutable indexing operator to fetch or modify an array element.

Parameters

r	row index to fetch.
c	column index to fetch.

Returns: reference to matrix element at position (r,c).

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);
  return (ary[rowindex + (nrr) * (colindex)]);
}

References ary, ncc, and nrr.

◆ operator*()

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

noexcept

Scale this matrix by a constant.

Multiplies every element in this matrix by s and returns the scaled copy.

Parameters

s	scaling factor.

Returns: this matrix multiplied by s.

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

References get_address().

◆ 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

other 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;
}

References ary, length, ncc, and nrr.

◆ 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;
}

References ary, length, ncc, and nrr.

◆ 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;
}

References ary, length, ncc, and nrr.

◆ rows()

size_t mspass::utility::dmatrix::rows ( ) const

Return number of rows in this matrix.

215{ return (nrr); }

References 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);
}

References ncc, and nrr.

◆ zero()

void mspass::utility::dmatrix::zero ( )

Initialize a matrix to all zeros.

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

References ary, and length.

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 (A.columns() != B.rows())
    throw dmatrix_size_error(A.rows(), A.columns(), B.rows(),
                             B.rows() * B.columns());
  dmatrix prod(A.rows(), B.columns());
  for (i = 0; i < A.rows(); i++)
    for (j = 0; j < B.columns(); j++) {
      double *x1ptr, *bptr;
      x1ptr = const_cast<dmatrix &>(A).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(A.columns(), x1ptr, A.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: s*A

                                                              {
  size_t i;
  dmatrix tempmat(A.rows(), A.columns());
  size_t lenary = A.rows() * A.columns();
  double *zptr, *dptr;
  zptr = const_cast<dmatrix &>(A).get_address(0, 0);
  dptr = tempmat.get_address(0, 0);
  for (i = 0; i < lenary; ++i) {
    (*dptr) = s * (*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(A.columns(), A.rows());
  for (i = 0; i < A.rows(); i++)
    for (j = 0; j < A.columns(); j++) {
      temp(j, i) = A(i, j);
    }
  return temp;
}

Member Data Documentation

◆ ary

std::vector<double> mspass::utility::dmatrix::ary

protected

Contiguous Fortran-order storage for all matrix elements.

◆ length

size_t mspass::utility::dmatrix::length

protected

Number of scalar values in ary that represent this matrix.

◆ ncc

size_t mspass::utility::dmatrix::ncc

protected

Number of columns in this matrix.

◆ nrr

size_t mspass::utility::dmatrix::nrr

protected

Number of rows in this matrix.

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

Public Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ dmatrix() [1/3]

◆ dmatrix() [2/3]

◆ dmatrix() [3/3]

◆ ~dmatrix()

Member Function Documentation

◆ columns()

◆ get_address()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ operator*()

◆ operator+()

◆ operator+=()

◆ operator-()

◆ operator-=()

◆ operator=()

◆ rows()

◆ size()

◆ zero()

Friends And Related Symbol Documentation

◆ operator* [1/2]

◆ operator* [2/2]

◆ operator<<

◆ tr

Member Data Documentation

◆ ary

◆ length

◆ ncc

◆ nrr