PARP Research Group Universidad de Murcia

QVTensor Class Reference
[Math functionality]

Implementation of tensors, a generalization for matrices and vectors. More...

#include <QVTensor>

List of all members.

Public Member Functions

 QVTensor (const QVTensor &tensor)
 Copy constructor.
 QVTensor (const QVTensorValence &indexList=QVTensorValence())
 Index list constructor.
bool operator== (const QVTensor &tensor) const
 Compare operator for tensors.
bool operator!= (const QVTensor &tensor) const
 Compare operator for tensors.
QVTensor operator* (const QVTensor &tensor) const
 Tensor product.
QVTensor operator+ (const QVTensor &tensor) const
 Tensor add.
QVTensor operator- (const QVTensor &tensor) const
 Tensor substraction.
QVTensor operator^ (const QVTensor &tensor) const
 Outer product.
QVTensor operator() (const QVTensorValence &indexList) const
 Index renaming and contracting operator.
int getDataSize () const
 Gets the size of the data array.
const double * getReadData () const
 Gets a read-only reference to the data buffer of the tensor.
double * getWriteData ()
 Gets a reference of the data buffer of the tensor for read and write accesses.
QVTensorValence getValence () const
 Gets valence of the tensor.
QVTensor slice (const QVTensorIndexValues &indexRangeList) const
 Get a subtensor from a tensor.
QVTensor transpose (const QVTensorValence &indexList) const
 Change the order of the indexes in the tensor.
QVTensor transpose (const QVTensorIndex &i, const QVTensorIndex &j) const
 Overloaded version of transpose function.
QVTensor add (const QVTensor &tensor) const
 Tensor add.
QVTensor substract (const QVTensor &tensor) const
 Tensor substraction.
QVTensor tensorProduct (const QVTensor &tensor) const
 Obtains the tensor product of two tensors.
QVTensor innerProduct (const QVTensor &tensor) const
 Obtains the inner product of two tensors.
QVTensor outerProduct (const QVTensor &tensor) const
 Obtains the outer product of two tensors.
bool equals (const QVTensor &tensor) const
 Check equivalence between tensors.
QVTensor renameIndexes (const QVTensorValence &indexList) const
 Index renaming and contracting.
QVTensorIndexator getIndexator ()
 Gets tensor indexator.
double norm2 () const
 Gets the norm2 for tensor.

Static Public Member Functions

static QVTensor leviCivita (const int dimension)
 Gets Levi Civita symbol tensor.

Detailed Description

Implementation of tensors, a generalization for matrices and vectors.

Opossed to scalar values, vector and matrices contain numeric values indexed by one and two index values respectively. A tensor is a generalization of these concepts, that can contain numeric values indexed by a set of fixed indexes.

Tensor creation

Tensors are created using index objects. These index objects are created using the class QVTensorIndex , indicating their size. An example of tensor creation follows:

QVTensorIndex i = 10, j = 20, k = 7;
QVTensor A( i * j * k );

[...]

Indexes i, j and k have respectively sizes 10, 20, and 7, so tensor A will have 10x20x7 elements, and tree dimensions, of sizes 10, 20 and 7 each one. It is shown that QVTensorIndex objects are composed using * operator, to express the valence of the tensor.

Method cov() from the QVTensorIndex class can be used to get a covariant version of an index. So, for example, we can create a second tensor B, similar to A, but with covariant index j, like this:

QVTensorIndex i = 10, j = 20, k = 7;
QVTensor A( i * j * k );

[...]

QVTensor B( i * j.cov() * k );

An index can be copied to another one, both becoming interchangeable and indistinguishable. For example, with the following code:

QVTensorIndex i = 10, j = 20, k = 7, i2 = i, j2 = j.cov().cov(), k2 = k, jCov = j.cov();
QVTensor A( i * j * k ), B( i2 * j2.cov() * k2 ), C( i2 * jCov * k );

Tensors A, B and C will have the same valence, and will behave the same for tensor product, and contraction operations. Also notice that index j is equivalent to index j.cov().cov(), because applying double covariance to an index returns the original index.

Slice operation

Method slice is the equivalent to a submatrix extractor, for tensors. It can be used to extract sub-tensors from tensors, specifying a value, or a list of values, for the indexes. For example, in this code:

QVTensorIndex i = 10, j = 20, k = 7, l = 10;
QVTensor A( i * j.cov() * k.cov() * l);

[...]

QVTensor B = A(i[10]);

tensor B will contain all the values of tensor A, for which index i equals the value 10. So, tensor B will have only tree indexes, covariated j, covariated k, and l. It can be specified several values for the same index, using operator &, like this:

QVTensorIndex i = 10, j = 20, k = 7, l = 10;
QVTensor A( i * j.cov() * k.cov() * l);

[...]

QVTensor B = A(i[10] & i[5] & i[0]);

in this case, tensor B will be a fourth-dimensional tensor, with same valence as tensor A, only that it will have three elements for index i. For multiple value slicing, it can be useful the method range from the class QVTensorIndex:

QVTensorIndex i = 10, j = 20, k = 7, l = 10;
QVTensor A( i * j.cov() * k.cov() * l);

[...]

QVTensor B = A(i.range(2,5));

it selects in the slice operation all the values from 2 to 5, for the index i. Also, slicing for multiple indexes can be done, combining values for the different indexes in the same slice operation, for example, in the following code:

QVTensorIndex i = 10, j = 20, k = 7;
QVTensor A( i * j.cov() * k ), B;

[...]

B = A(i[10] & i.range(3,5) & j[3] & j[1] & j.range(0,1));

tensor B will keep all the values from tensor A, for which index i equals 10, 3, 4 and 5, index j equals 3, 1, 0, and 1.

Transpose operation

Method transpose works like a transpose operation for matrices, over tensors. It can swap the location for two indexes in the valence of the tensor, or re-order their locations at will. Two versions of method transpose are provided: the first one takes as argument the valence for the resulting tensor, as it is specified in the constructor, as commented in the Tensor creation section:

QVTensorIndex i = 10, j = 20, k = 10;
QVTensor A( i * j * k ), B;

[...]

B = A.transpose( k * j * i.cov() );

This can transpose indexes in the tensor in any order, depending on the order in the valence. The second version is used as follows:

QVTensorIndex i = 10, j = 20, k = 10;
QVTensor A( i * j * k ), B;

[...]

B = A.transpose( i, k );

It takes two indexes, and swap their positions, leaving the rest of the indexes at the same place.

Tensor contraction

The operator () defined in tensors can be used to obtain the contraction of a tensor. The tensor should have two indexes with same size and one of them should be covariant, and the other one contravariant. The following code is an example of the use of this operator:

QVTensorIndex i = 10, j = 20, k = 10;
QVTensor A( i * j * k.cov() ), B;

[...]

B = A( i * j * i.cov() );

This makes B a tensor with one dimension of size 20 (corresponding to index j), which is obtained contracting indexes i and k from tensor A. Contraction can be done over multiple indexes at a time. For example, the following code will be correct:

QVTensorIndex i = 10, j = 20, k = 10, l = 7, m = 20;
QVTensor A( i * j * k.cov() * l * m.cov() ), B;

[...]

B = A( i * j * i.cov() * l * j.cov() );

This contracts indexes i and k, j and m from tensor A, and store the result in tensor B.

Tensor product

Tensor product can be commonly done with operator *. It performs an inner product between both operand tensors, and contracts the indexes of the resulting tensor:

QVTensorIndex i = 10, j = 20, k = 10, l = 14;
QVTensor A( i * j * k.cov() ), B(l * i.cov() * k);

[...]

QVTensor C = A( i * j * k.cov() ) * B(l * i.cov() * k);

The operator () can be used to specify the contracting indexes in the operation ex professo, if both tensors were constructed with different indexes. For example, the following code would create a tensor contracting the same indexes as the previous code did:

QVTensorIndex i = 10, j = 20, k = 10, l = 14, m = 20, n = 10;
QVTensor A( i * j * k.cov() ), B(l * m.cov() * n);

[...]

QVTensorIndex i1 = 10, i2 = 20, i3 = 10, i4;
QVTensor C = A( i1 * i2 * i3.cov() ) * B(i4 * i1.cov() * i3);

Data accessing

Tensor copying uses copy-on-write policy for its data buffer. This means that when performed a copy from one vector object over another, both objects will share the same data buffer, until a write operation is attempted over the data of one of them. In that case it is necesary to dupe the data, and let each tensor object to have its own copy of the data before the write operation takes place, to avoid writing operations to replicate changes at tensors supposedly different.

So, tensors have two operations to access to their data. One gets the data buffer for read accesses, not duplicating the data buffer if it is shared, and the other one allows writing on the data of the tensor, duping the data buffer if it is shared beforehand.

Method getReadData returns a read only pointer to the data buffer. It can be used to read values on the elements of the tensor. Method getDataSize returns the number of elements contained in the tensor. An example usage of both methods:

QVTensorIndex i = 10, j = 20, k = 10, l = 14, m = 20, n = 10;
QVTensor A( i * j * k.cov() );

[...]

// gets the sum of all the elements on tensor A
const double sum = 0, *data = A.getReadData();
for (int n = 0; n < A.getDataSize(); n++)
    sum += data[i];

[...]

Method getWriteData can be used to get a writable pointer to the data buffer. An example usage:

QVTensorIndex i = 10, j = 20, k = 10, l = 14, m = 20, n = 10;
QVTensor A( i * j * k.cov() );

[...]

// multiplies by a factor, and decrements it by one unit, each element of the tensor A.
double *data = A.getWriteData();
for (int n = 0; n < A.getDataSize(); n++)
    data[i] = 2*data[i] + 1;

[...]

Definition at line 234 of file qvtensor.h.

Constructor & Destructor Documentation

QVTensor::QVTensor ( const QVTensor &  tensor  )  [inline]

Copy constructor.

Creates a tensor object and copy the valence and data from a given one.

Definition at line 242 of file qvtensor.h.

QVTensor::QVTensor ( const QVTensorValence &  indexList = QVTensorValence()  )  [inline]

Index list constructor.

Creates a new tensor from a given valence, represented by a QVTensorIndex list. See TensorUsage section for a detailed description about its usage.

Parameters:
indexList a QVTensorValence, created from a list of QVTensorIndex objects.
Todo:
check that no indexes are repeated in the indexList, even covariated ones

Definition at line 250 of file qvtensor.h.

Member Function Documentation

bool QVTensor::operator== ( const QVTensor &  tensor  )  const [inline]

Compare operator for tensors.

Parameters:
tensor operand for the compare operation.
Returns:
true if valence and data are equal of both tensors, else false.

Definition at line 269 of file qvtensor.h.

bool QVTensor::operator!= ( const QVTensor &  tensor  )  const [inline]

Compare operator for tensors.

Parameters:
tensor operand for the compare operation.
Returns:
false if valence and data are equal of both tensors, else true.

Definition at line 275 of file qvtensor.h.

QVTensor QVTensor::operator* ( const QVTensor &  tensor  )  const [inline]

Tensor product.

Parameters:
tensor operand for the product operation.
See also:
tensorProduct

Definition at line 281 of file qvtensor.h.

QVTensor QVTensor::operator+ ( const QVTensor &  tensor  )  const [inline]

Tensor add.

Parameters:
tensor operand for the add operation.
See also:
add

Definition at line 287 of file qvtensor.h.

QVTensor QVTensor::operator- ( const QVTensor &  tensor  )  const [inline]

Tensor substraction.

Parameters:
tensor subtrahend for the operation.
See also:
substract

Definition at line 293 of file qvtensor.h.

QVTensor QVTensor::operator^ ( const QVTensor &  tensor  )  const [inline]

Outer product.

See also:
outerProduct(const QVTensor &tensor) const

Definition at line 298 of file qvtensor.h.

QVTensor QVTensor::operator() ( const QVTensorValence &  indexList  )  const [inline]

Index renaming and contracting operator.

See sections Tensor contraction and Tensor product for usage of this operator.

See also:
renameIndexes

Definition at line 304 of file qvtensor.h.

int QVTensor::getDataSize (  )  const [inline]

Gets the size of the data array.

This returns the number of elements in the tensor.

Returns:
the product of the sizes of all the indexes in the tensor.

Definition at line 312 of file qvtensor.h.

Referenced by add(), equals(), innerProduct(), leviCivita(), norm2(), substract(), and tensorProduct().

const double* QVTensor::getReadData (  )  const [inline]

Gets a read-only reference to the data buffer of the tensor.

Returns:
a constant pointer to the data buffer of the tensor

Definition at line 317 of file qvtensor.h.

Referenced by add(), equals(), innerProduct(), norm2(), slice(), substract(), and tensorProduct().

double* QVTensor::getWriteData (  )  [inline]

Gets a reference of the data buffer of the tensor for read and write accesses.

Returns:
a pointer to the data buffer of the tensor

Definition at line 322 of file qvtensor.h.

Referenced by innerProduct(), leviCivita(), slice(), and tensorProduct().

QVTensorValence QVTensor::getValence (  )  const

Gets valence of the tensor.

This function can be used to obtain a list of the QVTensorIndex objects that represente the valence of the tensor.

Returns:
a QList<QVTensorIndex> object, containing the QVTensorIndex objects corresponding to the indexes of the tensor.

Definition at line 207 of file qvtensor.cpp.

Referenced by innerProduct(), and tensorProduct().

QVTensor QVTensor::slice ( const QVTensorIndexValues &  indexRangeList  )  const

Get a subtensor from a tensor.

Like with matrices, it is possible to extract a part of a tensor, given a list of values for some of its indexes. For further details about the use of this function, see section Slice operation.

Parameters:
indexRangeList list of range values for indexes.
See also:
transpose(const QVTensorIndex &, const QVTensorIndex &) const;

Definition at line 217 of file qvtensor.cpp.

QVTensor QVTensor::transpose ( const QVTensorValence &  indexList  )  const

Change the order of the indexes in the tensor.

This function reorders the indexes of the tensor. For further details about the use of this function, see section Transpose operation.

Parameters:
indexList new valence for the tensor, expressed as a list of indexes.
See also:
transpose(const QVTensorIndex &, const QVTensorIndex &) const;

Definition at line 264 of file qvtensor.cpp.

Referenced by innerProduct(), and transpose().

QVTensor QVTensor::transpose ( const QVTensorIndex &  i,
const QVTensorIndex &  j 
) const

Overloaded version of transpose function.

This overloaded version of transpose method swaps the location of two given indexes in the tensor. For further details about the use of this function, see section Transpose operation.

See also:
transpose(const QVTensorValence &) const

Definition at line 241 of file qvtensor.cpp.

QVTensor QVTensor::add ( const QVTensor &  tensor  )  const

Tensor add.

Parameters:
tensor operand for the add operation.
See also:
operator+

Todo:
check tensor valences are compatible
Todo:
use blas function cblas_axpy for data add

Definition at line 82 of file qvtensor.cpp.

Referenced by operator+().

QVTensor QVTensor::substract ( const QVTensor &  tensor  )  const

Tensor substraction.

Parameters:
tensor subtrahend for the operation.
See also:
operator-

Todo:
check tensor valences are compatible
Todo:
use blas function cblas_axpy for data substraction

Definition at line 101 of file qvtensor.cpp.

Referenced by operator-().

QVTensor QVTensor::tensorProduct ( const QVTensor &  tensor  )  const

Obtains the tensor product of two tensors.

Parameters:
tensor operand for the tensor product. For further details about the use of this function, see section Tensor product.
Returns:
the contracted tensor resulting from the inner product of the actual tensor and the one given through the parameter.
See also:
operator*(const QVTensorValence &) const

Definition at line 54 of file qvtensor.cpp.

Referenced by innerProduct().

QVTensor QVTensor::innerProduct ( const QVTensor &  tensor  )  const

Obtains the inner product of two tensors.

Parameters:
tensor operand for the inner product.
Returns:
the contracted tensor resulting from the tensor product of the actual tensor and the one given through the parameter.
See also:
operator*(const QVTensorValence &) const

Definition at line 119 of file qvtensor.cpp.

Referenced by operator*().

QVTensor QVTensor::outerProduct ( const QVTensor &  tensor  )  const

Obtains the outer product of two tensors.

Parameters:
tensor operand for the outer product.
Returns:
outer product of actual tensor and
See also:
operator^(const QVTensorValence &) const

Todo:
: to be done.

Definition at line 186 of file qvtensor.cpp.

Referenced by operator^().

bool QVTensor::equals ( const QVTensor &  tensor  )  const

Check equivalence between tensors.

Parameters:
tensor operand for the compare operation.
Returns:
true if the given tensor has equivalent valence and equal content of the data buffer.
See also:
operator==(const QVTensorValence &) const

Todo:
assert para comprobar que el tamaño del buffer de datos de ambos tensores se corresponde con su valencia

Definition at line 28 of file qvtensor.cpp.

Referenced by operator!=(), and operator==().

QVTensor QVTensor::renameIndexes ( const QVTensorValence &  indexList  )  const

Index renaming and contracting.

This method is equivalent to using operator(). See sections Tensor contraction and Tensor product for usage of that operator.

Parameters:
indexList new indexes for the tensor.
See also:
operator()(const QVTensorValence &indexList) const

Todo:
Assert for valence (variance/covariance and size) of new and old indexes is equivalent really? no, just check dimensions are compatible.

Definition at line 192 of file qvtensor.cpp.

Referenced by operator()().

QVTensorIndexator QVTensor::getIndexator (  )  [inline]

Gets tensor indexator.

This functions copies content of the data buffer, valence, and index names on this vector, over a given one.

Parameters:
tensor tensor to be copied.
Returns:
a reference to this vector
See also:
operator=(const QVTensorValence &)

Definition at line 409 of file qvtensor.h.

Referenced by leviCivita().

double QVTensor::norm2 (  )  const

Gets the norm2 for tensor.

Returns:
norm-2 of the tensor.

Definition at line 436 of file qvtensor.cpp.

QVTensor QVTensor::leviCivita ( const int  dimension  )  [static]

Gets Levi Civita symbol tensor.

Parameters:
dimension number of dimensions of the tensor
Returns:
a tensor containing the Levi Civita symbol.

Definition at line 476 of file qvtensor.cpp.

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


QVision framework. PARP research group. Copyright © 2007, 2008, 2009, 2010, 2011.