numcxx::TMatrix< T > Class Template Reference

Description

template<typename T>
class numcxx::TMatrix< T >

Dense matrix class.

Besides two dimensional indexing like for numcxx::TArray2 it provides the method numcxx::TMatrix::apply() for efficient matrix-vector multiplication via LAPACK dgemm.

Alternatively LeftMatrixMultiplicationExpression<A,B> operator*(const A& a, const B& b) can be used as an expression template which allows an instance of this class to be used in typical linear algebra expressions.

Instances of this class can be created in various ways. The preferred construction of empty array goes like this:

numcxx::TMatrix<double> A(n,m);
std::shared_ptr<numcxx::TMatrix<double>> pA=numcxx::TMatrix<double>::create(n,m)

As a derived class from numcxx::TArray<T> it is merely a facade to the content in the base class.

An alias numcxx::DMatrix for numcxx::TMatrix<double> is available from numcxx.h.

Examples:

13-numcxx-lapack.cxx.

Definition at line 38 of file tmatrix.hxx.

Inheritance diagram for numcxx::TMatrix< T >:

Collaboration diagram for numcxx::TMatrix< T >:

Public Types
typedef T	value_type

Public Member Functions
	TMatrix (index n1, index n2)
	Construct an empty matrix. More...
	TMatrix (index n1, index n2, T *data, std::function< void(T *p)> deleter)
	Construct matrix from data pointer. More...
	TMatrix (index n1, index n2, T *data, std::shared_ptr< void > datamanager)
	Construct matrix from data pointer. More...
	TMatrix (const std::initializer_list< std::initializer_list< T >> &il)
	Construct 2D Array from std::initializer list. More...
	TMatrix (const TMatrix< T > &A)
	Copy constructor. More...
std::shared_ptr< TMatrix< T > >	copy () const
	Create a copy of the matrix. More...
std::shared_ptr< TMatrix< T > >	clone () const
	Create a clone of the matrix. More...
T	item (index i0, index i1)
	Element read access. More...
void	itemset (index i0, index i1, T x)
	Element write access. More...
const T &	xentry (const index i, const index j) const
	Matrix entry access for use in expression templates. More...
std::shared_ptr< TArray1< T > > const	__getitem__ (index i0)
	Getter routine for access from python. More...
TMatrix< T > &	operator= (const TMatrix< T > &expr)
	Assignment operator. More...
TMatrix< T > &	operator= (const T &expr)
	Assignment operator. More...
void	apply (const TArray< T > &u, TArray< T > &v) const
	Apply matrix to vector. More...
std::shared_ptr< TMatrix< T > >	calculate_inverse ()
	Calculate inverse of matrix. More...
	TMatrix ()
	Construct zero size matrix. More...
bool	is_matrix ()
template<>
void	apply (const TArray< double > &u, TArray< double > &v) const
template<>
void	apply (const TArray< float > &u, TArray< float > &v) const
T &	operator() (const index i0)
	Access operator for 1D arrays. More...
const T &	operator() (const index i0) const
T &	operator() (const index i0, const index i1)
	Access operator for 2D arrays. More...
const T &	operator() (const index i0, const index i1) const
index	ndim () const
	Obtain tensor dimension of array. More...
size_t	size () const
	Obtain size of array. More...
index	shape (const index dim) const
	Obtain shape of array for given dimension. More...
template<typename VAL >
void	operator+= (const VAL &a)
	Add value to all elements. More...
template<typename VAL >
void	operator-= (const VAL &a)
	Subtract value from all elements. More...
template<typename VAL >
void	operator*= (const VAL &a)
	Multiply all elements by value. More...
template<typename VAL >
void	operator/= (const VAL &a)
	Divide each element by value. More...
T &	operator[] (const index i)
	Alternative access operator for 1D arrays. More...
const T &	operator[] (const index i) const
	Const reference to entry for use in expression templates. More...
T *	data () const
	Obtain C-pointer of data array. More...
void	resize (size_t n)
	Resize array. More...
void	savetxt (std::ostream &s) const

Static Public Member Functions
static std::shared_ptr< TMatrix< T > >	create (index n1, index n2)
	Construct empty square matrix. More...
static std::shared_ptr< TMatrix< T > >	create (const std::initializer_list< std::initializer_list< T >> &il)
	Construct matrix from std::initializer list. More...
static void	operate (std::function< void(T &a, T &b)> f, TArray< T > &A, TArray< T > &B)
	Binary operation on arrays. More...
static void	operate (std::function< void(T &a, T &b, T &c)> f, TArray< T > &A, TArray< T > &B, TArray< T > &C)
	Ternary operation on arrays. More...

Protected Member Functions
void	_assert_square () const
	Check if all shapes are the same. More...
index	_idx (index i0) const
	1D Array index calculation with optional bounds check. More...
index	_idx (index i0, index i1) const
	2D Array index calculation with optional bounds check. More...
index	_idx (index i0, index i1, index i2) const
	3D Array index calculation with optional bounds check. More...
void	_nullify ()
	Nullify contents of array (for move constructors) More...
void	_setshape (index shape0)
	Set shape of 1D array (for move constructors) More...

Protected Attributes
std::function< void(T *p)>	_deleter =nullptr
	Deleter method. More...
std::shared_ptr< void >	_datamanager =nullptr
	Data manager. More...
T *	_data =nullptr
	Data pointer. More...

Member Typedef Documentation

template<typename T>

typedef T numcxx::TArray< T >::value_type

inherited

Definition at line 30 of file tarray.hxx.

Constructor & Destructor Documentation

template<typename T>

numcxx::TMatrix< T >::TMatrix ( index  n1, index  n2  )

inline

Construct an empty matrix.

Parameters

n0	Number of rows
n1	Number of columns

Definition at line 50 of file tmatrix.hxx.

: TArray<T>(n1,n2){_assert_square();};

Here is the call graph for this function:

template<typename T>

numcxx::TMatrix< T >::TMatrix ( index  n1, index  n2, T *  data, std::function< void(T *p)>  deleter  )

inline

Construct matrix from data pointer.

Parameters

n0	Number of rows
n1	Number of columns
data	Pointer to data.
deleter	Deleter method,

See also

TArray<T>::_deleter

Definition at line 59 of file tmatrix.hxx.

:  TArray<T>(n1,n2,data,deleter){_assert_square();};

Here is the call graph for this function:

template<typename T>

numcxx::TMatrix< T >::TMatrix ( index  n1, index  n2, T *  data, std::shared_ptr< void >  datamanager  )

inline

Construct matrix from data pointer.

Parameters

n0	Number of rows
n1	Number of columns
data	Pointer to data.
deleter	Deleter method.

See also

TArray<T>::_datamanager

Definition at line 68 of file tmatrix.hxx.

: TArray<T>(n1,n2,data,datamanager){_assert_square();};

Here is the call graph for this function:

template<typename T>

numcxx::TMatrix< T >::TMatrix ( const std::initializer_list< std::initializer_list< T >> &  il )

inline

Construct 2D Array from std::initializer list.

Definition at line 72 of file tmatrix.hxx.

: TArray<T>(il){_assert_square();};

Here is the call graph for this function:

template<typename T>

numcxx::TMatrix< T >::TMatrix ( const TMatrix< T > &  A )

inline

Copy constructor.

Definition at line 75 of file tmatrix.hxx.

:TArray<T>(A.shape(0),A.shape(1)){assign(*this,A);}

Here is the call graph for this function:

template<typename T>

numcxx::TMatrix< T >::TMatrix ( )

inline

Construct zero size matrix.

Definition at line 146 of file tmatrix.hxx.

: TArray<T>(){_assert_square();};

Here is the call graph for this function:

Member Function Documentation

template<typename T>

static std::shared_ptr<TMatrix <T> > numcxx::TMatrix< T >::create ( index  n1, index  n2  )

inlinestatic

Construct empty square matrix.

Mainly for access from python

Examples:

14-numcxx-lapack-sharedptr.cxx.

Definition at line 81 of file tmatrix.hxx.

{  return std::make_shared<TMatrix<T>> (n1,n2);  }

template<typename T>

static std::shared_ptr<TMatrix <T> > numcxx::TMatrix< T >::create ( const std::initializer_list< std::initializer_list< T >> &  il )

inlinestatic

Construct matrix from std::initializer list.

Definition at line 84 of file tmatrix.hxx.

{ return std::make_shared<TMatrix<T>> (il);  }

template<typename T>

std::shared_ptr<TMatrix <T> > numcxx::TMatrix< T >::copy ( ) const

inline

Create a copy of the matrix.

Returns

Matrix of the same size with contents initialized to this

Definition at line 89 of file tmatrix.hxx.

{  return std::make_shared<TMatrix<T>>(*this);  }

template<typename T>

std::shared_ptr<TMatrix <T> > numcxx::TMatrix< T >::clone ( ) const

inline

Create a clone of the matrix.

Returns

Matrix of the same size with empty contents.

Definition at line 94 of file tmatrix.hxx.

{  return create(shape(0),shape(1)); } 

Here is the call graph for this function:

template<typename T>

T numcxx::TMatrix< T >::item ( index  i0, index  i1  )

inline

Element read access.

Parameters

i0	Row index of element to be accessed.
i1	Column index of element to be accessed.

Returns

Value of element at (i0,i1)

Definition at line 101 of file tmatrix.hxx.

{ return _data[_idx(i0,i1)];};

Here is the call graph for this function:

template<typename T>

void numcxx::TMatrix< T >::itemset ( index  i0, index  i1, T  x  )

inline

Element write access.

Parameters

i0	Row index of element to be accessed.
i1	Column index of element to be accessed.
x	value to be copied to element at index.

Definition at line 109 of file tmatrix.hxx.

{ _data[_idx(i0,i1)]=x;};

Here is the call graph for this function:

template<typename T>

const T& numcxx::TMatrix< T >::xentry ( const index  i, const index  j  ) const

inline

Matrix entry access for use in expression templates.

Definition at line 113 of file tmatrix.hxx.

{return _data[_idx(i,j)];}

Here is the call graph for this function:

template<typename T>

std::shared_ptr<TArray1 <T> > const numcxx::TMatrix< T >::__getitem__ ( index  i0 )

inline

Getter routine for access from python.

This access is rather expensive, as it constructs a smart pointer to the row.

Parameters

i0	row index of element to be accessed.

Returns

Smart pointer to i0-th row.

Definition at line 121 of file tmatrix.hxx.

{ return std::shared_ptr<TArray1<T>>(new TArray1<T>(shape(1), &_data[_idx(i0,0)], [](T*p){;}));}

Here is the call graph for this function:

template<typename T>

TMatrix<T>& numcxx::TMatrix< T >::operator= ( const TMatrix< T > &  expr )

inline

Assignment operator.

Definition at line 126 of file tmatrix.hxx.

{return static_cast<TMatrix<T>&>(assign(*this,expr));}

Here is the call graph for this function:

template<typename T>

TMatrix<T>& numcxx::TMatrix< T >::operator= ( const T &  expr )

inline

Assignment operator.

Definition at line 129 of file tmatrix.hxx.

{return static_cast<TMatrix<T>&>(assign(*this,expr));}

Here is the call graph for this function:

template<typename T >

void numcxx::TMatrix< T >::apply ( const TArray< T > &  u, TArray< T > &  v  ) const

inlinevirtual

Apply matrix to vector.

This method performs a matrix-vector multiplication.

For float and double datatypes, sgemm resp. dgemm of LAPACK are called.

Parameters

u	input
v	output: v=A*u

Reimplemented from numcxx::TLinOperator< T >.

Definition at line 60 of file tmatrix.ixx.

  {
    for (index i=0;i<shape(1);i++)
    {   v[i]=0.0;
      for (index j=0;j<shape(0);j++)
        v[i]+=_data[_idx(i,j)]*u[j];
    }
  }

template<typename T >

std::shared_ptr< TMatrix< T > > numcxx::TMatrix< T >::calculate_inverse ( )

inline

Calculate inverse of matrix.

Definition at line 70 of file tmatrix.ixx.

  {
    auto pA=copy();  // essentially superfluous, but we seldomly use this
    auto pLU=TSolverLapackLU<T>::create(pA);
    return pLU->calculate_inverse();
  }

Here is the call graph for this function:

template<typename T>

bool numcxx::TMatrix< T >::is_matrix ( )

inline

Definition at line 149 of file tmatrix.hxx.

{return true;}

template<>

void numcxx::TMatrix< double >::apply ( const TArray< double > &  u, TArray< double > &  v  ) const

inline

Definition at line 18 of file tmatrix.ixx.

  {
    v.resize(u.size());
    char transmat[2]={'T','\0'};
    char transvec[2]={'N','\0'};
    int n=shape(0);
    int ione=1;
    double done=1.0;
    double dzero=0.0;
    dgemm_(transmat,
           transvec,
           &n,&ione,&n,
           &done,
           _data,&n,
           u.data(),&n,
           &dzero,
           v.data(),&n);
  }

Here is the call graph for this function:

template<>

void numcxx::TMatrix< float >::apply ( const TArray< float > &  u, TArray< float > &  v  ) const

inline

Definition at line 39 of file tmatrix.ixx.

  {
    v.resize(u.size());
    char transmat[2]={'T','\0'};
    char transvec[2]={'N','\0'};
    int n=shape(0);
    int ione=1;
    float done=1.0;
    float dzero=0.0;
    sgemm_(transmat,
           transvec,
           &n,&ione,&n,
           &done,
           _data,&n,
           u.data(),&n,
           &dzero,
           v.data(),&n);
  }

Here is the call graph for this function:

template<typename T>

T& numcxx::TArray< T >::operator() ( const index  i0 )

inlineinherited

Access operator for 1D arrays.

Parameters

i0	Index of element to be accessed.

Returns

Reference to element to be accessed.

Definition at line 36 of file tarray.hxx.

{ return _data[_idx(i0)];};

Here is the call graph for this function:

template<typename T>

const T& numcxx::TArray< T >::operator() ( const index  i0 ) const

inlineinherited

Definition at line 37 of file tarray.hxx.

{ return _data[_idx(i0)];};

Here is the call graph for this function:

template<typename T>

T& numcxx::TArray< T >::operator() ( const index  i0, const index  i1  )

inlineinherited

Access operator for 2D arrays.

Parameters

i0	Row index of element to be accessed.
i0	Column index of element to be accessed.

Returns

Reference to element to be accessed.

Definition at line 44 of file tarray.hxx.

{ return _data[_idx(i0,i1)];};

Here is the call graph for this function:

template<typename T>

const T& numcxx::TArray< T >::operator() ( const index  i0, const index  i1  ) const

inlineinherited

Definition at line 45 of file tarray.hxx.

{ return _data[_idx(i0,i1)];};

Here is the call graph for this function:

template<typename T>

index numcxx::TArray< T >::ndim ( ) const

inlineinherited

Obtain tensor dimension of array.

Tensor dimension is 1 for vectors, 2 for matrices.

Returns

Dimension.

Definition at line 52 of file tarray.hxx.

{return _ndim;}

template<typename T>

size_t numcxx::TArray< T >::size ( ) const

inlineinherited

Obtain size of array.

This ist the overall number of elements in the array

Returns

Size.

Examples:

11-numcxx-ref.cxx, 12-numcxx-sharedptr.cxx, 44-transient-heat-fe.cxx, and 45-convdiff1d.cxx.

Definition at line 58 of file tarray.hxx.

{ return _size;}

template<typename T>

index numcxx::TArray< T >::shape ( const index  dim ) const

inlineinherited

Obtain shape of array for given dimension.

For 1D arrays, shape(0) is equivalent to the size For 2D arrays, shape(0) is the number of rows and shape(1) the number of columns. This corresponds to the "row major" storage format.

Parameters

dim	Tensor dimension.

Returns

Number of elements in given dimension.

Definition at line 68 of file tarray.hxx.

{return _shape[dim];}

template<typename T>

template<typename VAL >

void numcxx::TArray< T >::operator+= ( const VAL &  a )

inlineinherited

Add value to all elements.

Parameters

a	Summand for each element.

Definition at line 74 of file tarray.hxx.

{xadd(*this,a);}

Here is the call graph for this function:

template<typename T>

template<typename VAL >

void numcxx::TArray< T >::operator-= ( const VAL &  a )

inlineinherited

Subtract value from all elements.

Parameters

a	Value to be subracted from each element.

Definition at line 80 of file tarray.hxx.

{xsub(*this,a);}

Here is the call graph for this function:

template<typename T>

template<typename VAL >

void numcxx::TArray< T >::operator*= ( const VAL &  a )

inlineinherited

Multiply all elements by value.

Parameters

a	Multiplicator for each element.

Definition at line 87 of file tarray.hxx.

{xmul(*this,a);}

Here is the call graph for this function:

template<typename T>

template<typename VAL >

void numcxx::TArray< T >::operator/= ( const VAL &  a )

inlineinherited

Divide each element by value.

Parameters

a	Divisor for each element.

Definition at line 94 of file tarray.hxx.

{xdiv(*this,a);}

Here is the call graph for this function:

template<typename T >

void numcxx::TArray< T >::operate ( std::function< void(T &a, T &b)>  f, TArray< T > &  A, TArray< T > &  B  )

inlinestaticinherited

Binary operation on arrays.

Parameters

f	Function performing operation for each index.
A	First array argument.
B	Second array argument.

Definition at line 314 of file tarray.ixx.

  { 
    for(index i=0;i<A._size;i++) f(A._data[i],B._data[i]);
  }

template<typename T >

void numcxx::TArray< T >::operate ( std::function< void(T &a, T &b, T &c)>  f, TArray< T > &  A, TArray< T > &  B, TArray< T > &  C  )

inlinestaticinherited

Ternary operation on arrays.

Parameters

f	Function performing operation for each index.
A	First array argument.
B	Second array argument.
C	Third array argument.

Definition at line 320 of file tarray.ixx.

  {
    for(index i=0;i<A._size;i++) f(A._data[i],B._data[i],C._data[i]);
  }

template<typename T>

T& numcxx::TArray< T >::operator[] ( const index  i )

inlineinherited

Alternative access operator for 1D arrays.

Definition at line 115 of file tarray.hxx.

{ return _data[i];}

template<typename T>

const T& numcxx::TArray< T >::operator[] ( const index  i ) const

inlineinherited

Const reference to entry for use in expression templates.

Definition at line 118 of file tarray.hxx.

{ return _data[i];};

template<typename T>

T* numcxx::TArray< T >::data ( ) const

inlineinherited

Obtain C-pointer of data array.

Returns

Address of C-Array managed by the class which holds the data

Definition at line 128 of file tarray.hxx.

{ return _data;}

Here is the call graph for this function:

template<typename T >

void numcxx::TArray< T >::resize ( size_t  n )

inlineinherited

Resize array.

Definition at line 282 of file tarray.ixx.

  {
    if (_size==n) return;

    if (_ndim>1)
    {
      char errormsg[80];
      snprintf(errormsg,80,"numcxx::TArray::resize: unable to resize 2D Array to 1D.\n");
      throw std::runtime_error(errormsg);
    }
        
    if (_datamanager==nullptr)
    {
      _deleter(_data);
      _data=(T*)malloc(sizeof(T)*n);
      if (_data==nullptr)  throw std::runtime_error("numcxx: TArray::resize(): Memory allocation failed"); 
      _deleter=[](T*p){free(p);};
      _size=n;
      _shape[0]=n;
      _shape[1]=0;
    }
    else
    {
      char errormsg[80];
      snprintf(errormsg,80,"numcxx::TArray::resize: unable to resize - data managed by different object.\n");
      throw std::runtime_error(errormsg);
    }
  }

template<typename T >

void numcxx::TArray< T >::savetxt ( std::ostream &  s ) const

inlineinherited

Definition at line 351 of file tarray.ixx.

  {
    if (ndim()==1)
      for (index i=0;i<size();i++) s << _data[i] << std::endl << std::flush;
    else
    {
      for (index i=0;i<shape(0);i++) 
      {
        for (index j=0;j<shape(1);j++) 
          s << _data[_idx(i,j)] << " ";
        s<< std::endl;
      }
      s << std::flush;
    }
  }

Here is the call graph for this function:

template<typename T >

void numcxx::TArray< T >::_assert_square ( ) const

inlineprotectedinherited

Check if all shapes are the same.

Throw an exception on error

Definition at line 145 of file tarray.ixx.

  {
    if (_ndim!=2 || _shape[0]!=_shape[1])
    {
      char errormsg[80];
      snprintf(errormsg,80,"numcxx::TArray::_assert_square: unexpected non-equal array dimensions\n");
      throw std::length_error(errormsg);
    }
  }

template<typename T >

index numcxx::TArray< T >::_idx ( index  i0 ) const

inlineprotectedinherited

1D Array index calculation with optional bounds check.

Definition at line 156 of file tarray.ixx.

  {
#ifdef NUMCXX_CHECK_BOUNDS
    _check_bounds(0,1,i0);
#endif
    return i0;
  }

Here is the call graph for this function:

template<typename T >

index numcxx::TArray< T >::_idx ( index  i0, index  i1  ) const

inlineprotectedinherited

2D Array index calculation with optional bounds check.

Definition at line 165 of file tarray.ixx.

  { 
#ifdef NUMCXX_CHECK_BOUNDS
    _check_bounds(0,2,i0);
    _check_bounds(1,2,i1);
#endif
    return i0*_shape[1]+i1;
  }

Here is the call graph for this function:

template<typename T >

index numcxx::TArray< T >::_idx ( index  i0, index  i1, index  i2  ) const

inlineprotectedinherited

3D Array index calculation with optional bounds check.

Definition at line 175 of file tarray.ixx.

  { 
#ifdef NUMCXX_CHECK_BOUNDS
    _check_bounds(0,3,i0);
    _check_bounds(1,3,i1);
    _check_bounds(2,3,i2);
#endif
    return (i0*_shape[0]+i1)*_shape[1]+i2;
  }

Here is the call graph for this function:

template<typename T >

void numcxx::TArray< T >::_nullify ( )

inlineprotectedinherited

Nullify contents of array (for move constructors)

Definition at line 254 of file tarray.ixx.

  {
    _shape[0]=0;     
    _shape[1]=0;     
    _shape[2]=0;     
    _size=0;       
    _deleter=[](T*p){;};     
    _datamanager=nullptr; 
    _data=nullptr;
  }

template<typename T >

void numcxx::TArray< T >::_setshape ( index  shape0 )

inlineprotectedinherited

Set shape of 1D array (for move constructors)

Definition at line 266 of file tarray.ixx.

  {
    if (_ndim!=1)
    {
      char errormsg[80];
      snprintf(errormsg,80,"numcxx::TArray::resize: unable to set 1D shape for 2D array.\n");
      throw std::runtime_error(errormsg);
    }
    _shape[0]=shape0;   
    _shape[1]=0;
    _shape[2]=0;
    _size=shape0;       
  }

Member Data Documentation

template<typename T>

std::function<void(T*p)> numcxx::TArray< T >::_deleter =nullptr

protectedinherited

Deleter method.

This is the proper method to be used to destroy the data pointer in the array if data manager is null. Depending on the way it was constructed, it may do nothing, free the memory, delete[] the memory, or something else.

Definition at line 172 of file tarray.hxx.

template<typename T>

std::shared_ptr<void> numcxx::TArray< T >::_datamanager =nullptr

protectedinherited

Data manager.

Smart pointer to some other object managing the data pointer. If it is not nullptr, the deleter is not called and the memory corresponding to the data pointer is freed when the object behind the data manager is destroyed.

An example in case is the use of shared_ptr<vector> v as datamanager and v->data() as data pointer

Definition at line 183 of file tarray.hxx.

template<typename T>

T* numcxx::TArray< T >::_data =nullptr

protectedinherited

Data pointer.

Definition at line 186 of file tarray.hxx.

---

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

• tmatrix.hxx
• tmatrix.ixx