BigMatrix.h File Reference

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

Go to the source code of this file.

Classes
class	SimTK::MatrixBase< ELT >
	This is the common base class for Simbody's Vector_ and Matrix_ classes for handling large, variable-sized vectors and matrices. More...
class	SimTK::VectorBase< ELT >
	This is a dataless rehash of the MatrixBase class to specialize it for Vectors. More...
class	SimTK::RowVectorBase< ELT >
	This is a dataless rehash of the MatrixBase class to specialize it for RowVectors. More...
class	SimTK::MatrixView_< ELT >
	(Advanced) This class is identical to Matrix_ except that it has shallow (reference) copy and assignment semantics. More...
class	SimTK::Matrix_< ELT >
	This is the matrix class intended to appear in user code for large, variable size matrices. More...
class	SimTK::VectorView_< ELT >
	(Advanced) This class is identical to Vector_ except that it has shallow (reference) copy and assignment semantics. More...
class	SimTK::Vector_< ELT >
	This is the vector class intended to appear in user code for large, variable size column vectors. More...
class	SimTK::RowVectorView_< ELT >
	(Advanced) This class is identical to RowVector_ except that it has shallow (reference) copy and assignment semantics. More...
class	SimTK::RowVector_< ELT >
	Represents a variable size row vector; much less common than the column vector type Vector_. More...
class	SimTK::VectorIterator< ELT, VECTOR_CLASS >
	This is an iterator for iterating over the elements of a Vector_ or Vec object. More...

Namespaces
	SimTK
	This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with other symbols.

Typedefs
typedef Vector_< Real >	SimTK::Vector
	Variable-size column vector of Real elements; abbreviation for Vector_<Real>. More...
typedef Matrix_< Real >	SimTK::Matrix
	Variable-size 2D matrix of Real elements; abbreviation for Matrix_<Real>. More...
typedef RowVector_< Real >	SimTK::RowVector
	Variable-size row vector of Real elements; abbreviation for RowVector_<Real>. More...
typedef Vector_< Complex >	SimTK::ComplexVector
	Variable-size column vector of Complex (std::complex<Real>) elements. More...
typedef Matrix_< Complex >	SimTK::ComplexMatrix
	Variable-size 2D matrix of Complex (std::complex<Real>) elements. More...
typedef RowVector_< Complex >	SimTK::ComplexRowVector
	Variable-size row vector of Complex (std::complex<Real>) elements. More...
typedef VectorView_< Real >	SimTK::VectorView
	Non-owner column vector sharing Real elements. More...
typedef MatrixView_< Real >	SimTK::MatrixView
	Non-owner matrix sharing Real elements. More...
typedef RowVectorView_< Real >	SimTK::RowVectorView
	Non-owner row vector sharing Real elements. More...
typedef VectorView_< Complex >	SimTK::ComplexVectorView
	Non-owner column vector sharing Complex (std::complex<Real>) elements. More...
typedef MatrixView_< Complex >	SimTK::ComplexMatrixView
	Non-owner matrix sharing Complex (std::complex<Real>) elements. More...
typedef RowVectorView_< Complex >	SimTK::ComplexRowVectorView
	Non-owner row vector sharing Complex (std::complex<Real>) elements. More...
typedef Vector_< float >	SimTK::fVector
	Abbreviation for Vector_<float>. More...
typedef Vector_< double >	SimTK::dVector
	Abbreviation for Vector_<double>. More...
typedef Vector_< fComplex >	SimTK::fComplexVector
	Abbreviation for Vector_<std::complex<float>>. More...
typedef Vector_< dComplex >	SimTK::dComplexVector
	Abbreviation for Vector_<std::complex<double>>. More...
typedef VectorView_< float >	SimTK::fVectorView
	Abbreviation for VectorView_<float>. More...
typedef VectorView_< double >	SimTK::dVectorView
	Abbreviation for VectorView_<double>. More...
typedef VectorView_< fComplex >	SimTK::fComplexVectorView
	Abbreviation for VectorView_<std::complex<float>>. More...
typedef VectorView_< dComplex >	SimTK::dComplexVectorView
	Abbreviation for VectorView_<std::complex<double>>. More...
typedef RowVector_< float >	SimTK::fRowVector
	Abbreviation for RowVector_<float>. More...
typedef RowVector_< double >	SimTK::dRowVector
	Abbreviation for RowVector_<double>. More...
typedef RowVector_< fComplex >	SimTK::fComplexRowVector
	Abbreviation for RowVector_<std::complex<float>>. More...
typedef RowVector_< dComplex >	SimTK::dComplexRowVector
	Abbreviation for RowVector_<std::complex<double>>. More...
typedef RowVectorView_< float >	SimTK::fRowVectorView
	Abbreviation for RowVectorView_<float>. More...
typedef RowVectorView_< double >	SimTK::dRowVectorView
	Abbreviation for RowVectorView_<double>. More...
typedef RowVectorView_< fComplex >	SimTK::fComplexRowVectorView
	Abbreviation for RowVectorView_<std::complex<float>>. More...
typedef RowVectorView_< dComplex >	SimTK::dComplexRowVectorView
	Abbreviation for RowVectorView_<std::complex<double>>. More...
typedef Matrix_< float >	SimTK::fMatrix
	Abbreviation for Matrix_<float>. More...
typedef Matrix_< double >	SimTK::dMatrix
	Abbreviation for Matrix_<double>. More...
typedef Matrix_< fComplex >	SimTK::fComplexMatrix
	Abbreviation for Matrix_<std::complex<float>>. More...
typedef Matrix_< dComplex >	SimTK::dComplexMatrix
	Abbreviation for Matrix_<std::complex<double>>. More...
typedef MatrixView_< float >	SimTK::fMatrixView
	Abbreviation for MatrixView_<float>. More...
typedef MatrixView_< double >	SimTK::dMatrixView
	Abbreviation for MatrixView_<double>. More...
typedef MatrixView_< fComplex >	SimTK::fComplexMatrixView
	Abbreviation for MatrixView_<std::complex<float>>. More...
typedef MatrixView_< dComplex >	SimTK::dComplexMatrixView
	Abbreviation for MatrixView_<std::complex<double>>. More...

Functions
template<class T >
static std::istream &	SimTK::readVectorFromStreamHelper (std::istream &in, bool isFixedSize, Vector_< T > &out)
Global operators involving Matrix objects
These operators take MatrixBase arguments and produce Matrix_ results.
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 E >
Matrix_< E >	SimTK::operator* (const MatrixBase< E > &l, int r)
template<class E >
Matrix_< E >	SimTK::operator* (int l, const MatrixBase< E > &r)
template<class E >
Matrix_< E >	SimTK::operator/ (const MatrixBase< E > &l, int r)
Global operators involving Vector objects
These operators take VectorBase arguments and produce Vector_ results.
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 E >
Vector_< E >	SimTK::operator* (const VectorBase< E > &l, int r)
template<class E >
Vector_< E >	SimTK::operator* (int l, const VectorBase< E > &r)
template<class E >
Vector_< E >	SimTK::operator/ (const VectorBase< E > &l, int r)
template<class E1 , int M, class E2 , int S>
Vector_< typename CNT< E1 > ::template Result< Vec< M, E2, S > >::Mul >	SimTK::operator* (const VectorBase< E1 > &v, const Vec< M, E2, S > &s)
template<class E1 , int M, class E2 , int S>
Vector_< typename Vec< M, E2, S >::template Result< E1 > ::Mul >	SimTK::operator* (const Vec< M, E2, S > &s, const VectorBase< E1 > &v)
template<class E1 , int N, class E2 , int S>
Vector_< typename CNT< E1 > ::template Result< Row< N, E2, S > >::Mul >	SimTK::operator* (const VectorBase< E1 > &v, const Row< N, E2, S > &s)
template<class E1 , int N, class E2 , int S>
Vector_< typename Row< N, E2, S >::template Result< E1 > ::Mul >	SimTK::operator* (const Row< N, E2, S > &s, const VectorBase< E1 > &v)
template<class E1 , int M, int N, class E2 , int S1, int S2>
Vector_< typename CNT< E1 > ::template Result< Mat< M, N, E2, S1, S2 > >::Mul >	SimTK::operator* (const VectorBase< E1 > &v, const Mat< M, N, E2, S1, S2 > &s)
template<class E1 , int M, int N, class E2 , int S1, int S2>
Vector_< typename Mat< M, N, E2, S1, S2 >::template Result < E1 >::Mul >	SimTK::operator* (const Mat< M, N, E2, S1, S2 > &s, const VectorBase< E1 > &v)
template<class E1 , int M, class E2 , int S>
Vector_< typename CNT< E1 > ::template Result< SymMat< M, E2, S > >::Mul >	SimTK::operator* (const VectorBase< E1 > &v, const SymMat< M, E2, S > &s)
template<class E1 , int M, class E2 , int S>
Vector_< typename SymMat< M, E2, S >::template Result< E1 > ::Mul >	SimTK::operator* (const SymMat< M, E2, S > &s, const VectorBase< E1 > &v)
Global operators involving RowVector objects
These operators take RowVectorBase arguments and produce RowVector_ results.
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 E >
RowVector_< E >	SimTK::operator* (const RowVectorBase< E > &l, int r)
template<class E >
RowVector_< E >	SimTK::operator* (int l, const RowVectorBase< E > &r)
template<class E >
RowVector_< E >	SimTK::operator/ (const RowVectorBase< E > &l, int r)
template<class E1 , int M, class E2 , int S>
RowVector_< typename CNT< E1 > ::template Result< Vec< M, E2, S > >::Mul >	SimTK::operator* (const RowVectorBase< E1 > &v, const Vec< M, E2, S > &s)
template<class E1 , int M, class E2 , int S>
RowVector_< typename Vec< M, E2, S >::template Result< E1 > ::Mul >	SimTK::operator* (const Vec< M, E2, S > &s, const RowVectorBase< E1 > &v)
template<class E1 , int N, class E2 , int S>
RowVector_< typename CNT< E1 > ::template Result< Row< N, E2, S > >::Mul >	SimTK::operator* (const RowVectorBase< E1 > &v, const Row< N, E2, S > &s)
template<class E1 , int N, class E2 , int S>
RowVector_< typename Row< N, E2, S >::template Result< E1 > ::Mul >	SimTK::operator* (const Row< N, E2, S > &s, const RowVectorBase< E1 > &v)
template<class E1 , int M, int N, class E2 , int S1, int S2>
RowVector_< typename CNT< E1 > ::template Result< Mat< M, N, E2, S1, S2 > >::Mul >	SimTK::operator* (const RowVectorBase< E1 > &v, const Mat< M, N, E2, S1, S2 > &s)
template<class E1 , int M, int N, class E2 , int S1, int S2>
RowVector_< typename Mat< M, N, E2, S1, S2 >::template Result < E1 >::Mul >	SimTK::operator* (const Mat< M, N, E2, S1, S2 > &s, const RowVectorBase< E1 > &v)
template<class E1 , int M, class E2 , int S>
RowVector_< typename CNT< E1 > ::template Result< SymMat< M, E2, S > >::Mul >	SimTK::operator* (const RowVectorBase< E1 > &v, const SymMat< M, E2, S > &s)
template<class E1 , int M, class E2 , int S>
RowVector_< typename SymMat< M, E2, S >::template Result< E1 > ::Mul >	SimTK::operator* (const SymMat< M, E2, S > &s, const RowVectorBase< E1 > &v)
Global operators involving mixed matrix, vector, and row vector objects
These operators take MatrixBase, VectorBase, and RowVectorBase arguments and produce Matrix_, Vector_, and RowVector_ results.
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)

Detailed Description

This file defines the client side of the SimTK::Matrix classes, which hold medium to 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 three pieces:

• the matrix handle
• the matrix helper
• and the matrix data.

They are organized like this:

     ------------            ------------
    |  Handle<E> | -------> |            |
     ------------  <------- | Helper<S>  |
                            |            |
                            |            |          --------~ ~--
                            |            | ------> | Data<S> ... |
                             ------------           --------~ ~--

The handle is the object actually appearing in SimTK API user programs. It always consists of just a single pointer, pointing to a library-side "helper" object whose implementation is opaque. The handle is templatized by the user's element type, which may be any packed composite numerical type, including scalar types like float and complex<double>, but also composite types such as Vec3 or Mat<2,2,Mat<3,3>>. A Matrix handle owns the helper to which it points and must destruct the helper when the handle's destructor is called.

The helper, on the other hand, is parameterized only by the underlying scalar type. There are exactly 12 SimTK scalar types, so all can be instantiated on the library side leaving the implementation opaque and thus flexible from release to release without compromising binary compatibility. (The scalar types are: the four C++ standard types float and double, complex<float>, and complex<double>; the SimTK numbers conjugate<float> and conjugate<double>; and negator<> types templatized by any of the six numeric types.) The helper contains several kinds of information:

• the underlying scalar type S (as its template parameter)
• the number of scalars in the handle's logical element type E
• whether this is an owner matrix, or just a view
• the handle "commitment"; defining the range of matrix characteristics to which that handle may refer
• the actual characteristics of the matrix currently represented by the helper
• a virtual function table full of methods which are aware of the logical structure of the Matrix and the physical structure of the data to support operations such as element indexing
• a pointer to the underlying data, which may be shared with other helpers

The data itself consists only of scalars S of the same type as the helper's template argument, but different helpers can look at the same data differently. For examples, when the elements are composite consisting of k scalars, the helper will provide a view of the data in which its scalars are interpreted in groups of k. Many other reinterpretations of the data are possible and useful, such as a real-valued helper viewing only the real or imaginary part of complex data, or a helper which views the data order as though it were transposed.

At most one matrix helper owns the matrix data and is responsible for deleting that data when no longer needed. That is called an "owner" helper and its associated handle is an owner handle. Normally the owner is the handle (and helper) that allocated the data, and in most cases an owner can resize the data at will. Many other handles may reference the same data; those non-owner handles are called "views". Every view may present a different picture of the underlying data. The default view is "whole" meaning that all the elements of the data are visible, and appear in their normal order. A "transpose" view also shows all the elements but the matrix dimensions and indices are reversed. Other common views are "block" to select a sub-block of a matrix, and "diagonal" which shows only the diagonal of a matrix (as a vector).

NOTE: Destruction of an owner destructs the data it owns *regardless* of the presence of other views into that data! I.e., these are not reference counted. TODO: should we change that?

In some cases there may be no owner helper for a particular piece of matrix data. That occurs when pre-existing memory, such as a Fortran array, is used to construct a Matrix. In that case all the helpers are views and the data will persist after the destruction of the last referencing helper.

A Matrix that is the owner of its data 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>