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...

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

Go to the source code of this file.

Classes
class	SimTK::MatrixBase< ELT >
	Variable-size 2d matrix of Composite Numerical Type (ELT) elements. 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_< T >
	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	SimTK::DeadMatrixView_< T >
	This is a MatrixView_ with the additional property that we are about to delete it. More...
class	SimTK::Matrix_< T >
	This is the Matrix class intended to appear in user code. More...
class	SimTK::DeadMatrix_< T >
class	SimTK::VectorView_< T >
	This class is identical to a Vector_; 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	SimTK::DeadVectorView_< T >
class	SimTK::Vector_< T >
	This is the Vector class intended to appear in user code. More...
class	SimTK::DeadVector_< T >
class	SimTK::RowVectorView_< T >
	This class is identical to a RowVector_; 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	SimTK::DeadRowVectorView_< T >
class	SimTK::RowVector_< T >
	RowVectors are much less common than Vectors. More...
class	SimTK::DeadRowVector_< T >
class	SimTK::VectorIterator< ELT, VECTOR_CLASS >
	This is an iterator for iterating over the elements of a Vector. More...
class	SimTK::MatrixBase< ELT >
	Variable-size 2d matrix of Composite Numerical Type (ELT) elements. More...
struct	SimTK::MatrixBase< ELT >::EltResult< P >
class	SimTK::VectorBase< ELT >
	This is a dataless rehash of the MatrixBase class to specialize it for Vectors. More...
struct	SimTK::VectorBase< ELT >::EltResult< P >
class	SimTK::RowVectorBase< ELT >
	This is a dataless rehash of the MatrixBase class to specialize it for RowVectors. More...
struct	SimTK::RowVectorBase< ELT >::EltResult< P >
class	SimTK::MatrixView_< T >
	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	SimTK::DeadMatrixView_< T >
	This is a MatrixView_ with the additional property that we are about to delete it. More...
class	SimTK::Matrix_< T >
	This is the Matrix class intended to appear in user code. More...
class	SimTK::VectorView_< T >
	This class is identical to a Vector_; 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	SimTK::Vector_< T >
	This is the Vector class intended to appear in user code. More...
class	SimTK::RowVectorView_< T >
	This class is identical to a RowVector_; 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	SimTK::RowVector_< T >
	RowVectors are much less common than Vectors. More...
class	SimTK::VectorIterator< ELT, VECTOR_CLASS >
	This is an iterator for iterating over the elements of a Vector. More...

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

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)

Matrix_<T> serialization and I/O
These methods are at namespace scope but are logically part of the Vector classes. These deal with reading and writing Vectors from and to streams, which places an additional requirement on the element type T: the element must support the same operation you are trying to do on the Vector as a whole.
typedef Vector_< Real >	SimTK::Vector
	Read fixed-size VectorView from input stream. More...
typedef Vector_< float >	SimTK::fVector
	Read fixed-size VectorView from input stream. More...
typedef Vector_< double >	SimTK::dVector
	Read fixed-size VectorView from input stream. More...
typedef Vector_< Complex >	SimTK::ComplexVector
	Read fixed-size VectorView from input stream. More...
typedef Vector_< fComplex >	SimTK::fComplexVector
	Read fixed-size VectorView from input stream. More...
typedef Vector_< dComplex >	SimTK::dComplexVector
	Read fixed-size VectorView from input stream. More...
typedef VectorView_< Real >	SimTK::VectorView
	Read fixed-size VectorView from input stream. More...
typedef VectorView_< float >	SimTK::fVectorView
	Read fixed-size VectorView from input stream. More...
typedef VectorView_< double >	SimTK::dVectorView
	Read fixed-size VectorView from input stream. More...
typedef VectorView_< Complex >	SimTK::ComplexVectorView
	Read fixed-size VectorView from input stream. More...
typedef VectorView_< fComplex >	SimTK::fComplexVectorView
	Read fixed-size VectorView from input stream. More...
typedef VectorView_< dComplex >	SimTK::dComplexVectorView
	Read fixed-size VectorView from input stream. More...
typedef RowVector_< Real >	SimTK::RowVector
	Read fixed-size VectorView from input stream. More...
typedef RowVector_< float >	SimTK::fRowVector
	Read fixed-size VectorView from input stream. More...
typedef RowVector_< double >	SimTK::dRowVector
	Read fixed-size VectorView from input stream. More...
typedef RowVector_< Complex >	SimTK::ComplexRowVector
	Read fixed-size VectorView from input stream. More...
typedef RowVector_< fComplex >	SimTK::fComplexRowVector
	Read fixed-size VectorView from input stream. More...
typedef RowVector_< dComplex >	SimTK::dComplexRowVector
	Read fixed-size VectorView from input stream. More...
typedef RowVectorView_< Real >	SimTK::RowVectorView
	Read fixed-size VectorView from input stream. More...
typedef RowVectorView_< float >	SimTK::fRowVectorView
	Read fixed-size VectorView from input stream. More...
typedef RowVectorView_< double >	SimTK::dRowVectorView
	Read fixed-size VectorView from input stream. More...
typedef RowVectorView_< Complex >	SimTK::ComplexRowVectorView
	Read fixed-size VectorView from input stream. More...
typedef RowVectorView_< fComplex >	SimTK::fComplexRowVectorView
	Read fixed-size VectorView from input stream. More...
typedef RowVectorView_< dComplex >	SimTK::dComplexRowVectorView
	Read fixed-size VectorView from input stream. More...
typedef Matrix_< Real >	SimTK::Matrix
	Read fixed-size VectorView from input stream. More...
typedef Matrix_< float >	SimTK::fMatrix
	Read fixed-size VectorView from input stream. More...
typedef Matrix_< double >	SimTK::dMatrix
	Read fixed-size VectorView from input stream. More...
typedef Matrix_< Complex >	SimTK::ComplexMatrix
	Read fixed-size VectorView from input stream. More...
typedef Matrix_< fComplex >	SimTK::fComplexMatrix
	Read fixed-size VectorView from input stream. More...
typedef Matrix_< dComplex >	SimTK::dComplexMatrix
	Read fixed-size VectorView from input stream. More...
typedef MatrixView_< Real >	SimTK::MatrixView
	Read fixed-size VectorView from input stream. More...
typedef MatrixView_< float >	SimTK::fMatrixView
	Read fixed-size VectorView from input stream. More...
typedef MatrixView_< double >	SimTK::dMatrixView
	Read fixed-size VectorView from input stream. More...
typedef MatrixView_< Complex >	SimTK::ComplexMatrixView
	Read fixed-size VectorView from input stream. More...
typedef MatrixView_< fComplex >	SimTK::fComplexMatrixView
	Read fixed-size VectorView from input stream. More...
typedef MatrixView_< dComplex >	SimTK::dComplexMatrixView
	Read fixed-size VectorView from input stream. More...
template<class E >
bool	SimTK::readUnformatted (std::istream &in, VectorView_< E > &v)
	Read fixed-size VectorView from input stream. More...
template<class E >
bool	SimTK::readUnformatted (std::istream &in, Vector_< E > &v)
	Read variable-size Vector from input stream. More...
template<class E >
bool	SimTK::readUnformatted (std::istream &in, RowVectorView_< E > &v)
	Read fixed-size RowVectorView from input stream. More...
template<class E >
bool	SimTK::readUnformatted (std::istream &in, RowVector_< E > &v)
	Read variable-size RowVector from unformatted (whitespace-separated) input stream. More...
template<class E >
bool	SimTK::readUnformatted (std::istream &in, MatrixView_< E > &v)
	Read fixed-size MatrixView in row order from unformatted (whitespace- separated) input stream. More...
template<class E >
bool	SimTK::fillUnformatted (std::istream &in, Matrix_< E > &v)
	Read in new values for a Matrix without changing its size, from a stream of whitespace-separated tokens with no other formatting recognized. More...
template<class E >
bool	SimTK::readUnformatted (std::istream &in, Matrix_< E > &v)
	NOT IMPLEMENTED: read variable-size Matrix recognizing newlines as end of row; use fillUnformatted() instead. More...

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>

Dead matrices are owners that are about to be destructed. Anything they own may be taken from them, including the helper and/or the data. 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>