Jive reference manual
List of all members | Public Member Functions | Static Public Attributes
jem::numeric::MatmulChain< T, N > Class Template Reference

Multiplies a series of matrices and vectors. More...

#include <jem/numeric/algebra/MatmulChain.h>

Public Member Functions

 MatmulChain ()
 Creates a new matmul chain. More...
 
const Array< T, 2 > & matmul (const Array< T > &v, const Array< T > &w)
 Computes the matrix product of two vectors. More...
 
const Array< T > & matmul (const Array< T, 2 > &a, const Array< T > &v)
 Computes the product of a matrix and a vector. More...
 
const Array< T > & matmul (const Array< T > &v, const Array< T, 2 > &a)
 Computes the product of a vector and a matrix. More...
 
const Array< T, 2 > & matmul (const Array< T > &v, const Array< T, 2 > &a, const Array< T > &w)
 Computes the product of two vectors and a matrix. More...
 
const Array< T, 2 > & matmul (const Array< T, 2 > &a, const Array< T, 2 > &b)
 Computes the product of two matrices. More...
 
const Array< T > & matmul (const Array< T, 2 > &a, const Array< T, 2 > &b, const Array< T > &v)
 Computes the product of two matrices and a vector. More...
 
const Array< T > & matmul (const Array< T > &v, const Array< T, 2 > &a, const Array< T, 2 > &b)
 Computes the product of a vector and two matrices. More...
 
const Array< T, 2 > & matmul (const Array< T > &v, const Array< T, 2 > &a, const Array< T, 2 > &b, const Array< T > &w)
 Computes the matrix product of two vectors and two matrices. More...
 
const Array< T, 2 > & matmul (const Array< T, 2 > &a, const Array< T, 2 > &b, const Array< T, 2 > &c)
 Computes the product of three matrices. More...
 
const Array< T > & matmul (const Array< T, 2 > &a, const Array< T, 2 > &b, const Array< T, 2 > &c, const Array< T > &v)
 Computes the product of three matrices and a vector. More...
 
const Array< T > & matmul (const Array< T > &v, const Array< T, 2 > &a, const Array< T, 2 > &b, const Array< T, 2 > &c)
 Computes the product of a vector and three matrices. More...
 
const Array< T, 2 > & matmul (const Array< T > &v, const Array< T, 2 > &a, const Array< T, 2 > &b, const Array< T, 2 > &c, const Array< T > &w)
 Computes the matrix product of two vectors and three matrices. More...
 
const Array< T, 2 > & matmul (const Array< T, 2 > &a, const Array< T, 2 > &b, const Array< T, 2 > &c, const Array< T, 2 > &d)
 Computes the product of four matrices. More...
 
const Array< T > & matmul (const Array< T, 2 > &a, const Array< T, 2 > &b, const Array< T, 2 > &c, const Array< T, 2 > &d, const Array< T > &v)
 Computes the product of four matrices and a vector. More...
 
const Array< T > & matmul (const Array< T > &v, const Array< T, 2 > &a, const Array< T, 2 > &b, const Array< T, 2 > &c, const Array< T, 2 > &d)
 Computes the product of a vector and four matrices. More...
 
const Array< T, 2 > & matmul (const Array< T > &v, const Array< T, 2 > &a, const Array< T, 2 > &b, const Array< T, 2 > &c, const Array< T, 2 > &d, const Array< T > &w)
 Computes the matrix product of two vectors and four matrices. More...
 

Static Public Attributes

static const int LENGTH = N
 The length of the chain. More...
 

Detailed Description

template<class T, int N>
class jem::numeric::MatmulChain< T, N >

The template class MatmulChain can be used to compute the product of N matrices containing elements of type T. It can also be used to compute the product of N matrices and a vector, and the product of a vector, N matrices and a vector. Since a MatmulChain object stores any temporary matrices and vectors in private data members, it does not have to allocate and deallocate those temporary matrices and vectors for each product that it computes. As a consequence, a MatmuChain can be considerably faster than an equivalent series of nested numeric::matmul() calls, especially when the product of N matrices is computed repeatedly within a loop. This is illustrated in the example below:

MatmulChain<double,3> mc;
Array<double,2> a ( 10, 8 );
Array<double,2> b ( 8, 9 );
Array<double,2> c ( 9, 13 );
Array<double,2> r ( 10, 13 );
int i;
for ( i = 0; i < 1000; i++ )
{
// Fill a, b, and c ...
r = mc.matmul ( a, b, c );
// Do something with r ...
}

When using the matmul() function, the above loop could be coded as follows:

for ( i = 0; i < 1000; i++ )
{
r = numeric::matmul ( a, numeric::matmul( b, c ) );
}

In this case, however, two temporary matrices will be allocated and destroyed in each iteration of the loop.

The first template argument, T, specifies the type of the matrix and vector elements. The second template argument, N, specifies the length of a MatmulChain; that is, the number of matrices that are to be multiplied.

Note
The MatmulChain class is not thread safe.
Precondition
N >= 0 && N <= 4
See also
numeric::matmul()

Constructor & Destructor Documentation

template<class T , int N>
jem::numeric::MatmulChain< T, N >::MatmulChain ( )

Creates a new MatmulChain object that is ready for use.

Member Function Documentation

template<class T , int N>
const Array<T,2>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T > &  v,
const Array< T > &  w 
)

Returns a reference to a matrix containing the product of the vectors v and v. From a logical point of view, this function has the same effect as:

return numeric::matmul( v, w )

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length zero.

Parameters
v- a (column) vector.
w- a (row) vector.
Precondition
LENGTH == 0
Returns
A reference to a matrix containing the product of v and w.
template<class T , int N>
const Array<T>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T, 2 > &  a,
const Array< T > &  v 
)

Returns a reference to a vector containing the product of the matrix a and the vector v. From a logical point of view, this function has the same effect as:

return numeric::matmul( a, v )

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length one.

Parameters
a- a matrix.
v- a (column) vector.
Precondition
LENGTH == 1 &&
a.size(1) == v.size()
Returns
A reference to a vector containing the product of a and v.
template<class T , int N>
const Array<T>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T > &  v,
const Array< T, 2 > &  a 
)

Returns a reference to a (row) vector containing the product of the vector v and the matrix a. From a logical point of view, this function has the same effect as:

return numeric::matmul( v, a )

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length one.

Parameters
v- a (row) vector.
a- a matrix.
Precondition
LENGTH == 1 &&
v.size() == a.size(0)
Returns
A reference to a vector containing the product of v and a.
template<class T , int N>
const Array<T,2>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T > &  v,
const Array< T, 2 > &  a,
const Array< T > &  w 
)

Returns a reference to a matrix containing the product of the vector v, the matrix a and the vector w. From a logical point of view, this function has the same effect as:

return numeric::matmul( v, numeric::matmul( a, w )

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length one.

Parameters
v- a (row) vector.
a- a matrix.
w- a (column) vector.
Precondition
LENGTH == 1 &&
v.size() == a.size(0) &&
w.size() == a.size(1)
Returns
A reference to a matrix containing the product of v, a and w.
template<class T , int N>
const Array<T,2>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T, 2 > &  a,
const Array< T, 2 > &  b 
)

Returns a reference to a matrix containing the product of the matrices a and b. From a logical point of view, this function has the same effect as:

return numeric::matmul( a, b )

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length two.

Parameters
a- a matrix.
b- another matrix.
Precondition
LENGTH == 2 &&
a.size(1) == b.size(0)
Returns
A reference to a matrix containing the product of a and b.
template<class T , int N>
const Array<T>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T, 2 > &  a,
const Array< T, 2 > &  b,
const Array< T > &  v 
)

Returns a reference to a vector containing the product of the matrices a and b, and the vector v. From a logical point of view, this function has the same effect as:

return numeric::matmul( a, numeric::matmul( b, v ) )

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length two.

Parameters
a- a matrix.
b- another matrix.
v- a (column) vector.
Precondition
LENGTH == 2 &&
a.size(1) == b.size(0) &&
b.size(1) == v.size()
Returns
A reference to a vector containing the product of a, b and v.
template<class T , int N>
const Array<T>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T > &  v,
const Array< T, 2 > &  a,
const Array< T, 2 > &  b 
)

Returns a reference to a (row) vector containing the product of the vector v, and the matrices a and b. From a logical point of view, this function has the same effect as:

return numeric::matmul( numeric::matmul( v, a ), b )

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length two.

Parameters
v- a (row) vector.
a- a matrix.
b- another matrix.
Precondition
LENGTH == 2 &&
v.size() == a.size(0) &&
a.size(1) == b.size(0)
Returns
A reference to a vector containing the product of v, a and b.
template<class T , int N>
const Array<T,2>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T > &  v,
const Array< T, 2 > &  a,
const Array< T, 2 > &  b,
const Array< T > &  w 
)

Returns a reference to a matrix containing the product of the vector v, the matrices a and b, and the vector w. From a logical point of view, this function has the same effect as:

return numeric::matmul (
numeric::matmul ( v, a ),
numeric::matmul ( b, w )
)

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length two.

Parameters
v- a (row) vector.
a- a matrix.
b- another matrix.
w- a (column) vector.
Precondition
LENGTH == 2 &&
v.size() == a.size(0) &&
a.size(1) == b.size(0) &&
b.size(1) == w.size()
Returns
A reference to a matrix containing the product of v, a, b and w.
template<class T , int N>
const Array<T,2>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T, 2 > &  a,
const Array< T, 2 > &  b,
const Array< T, 2 > &  c 
)

Returns a reference to a matrix containing the product of the matrices a, b and c. From a logical point of view, this function has the same effect as:

return numeric::matmul( a, numeric::matmul( b, c ) )

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length three.

Parameters
a- a matrix.
b- a second matrix.
c- a third matrix.
Precondition
LENGTH == 3 &&
a.size(1) == b.size(0) &&
b.size(1) == c.size(0)
Returns
A reference to a matrix containing the product of a, b and c.
template<class T , int N>
const Array<T>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T, 2 > &  a,
const Array< T, 2 > &  b,
const Array< T, 2 > &  c,
const Array< T > &  v 
)

Returns a reference to a vector containing the product of the matrices a, b and c, and the vector v. From a logical point of view, this function has the same effect as:

return numeric::matmul (
a, numeric::matmul ( b, numeric::matmul( c, v ) )
);

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length three.

Parameters
a- a matrix.
b- a second matrix
c- a third matrix.
v- a (column) vector.
Precondition
LENGTH == 3 &&
a.size(1) == b.size(0) &&
b.size(1) == c.size(0) &&
c.size(1) == v.size()
Returns
A reference to a vector containing the product of a, b, c and v.
template<class T , int N>
const Array<T>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T > &  v,
const Array< T, 2 > &  a,
const Array< T, 2 > &  b,
const Array< T, 2 > &  c 
)

Returns a reference to a (row) vector containing the product of the vector v, and the matrices a, b and c. From a logical point of view, this function has the same effect as:

return numeric::matmul (
numeric::matmul ( numeric::matmul( v, a ), b ),
c
);

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length three.

Parameters
v- a (row) vector.
a- a matrix.
b- a second matrix
c- a third matrix.
Precondition
LENGTH == 3 &&
v.size() == a.size(0) &&
a.size(1) == b.size(0) &&
b.size(1) == c.size(0)
Returns
A reference to a vector containing the product of v, a, b and c.
template<class T , int N>
const Array<T,2>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T > &  v,
const Array< T, 2 > &  a,
const Array< T, 2 > &  b,
const Array< T, 2 > &  c,
const Array< T > &  w 
)

Returns a reference to a matrix containing the product of the vector v, the matrices a, b and c, and the vector w. From a logical point of view, this function has the same effect as:

return numeric::matmul (
numeric::matmul ( numeric::matmul( v, a ), b ),
numeric::matmul ( c, w )
);

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length three.

Parameters
v- a (row) vector.
a- a matrix.
b- a second matrix
c- a third matrix.
w- a (column) vector.
Precondition
LENGTH == 3 &&
v.size() == a.size(0) &&
a.size(1) == b.size(0) &&
b.size(1) == c.size(0) &&
c.size(1) == w.size()
Returns
A reference to a matrix containing the product of v, a, b, c and w.
template<class T , int N>
const Array<T,2>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T, 2 > &  a,
const Array< T, 2 > &  b,
const Array< T, 2 > &  c,
const Array< T, 2 > &  d 
)

Returns a reference to a matrix containing the product of the matrices a, b, c and d. From a logical point of view, this function has the same effect as:

return numeric::matmul (
a, numeric::matmul( b, numeric::matmul( c, d ) )
);

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length four.

Parameters
a- a matrix.
b- a second matrix.
c- a third matrix.
d- a fourth matrix.
Precondition
LENGTH == 4 &&
a.size(1) == b.size(0) &&
b.size(1) == c.size(0) &&
c.size(1) == d.size(0)
Returns
A reference to a matrix containing the product of a, b, c and d.
template<class T , int N>
const Array<T>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T, 2 > &  a,
const Array< T, 2 > &  b,
const Array< T, 2 > &  c,
const Array< T, 2 > &  d,
const Array< T > &  v 
)

Returns a reference to a vector containing the product of the matrices a, b, c and d, and the vector v. From a logical point of view, this function has the same effect as:

return numeric::matmul (
a, numeric::matmul (
b, numeric::matmul( c, numeric::matmul( d, v ) )
)
);

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length four.

Parameters
a- a matrix.
b- a second matrix
c- a third matrix.
d- a fourth matrix.
v- a (column) vector.
Precondition
LENGTH == 4 &&
a.size(1) == b.size(0) &&
b.size(1) == c.size(0) &&
c.size(1) == d.size(0) &&
d.size(1) == v.size()
Returns
A reference to a vector containing the product of a, b, c, d and v.
template<class T , int N>
const Array<T>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T > &  v,
const Array< T, 2 > &  a,
const Array< T, 2 > &  b,
const Array< T, 2 > &  c,
const Array< T, 2 > &  d 
)

Returns a reference to a (row) vector containing the product of the vector v and the matrices a, b, c and d. From a logical point of view, this function has the same effect as:

return numeric::matmul (
numeric::matmul (
numeric::matmul ( numeric::matmul( v, a ), b ), c
),
d
);

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length four.

Parameters
v- a (row) vector.
a- a matrix.
b- a second matrix
c- a third matrix.
d- a fourth matrix.
Precondition
LENGTH == 4 &&
v.size() == a.size(0) &&
a.size(1) == b.size(0) &&
b.size(1) == c.size(0) &&
c.size(1) == d.size(0)
Returns
A reference to a vector containing the product of v, a, b, c and d.
template<class T , int N>
const Array<T,2>& jem::numeric::MatmulChain< T, N >::matmul ( const Array< T > &  v,
const Array< T, 2 > &  a,
const Array< T, 2 > &  b,
const Array< T, 2 > &  c,
const Array< T, 2 > &  d,
const Array< T > &  w 
)

Returns a reference to a matrix containing the product of the vector v, the matrices a, b, c and d, and the vector w. From a logical point of view, this function has the same effect as:

return numeric::matmul (
numeric::matmul ( numeric::matmul( v, a ), b ),
numeric::matmul ( c, numeric::matmul( d, w ) )
);

The returned reference is valid until this function is called again or until this MatmulChain object is destroyed.

This function is only available if this matmul chain has length four.

Parameters
v- a (row) vector.
a- a matrix.
b- a second matrix
c- a third matrix.
d- a fourth matrix.
w- a (column) vector.
Precondition
LENGTH == 4 &&
v.size() == a.size(0) &&
a.size(1) == b.size(0) &&
b.size(1) == c.size(0) &&
c.size(1) == d.size(0) &&
d.size(1) == w.size()
Returns
A reference to a matrix containing the product of v, a, b, c, d and w.

Member Data Documentation

template<class T , int N>
const int jem::numeric::MatmulChain< T, N >::LENGTH = N
static

A constant integer representing the length of this chain. It is equal to the second template parameter.

Generated on Fri Jun 19 2015 09:52:50 by Doxygen