lti::tensor< T > Class Template Reference
[Aggregate Data Types]

Tensor template class. More...

#include <ltiTensor.h>

Inheritance diagram for lti::tensor< T >:

[legend]

Collaboration diagram for lti::tensor< T >:

[legend]

List of all members.

Public Types
typedef vector< T >::iterator	iterator
typedef vector< T >::const_iterator	const_iterator
Public Member Functions
	tensor ()
	tensor (const int &order, const int &elements)
	tensor (const int &order, const ivector &elements)
	tensor (const tensor< T > &other)
virtual	~tensor ()
const char *	getTypeName () const
int	order () const
const int &	elementsInDimension (const int &dimension) const
const ivector &	elementsPerDimension () const
const ivector &	getFirstIndex () const
const ivector &	getLastIndex () const
const_iterator	begin () const
iterator	begin ()
const_iterator	end () const
iterator	end ()
void	resize (const int &order, const int &elements, const T &initValue=T(), const bool &copyData=false, const bool &initData=true)
void	resize (const int &order, const ivector &elements, const T &initValue=T(), const bool &copyData=false, const bool &initData=true)
void	detach (tensor< T > &receiver)
void	clear ()
void	fill (const T &value=T(0))
void	fill (const T &iniValue, const ivector &from, const ivector &to)
const T &	at (const ivector &x) const
T &	at (const ivector &x)
T &	at ()
const T &	at () const
T &	at (const int &x)
const T &	at (const int &x) const
T &	at (const int &x, const int &y)
const T &	at (const int &x, const int &y) const
T &	at (const int &x, const int &y, const int &z)
const T &	at (const int &x, const int &y, const int &z) const
tensor< T > &	copy (const tensor< T > &other)
template<class U >
tensor< T > &	castFrom (const tensor< U > &other)
virtual mathObject *	clone () const
bool	equals (const tensor< T > &other) const
bool	operator== (const tensor< T > &other) const
bool	prettyCloseTo (const tensor< T > &other, const T &tolerance) const
tensor< T > &	operator= (const tensor< T > &other)
tensor< T > &	apply (T(*function)(T))
tensor< T > &	apply (T(*function)(const T &))
tensor< T > &	emultiply (const tensor< T > &other)
tensor< T > &	emultiply (const tensor< T > &first, const tensor< T > &second)
tensor< T > &	add (const tensor< T > &other)
tensor< T > &	add (const tensor< T > &first, const tensor< T > &second)
tensor< T > &	operator+= (const tensor< T > &other)
tensor< T > &	subtract (const tensor< T > &other)
tensor< T > &	subtract (const tensor< T > &first, const tensor< T > &second)
tensor< T > &	operator-= (const tensor< T > &other)
tensor< T > &	multiply (const T &cst)
tensor< T > &	multiply (const tensor< T > &other, const T &cst)
tensor< T > &	operator*= (const T &cst)
tensor< T > &	divide (const T &cst)
tensor< T > &	divide (const tensor< T > &other, const T &cst)
tensor< T > &	add (const T &cst)
tensor< T > &	operator+= (const T &cst)
tensor< T > &	add (const tensor< T > &other, const T &cst)
virtual bool	write (ioHandler &handler, const bool complete=true) const
virtual bool	read (ioHandler &handler, const bool complete=true)
Protected Attributes
int	totalNumberOfElements
int	theOrder
vector< T >	theElements
ivector	theElementsPerDimension
ivector	firstIndex
ivector	lastIndex

Detailed Description

template<class T>
class lti::tensor< T >

Tensor template class.

The lti::tensor template container class allows the generation multidimensional tables. If you only need first or second order tensors, please use the lti::vector and lti::matrix instead (they are more efficient!).

The elements of the tensor will be indexed in each dimension i between 0 an $n_i-1$ .

Example:

    lti::tensor<float> hist(3,10); // creates a 3rd order tensor with 10
                                   // elements pro dimension.  The total
                                   // number of elements is 10^3=1000

To read the content of a tensor element use the access operator at().

For tensors with order 0, the number of elements per dimension will be ignored.

Member Typedef Documentation

template<class T>

typedef vector<T>::const_iterator lti::tensor< T >::const_iterator

The const_iterator is equivalent to a lti::vector<T>::const_iterator.

template<class T>

typedef vector<T>::iterator lti::tensor< T >::iterator

The iterator is equivalent to a lti::vector<T>::iterator.

Constructor & Destructor Documentation

template<class T>

lti::tensor< T >::tensor ( )

default constructor creates an empty tensor.

template<class T>

lti::tensor< T >::tensor	(	const int &	order,
		const int &	elements
	)

create a tensor of the given order.

Each "dimension" will have the given number of elements, i.e. the tensor will have $elements^{dimensions}$ elements.

For tensors with order 0, the number of elements per dimension will be ignored.

Parameters:

	order	the order of the tensor.
	elements	the number of elements per dimension.

template<class T>

lti::tensor< T >::tensor	(	const int &	order,
		const ivector &	elements
	)

create a tensor of the given order.

Each "dimension" i will have the number of elements indicated in the i-th element of the vector elements.

If the order differs from the size of the given vector, the number of elements for the dimension i will be given by $dim_i = elements[i \, mod \, elements.size()]$ .

This means, if you want a 6th-order tensor, and your elements-vector has only three elements [10,15,5], the number of elements per dimension will be [10,15,5,10,15,5]

For tensors with order 0, the number of elements per dimension will be ignored.

Parameters:

	order	the order of the tensor
	elements	a vector with the number of elements per dimension

template<class T>

lti::tensor< T >::tensor ( const tensor< T > & other )

create this tensor as a copy of another tensor

Parameters:

other

the tensor to be copied.

template<class T>

virtual lti::tensor< T >::~tensor ( ) [virtual]

destructor

Member Function Documentation

template<class T>

tensor<T>& lti::tensor< T >::add	(	const tensor< T > &	other,
		const T &	cst
	)

Add constant to the other tensor and leave the result here.

Returns a reference to this tensor.

Parameters:

	other	the oder tensor
	cst	constant scala to be added with each element of the other tensor

Returns:: a reference to the actual tensor

template<class T>

tensor<T>& lti::tensor< T >::add ( const T & cst )

Add constant to this tensor.

This tensor is changed. Returns this tensor.

Parameters:

cst

constant scala to be added with each element

Returns:: a reference to the actual tensor

template<class T>

tensor<T>& lti::tensor< T >::add	(	const tensor< T > &	first,
		const tensor< T > &	second
	)

Add two tensor and leave the result in this object.

Parameters:

	first	the first tensor.
	second	the second tensor will be added with the first tensor

Returns:: a reference to the actual tensor

template<class T>

tensor<T>& lti::tensor< T >::add ( const tensor< T > & other )

Add another tensor of the same type and same order and leave the result in this object.

Parameters:

other

the other tensor to be added with

Returns:: a reference to the actual tensor

Referenced by lti::tensor< T >::operator+=().

template<class T>

tensor<T>& lti::tensor< T >::apply ( T(*)(const T &) function )

applies a C-function to each element of the tensor.

Parameters:

function

a pointer to a C-function

Returns:: a reference to the actual tensor

template<class T>

tensor<T>& lti::tensor< T >::apply ( T(*)(T) function )

applies a C-function to each element of the tensor.

Parameters:

function

a pointer to a C-function

Returns:: a reference to the actual tensor

template<class T>

const T& lti::tensor< T >::at	(	const int &	x,
		const int &	y,
		const int &	z
	)			const

overload of the at() operator for third-order tensors.

This method is provided as a shortcut to avoid creating a vector with only three elements to access the third-order tensor. If used with tensors of orders other than three, an assertion will be thrown (in debug mode) or an undefined behaviour must be expected (in release mode).

Parameters:

	x	equivalent to the first element of an index vector.
	y	equivalent to the second element of an index vector.
	z	equivalent to the third element of an index vector.

template<class T>

T& lti::tensor< T >::at	(	const int &	x,
		const int &	y,
		const int &	z
	)

overload of the at() operator for third-order tensors.

This method is provided as a shortcut to avoid creating a vector with only three elements to access the third-order tensor. If used with tensors of orders other than three, an assertion will be thrown (in debug mode) or an undefined behaviour must be expected (in release mode).

Parameters:

	x	equivalent to the first element of an index vector.
	y	equivalent to the second element of an index vector.
	z	equivalent to the third element of an index vector.

template<class T>

const T& lti::tensor< T >::at	(	const int &	x,
		const int &	y
	)			const

overload of the at() operator for second-order tensors.

This method is provided as a shortcut to avoid creating a vector with only two elements to access the second-order tensor. If used with tensors of orders other than two, an assertion will be thrown (in debug mode) or an undefined behaviour must be expected (in release mode).

Parameters:

	x	equivalent to the first element of an index vector.
	y	equivalent to the second element of an index vector.

template<class T>

T& lti::tensor< T >::at	(	const int &	x,
		const int &	y
	)

overload of the at() operator for second-order tensors.

This method is provided as a shortcut to avoid creating a vector with only two elements to access the second-order tensor. If used with tensors of orders other than two, an assertion will be thrown (in debug mode) or an undefined behaviour must be expected (in release mode).

Parameters:

	x	equivalent to the first element of an index vector.
	y	equivalent to the second element of an index vector.

template<class T>

const T& lti::tensor< T >::at ( const int & x ) const

overload of the at() operator for first-order tensors.

This method is provided as a shortcut to avoid creating a vector with only one element to access the first-order tensor. If used with tensors of orders other than one, an assertion will be thrown (in debug mode) or an undefined behaviour must be expected (in release mode).

Parameters:

x

equivalent to the first element of an index vector.

template<class T>

T& lti::tensor< T >::at ( const int & x )

overload of the at() operator for first-order tensors.

This method is provided as a shortcut to avoid creating a vector with only one element to access the first-order tensor. If used with tensors of orders other than one, an assertion will be thrown (in debug mode) or an undefined behaviour must be expected (in release mode).

Parameters:

x

equivalent to the first element of an index vector.

template<class T>

const T& lti::tensor< T >::at ( ) const

overload of the at() operator for zero-order tensors.

This method is provided as a shortcut to avoid creating an empty vector to access the zero-order tensor. If used with tensors of orders other than zero, an assertion will be thrown (in debug mode) or an undefined behaviour must be expected (in release mode).

template<class T>

T& lti::tensor< T >::at ( )

overload of the at() operator for zero-order tensors.

This method is provided as a shortcut to avoid creating an empty vector to access the zero-order tensor. If used with tensors of orders other than zero, an assertion will be thrown (in debug mode) or an undefined behaviour must be expected (in release mode).

template<class T>

T& lti::tensor< T >::at ( const ivector & x )

access element x of the tensor

Parameters:

x

index of the tensor element to be accessed. It should be between getFirstIndex() and getLastIndex()

Returns:: a reference to the element at index x.

template<class T>

const T& lti::tensor< T >::at ( const ivector & x ) const

read-only access to the element x of the tensor

Parameters:

x

index of the tensor element to be accessed. It should be between getFirstIndex() and getLastIndex()

Returns:: a read-only reference to the element at index x.

template<class T>

iterator lti::tensor< T >::begin ( ) [inline]

returns an iterator pointing to the first element of the tensor.

The use of the interators is similar to the iterators of the Standard Template Library (STL).

If you need to iterate on all elements of the tensor, you can use following code:

   int tmp,accu;                      // a temporal variable
   lti::tensor<float> myTensor(3,10); // a 3rd order tensor with
                                      // 10 elements/dim. (of type float)
   lti::tensor<float>::iterator it;   // an iterator

   for (it=myTensor.begin();it!=myTensor.end();it++) {
     tmp = *it;                       // tmp has value of element pointed
                                      // by the iterator.
     accu += tmp;
     (*it) = accu;                    // change the value in the tensor.
   }

Please note that if you define it as a const_iterator, you can not make something like *it=accu.

References lti::tensor< T >::theElements.

template<class T>

const_iterator lti::tensor< T >::begin ( ) const [inline]

returns an iterator pointing to the first element.

Note that you can not change the values of the tensor elements when you use a const_iterator. See also begin()

References lti::tensor< T >::theElements.

Referenced by lti::tensor< T >::castFrom().

template<class T>

template<class U >

tensor<T>& lti::tensor< T >::castFrom ( const tensor< U > & other ) [inline]

copy the other tensor by casting each of its elements

Parameters:

other

The tensor to be casted

References lti::tensor< T >::begin(), lti::tensor< T >::elementsPerDimension(), lti::tensor< T >::end(), and lti::tensor< T >::resize().

template<class T>

void lti::tensor< T >::clear ( )

equivalent to resize(-1,0);

template<class T>

virtual mathObject* lti::tensor< T >::clone ( ) const [virtual]

create a clone of this tensor

Returns:: a pointer to a copy of this tensor

Implements lti::mathObject.

template<class T>

tensor<T>& lti::tensor< T >::copy ( const tensor< T > & other )

assigment operator.

copy the contents of other in this object.

Parameters:

other

the source tensor to be copied.

Returns:: a reference to this object

Reimplemented from lti::ioObject.

Referenced by lti::tensor< T >::operator=().

template<class T>

void lti::tensor< T >::detach ( tensor< T > & receiver )

transfer the data of this object into the receiver, leaving this vector empty and the receiver as if a copy were done.

This function makes a "memory block transfusion" to another tensor. It is a very efficient way to make a copy of this tensor, if you don't need the source data anymore!

At the end of the detachment, this tensor will be empty.

Parameters:

receiver

the tensor that will receive the data

template<class T>

tensor<T>& lti::tensor< T >::divide	(	const tensor< T > &	other,
		const T &	cst
	)

Divide the other tensor with a constant and leave the result here.

Returns a reference to this tensor.

Parameters:

	other	the tensor to be divide by the constant value
	cst	the elements of the tensor will be divided with this constant

Returns:: a reference to the actual tensor

template<class T>

tensor<T>& lti::tensor< T >::divide ( const T & cst )

Divide this tensor with a constant.

Returns this tensor.

Parameters:

cst

the elements of the tensor will be divided with this constant

Returns:: a reference to the actual tensor

template<class T>

const int& lti::tensor< T >::elementsInDimension ( const int & dimension ) const [inline]

get the number of elements of the dimension dim

Parameters:

dimension

the index of the dimension to be checked

Returns:: the number of elements of the dimension specified by dim

template<class T>

const ivector& lti::tensor< T >::elementsPerDimension ( ) const [inline]

get the number of elements per dimension

Referenced by lti::tensor< T >::castFrom().

template<class T>

tensor<T>& lti::tensor< T >::emultiply	(	const tensor< T > &	first,
		const tensor< T > &	second
	)

Elementwise multiplication.

This tensor will contain the elementwise multiplication of the elements in first and second.

Parameters:

	first	the first tensor
	second	the second tensor will be multiplied with the first tensor

Returns:: a reference to the actual tensor

template<class T>

tensor<T>& lti::tensor< T >::emultiply ( const tensor< T > & other )

Elementwise multiplication.

Each element of this tensor will be multiplied with the elements of the other tensor and the result will be left in this object!

Parameters:

other

the other tensor to be multiplied with

Returns:: a reference to the actual tensor

template<class T>

iterator lti::tensor< T >::end ( ) [inline]

returns last index as an iterator For an example see begin()

References lti::tensor< T >::theElements.

template<class T>

const_iterator lti::tensor< T >::end ( ) const [inline]

returns last index as a const iterator.

For an example see begin()

References lti::tensor< T >::theElements.

Referenced by lti::tensor< T >::castFrom().

template<class T>

bool lti::tensor< T >::equals ( const tensor< T > & other ) const

compare this tensor with another one.

Parameters:

other

the other tensor to be compared with

Returns:: true if both tensors have the same elements and same size

Referenced by lti::tensor< T >::operator==().

template<class T>

void lti::tensor< T >::fill	(	const T &	iniValue,
		const ivector &	from,
		const ivector &	to
	)

fills the tensor elements with iniValue between the n-dimensional points from and to.

Parameters:

	iniValue	the elements will be initialized with this value.
	from	first element index
	to	last element index

If from or to are out of bounds, they will be (internaly) adjusted to a correct value.

Example:

   lti::tensor<float> t(1,10);    // first order tensor with 10 elements
   t.clear();
   t.fill(9.0f,ivector(1,1),ivector(1,3)); // hist=[0,9,9,9,0,0,0,0,0,0]

template<class T>

void lti::tensor< T >::fill ( const T & value = T(0) )

initialize all elements of the tensor with 0 (or another specified number).

template<class T>

const ivector& lti::tensor< T >::getFirstIndex ( ) const [inline]

returns a vector with the index of the first element of the tensor (usually every element of the vector is 0)

template<class T>

const ivector& lti::tensor< T >::getLastIndex ( ) const [inline]

returns a vector with the index to the last element of the tensor (usually is the value returned by elementsPerDimension() minus (1,1,..1)

template<class T>

const char* lti::tensor< T >::getTypeName ( void ) const [inline, virtual]

returns the name of this class: "tensor"

Reimplemented from lti::mathObject.

template<class T>

tensor<T>& lti::tensor< T >::multiply	(	const tensor< T > &	other,
		const T &	cst
	)

Multiply the other tensor with a constant and leave the result here.

Returns a reference to this tensor.

Parameters:

	other	the other tensor to be multiplied with the constant value
	cst	constant scalar to be multiplied with the other tensor.

Returns:: a reference to the actual tensor

template<class T>

tensor<T>& lti::tensor< T >::multiply ( const T & cst )

Multiply this tensor with a constant.

Returns this tensor.

Parameters:

cst

constant scalar to be multiplied with

Returns:: a reference to the actual tensor

Referenced by lti::tensor< T >::operator*=().

template<class T>

tensor<T>& lti::tensor< T >::operator*= ( const T & cst ) [inline]

alias for multiply(const T& cst)

Parameters:

cst

constant scalar to be multiplied with

Returns:: a reference to the actual tensor

References lti::tensor< T >::multiply().

template<class T>

tensor<T>& lti::tensor< T >::operator+= ( const T & cst ) [inline]

Alias for add(const T& cst).

References lti::tensor< T >::add().

template<class T>

tensor<T>& lti::tensor< T >::operator+= ( const tensor< T > & other ) [inline]

Alias for add(const tensor& other).

References lti::tensor< T >::add().

template<class T>

tensor<T>& lti::tensor< T >::operator-= ( const tensor< T > & other ) [inline]

Alias for substract(const tensor& other).

References lti::tensor< T >::subtract().

template<class T>

tensor<T>& lti::tensor< T >::operator= ( const tensor< T > & other ) [inline]

assigment operator (alias for copy(other)).

Parameters:

other

the tensor to be copied

Returns:: a reference to the actual tensor

Reimplemented from lti::ioObject.

References lti::tensor< T >::copy().

template<class T>

bool lti::tensor< T >::operator== ( const tensor< T > & other ) const [inline]

compare this tensor with other

Parameters:

other

the other tensor to be compared with

Returns:: true if both tensors have the same elements and same size

References lti::tensor< T >::equals().

template<class T>

int lti::tensor< T >::order ( ) const [inline]

returns the order of this tensor

template<class T>

bool lti::tensor< T >::prettyCloseTo	(	const tensor< T > &	other,
		const T &	tolerance
	)			const

compare this tensor with another one, and use the given tolerance to determine if the value of each element of the other tensor approximately equals the values of the actual tensor elements.

An element x is approximately equal to another element y with a tolerance t, if following equation holds: x-t < y < x+t

Parameters:

	other	the other tensor to be compared with
	tolerance	the tolerance to be used

Returns:: true if both tensors are approximatly equal

template<class T>

virtual bool lti::tensor< T >::read	(	ioHandler &	handler,
		const bool	complete = `true`
	)			`[virtual]`

read the object from the given ioHandler

Reimplemented from lti::mathObject.

Referenced by lti::read().

template<class T>

void lti::tensor< T >::resize	(	const int &	order,
		const ivector &	elements,
		const T &	initValue = `T()`,
		const bool &	copyData = `false`,
		const bool &	initData = `true`
	)

change the order and number of elements per dimension of the tensor.

All data will be lost!

For tensors with order 0, the number of elements per dimension will be ignored.

Parameters:

	order	the new order of the tensor
	elements	the number of elements per dimension
	initValue	value to be copied at each element of the tensor if the initData parameter is true
	copyData	copy the old data into the new tensor (WARNING: Not implemented yet! (i.e. only false is correctly interpreted)
	initData	initialize all data in the tensor with the value specified in initValue.

template<class T>

void lti::tensor< T >::resize	(	const int &	order,
		const int &	elements,
		const T &	initValue = `T()`,
		const bool &	copyData = `false`,
		const bool &	initData = `true`
	)

change the order and number of elements per dimension of the tensor.

All data will be lost!

For tensors with order 0, the number of elements per dimension will be ignored.

Parameters:

	order	the new order of the tensor
	elements	the number of elements per dimension
	initValue	value to be copied at each element of the tensor if the initData parameter is true
	copyData	copy the old data into the new tensor (WARNING: Not implemented yet! (i.e. only false is correctly interpreted))
	initData	initialize all data in the tensor with the value specified in initValue.