BigMatrix.h File Reference

---

Detailed Description

This file defines the client side of the SimTK::Matrix classes, which hold large, variable-sized matrices whose elements are packed SimTK "Composite Numerical Types" (CNTs).

Unlike CNTs, the implemention here is opaque, and almost all properties are captured in the implementation at run time rather than in the type at compile time.

Every Matrix consists logically of two pieces: data descriptor and view (which we call an "element filter"). Many matrices can refer to the same data descriptor, but each presents its own view of that data. The default view is transparent, that is, all the data managed by the descriptor is visible. A single Matrix owns a data descriptor, although there can be many other views.

NOTE: Destruction of a data descriptor's owner destructs the data descriptor *regardless* of the presences of other views! I.e., these are not reference counted. TODO: should we change that?

Data descriptors refer to the actual in-memory data containing the floating point values. Typically the data descriptor owns the data, so they disappear together. However, when working with pre-existing arrays (for example when dealing with Fortran or C), the data descriptor will describe the data layout without owning it so the data persists after the death of the descriptor. In that case it is fine to have multiple data descriptors for the same data.

Matrix handle references & may own: MatrixRep (private implementation) MatrixRep owns: view references & may own: data descriptor references & may own: data

A Matrix which is the owner of its data descriptor will be resized whenever necessary, unless you take active steps to prevent that. For example, if you declare a Vector, the number of rows can resize but the number of columns will be locked at 1. A RowVector does the reverse. You can also explicitly lock the number of rows and/or columns of a matrix to prevent unwanted resizes.

Here are the classes and short descriptions: MatrixHelper<S> interface to the opaque implementation, templatized by scalar type only MatrixBase<CNT> fully templatized client, contains a MatrixHelper

The rest are dataless classes all of which can be interconverted just by recasting. Every one of these classes has a default conversion to type Matrix_<same element type>, so users can write functions that expect a Matrix argument and pass it a Vector, RowVectorView, or whatever.

VectorBase<CNT> these are derived from MatrixBase and add no new data, RowVectorBase<CNT> but change some of the operators and other methods to be appropriate for 1d data.

Matrix_<CNT> 2d owner class (a MatrixBase<CNT>) Vector_<CNT> column owner class (a VectorBase<CNT>) RowVector_<CNT> row owner class (a RowVectorBase<CNT>)

Views are exactly the same as the corresponding owner class, but with shallow construction and assignment semantics.

MatrixView_<CNT>, VectorView_<CNT>, RowVectorView_<CNT>

Dead matrices are owners which are about to be destructed. Anything they own may be taken from them, including the data descriptor and/or the element filter. This is a very effective performance trick for sequences of operations since it eliminates most of the need for allocating and deallocating temporaries.

DeadMatrix_<CNT>, DeadVector_<CNT>, DeadRowVector_<CNT>

TODO: matrix expression templates for delaying operator execution.

#include "SimTKcommon/Scalar.h"
#include "SimTKcommon/SmallMatrix.h"
#include "SimTKcommon/internal/MatrixHelper.h"
#include <iostream>
#include <cassert>
#include <complex>
#include <cstddef>
#include <limits>

Go to the source code of this file.

Namespaces
namespace	SimTK
Classes
class	MatrixBase
	Variable-size 2d matrix of Composite Numerical Type (ELT) elements. More...
struct	MatrixBase::EltResult
class	VectorBase
	This is a dataless rehash of the MatrixBase class to specialize it for Vectors. More...
struct	VectorBase::EltResult
class	RowVectorBase
	This is a dataless rehash of the MatrixBase class to specialize it for RowVectors. More...
struct	RowVectorBase::EltResult
class	TmpMatrixView_
	XXX not ready for prime time. More...
class	MatrixView_
	This class is identical to a Matrix_; it is used only to manage the C++ rules for when copy constructors are called by introducing a separate type to prevent certain allowed optimizations from occuring when we don't want them. More...
class	Matrix_
	This is the class intended to appear in user code. More...
class	VectorView_
class	TmpVectorViewT
	XXX not ready for prime time. More...
class	Vector_
class	RowVectorView_
class	TmpRowVectorView_
	XXX not ready for prime time. More...
class	RowVector_
class	MatrixShape
class	MatrixSize
class	MatrixStructure
class	MatrixSparsity
class	MatrixStorage
class	MatrixCondition
class	VectorIterator
	This is an iterator for iterating over the elements of a matrix. More...
Typedefs
typedef Vector_< Real >	SimTK::Vector
typedef Vector_< Complex >	SimTK::ComplexVector
typedef VectorView_< Real >	SimTK::VectorView
typedef VectorView_< Complex >	SimTK::ComplexVectorView
typedef RowVector_< Real >	SimTK::RowVector
typedef RowVector_< Complex >	SimTK::ComplexRowVector
typedef RowVectorView_< Real >	SimTK::RowVectorView
typedef RowVectorView_< Complex >	SimTK::ComplexRowVectorView
typedef Matrix_< Real >	SimTK::Matrix
typedef Matrix_< Complex >	SimTK::ComplexMatrix
typedef MatrixView_< Real >	SimTK::MatrixView
typedef MatrixView_< Complex >	SimTK::ComplexMatrixView
Functions
template<class E1, class E2>
Matrix_< typename CNT< E1 >::template Result< E2 >::Add >	SimTK::operator+ (const MatrixBase< E1 > &l, const MatrixBase< E2 > &r)
template<class E>
Matrix_< E >	SimTK::operator+ (const MatrixBase< E > &l, const typename CNT< E >::T &r)
template<class E>
Matrix_< E >	SimTK::operator+ (const typename CNT< E >::T &l, const MatrixBase< E > &r)
template<class E1, class E2>
Matrix_< typename CNT< E1 >::template Result< E2 >::Sub >	SimTK::operator- (const MatrixBase< E1 > &l, const MatrixBase< E2 > &r)
template<class E>
Matrix_< E >	SimTK::operator- (const MatrixBase< E > &l, const typename CNT< E >::T &r)
template<class E>
Matrix_< E >	SimTK::operator- (const typename CNT< E >::T &l, const MatrixBase< E > &r)
template<class E>
Matrix_< E >	SimTK::operator * (const MatrixBase< E > &l, const typename CNT< E >::StdNumber &r)
template<class E>
Matrix_< E >	SimTK::operator * (const typename CNT< E >::StdNumber &l, const MatrixBase< E > &r)
template<class E>
Matrix_< E >	SimTK::operator/ (const MatrixBase< E > &l, const typename CNT< E >::StdNumber &r)
template<class E1, class E2>
Vector_< typename CNT< E1 >::template Result< E2 >::Add >	SimTK::operator+ (const VectorBase< E1 > &l, const VectorBase< E2 > &r)
template<class E>
Vector_< E >	SimTK::operator+ (const VectorBase< E > &l, const typename CNT< E >::T &r)
template<class E>
Vector_< E >	SimTK::operator+ (const typename CNT< E >::T &l, const VectorBase< E > &r)
template<class E1, class E2>
Vector_< typename CNT< E1 >::template Result< E2 >::Sub >	SimTK::operator- (const VectorBase< E1 > &l, const VectorBase< E2 > &r)
template<class E>
Vector_< E >	SimTK::operator- (const VectorBase< E > &l, const typename CNT< E >::T &r)
template<class E>
Vector_< E >	SimTK::operator- (const typename CNT< E >::T &l, const VectorBase< E > &r)
template<class E>
Vector_< E >	SimTK::operator * (const VectorBase< E > &l, const typename CNT< E >::StdNumber &r)
template<class E>
Vector_< E >	SimTK::operator * (const typename CNT< E >::StdNumber &l, const VectorBase< E > &r)
template<class E>
Vector_< E >	SimTK::operator/ (const VectorBase< E > &l, const typename CNT< E >::StdNumber &r)
template<class E1, class E2>
RowVector_< typename CNT< E1 >::template Result< E2 >::Add >	SimTK::operator+ (const RowVectorBase< E1 > &l, const RowVectorBase< E2 > &r)
template<class E>
RowVector_< E >	SimTK::operator+ (const RowVectorBase< E > &l, const typename CNT< E >::T &r)
template<class E>
RowVector_< E >	SimTK::operator+ (const typename CNT< E >::T &l, const RowVectorBase< E > &r)
template<class E1, class E2>
RowVector_< typename CNT< E1 >::template Result< E2 >::Sub >	SimTK::operator- (const RowVectorBase< E1 > &l, const RowVectorBase< E2 > &r)
template<class E>
RowVector_< E >	SimTK::operator- (const RowVectorBase< E > &l, const typename CNT< E >::T &r)
template<class E>
RowVector_< E >	SimTK::operator- (const typename CNT< E >::T &l, const RowVectorBase< E > &r)
template<class E>
RowVector_< E >	SimTK::operator * (const RowVectorBase< E > &l, const typename CNT< E >::StdNumber &r)
template<class E>
RowVector_< E >	SimTK::operator * (const typename CNT< E >::StdNumber &l, const RowVectorBase< E > &r)
template<class E>
RowVector_< E >	SimTK::operator/ (const RowVectorBase< E > &l, const typename CNT< E >::StdNumber &r)
template<class E1, class E2>
CNT< E1 >::template Result< E2 >::Mul	SimTK::operator * (const RowVectorBase< E1 > &r, const VectorBase< E2 > &v)
template<class E1, class E2>
Vector_< typename CNT< E1 >::template Result< E2 >::Mul >	SimTK::operator * (const MatrixBase< E1 > &m, const VectorBase< E2 > &v)
template<class E1, class E2>
Matrix_< typename CNT< E1 >::template Result< E2 >::Mul >	SimTK::operator * (const MatrixBase< E1 > &m1, const MatrixBase< E2 > &m2)
template<class T>
std::ostream &	SimTK::operator<< (std::ostream &o, const VectorBase< T > &v)
template<class T>
std::ostream &	SimTK::operator<< (std::ostream &o, const RowVectorBase< T > &v)
template<class T>
std::ostream &	SimTK::operator<< (std::ostream &o, const MatrixBase< T > &m)

---