Simbody: 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...
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_< ELT >
	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_< ELT >
	This is a MatrixView_ with the additional property that we are about to delete it. More...
class	SimTK::Matrix_< ELT >
	This is the Matrix class intended to appear in user code. More...
class	SimTK::VectorView_< ELT >
	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_< ELT >
	This is the Vector class intended to appear in user code. More...
class	SimTK::RowVectorView_< ELT >
	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_< ELT >
	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
namespace	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
typedef Vector_< float >	SimTK::fVector
typedef Vector_< double >	SimTK::dVector
typedef Vector_< Complex >	SimTK::ComplexVector
typedef Vector_< fComplex >	SimTK::fComplexVector
typedef Vector_< dComplex >	SimTK::dComplexVector
typedef VectorView_< Real >	SimTK::VectorView
typedef VectorView_< float >	SimTK::fVectorView
typedef VectorView_< double >	SimTK::dVectorView
typedef VectorView_< Complex >	SimTK::ComplexVectorView
typedef VectorView_< fComplex >	SimTK::fComplexVectorView
typedef VectorView_< dComplex >	SimTK::dComplexVectorView
typedef RowVector_< Real >	SimTK::RowVector
typedef RowVector_< float >	SimTK::fRowVector
typedef RowVector_< double >	SimTK::dRowVector
typedef RowVector_< Complex >	SimTK::ComplexRowVector
typedef RowVector_< fComplex >	SimTK::fComplexRowVector
typedef RowVector_< dComplex >	SimTK::dComplexRowVector
typedef RowVectorView_< Real >	SimTK::RowVectorView
typedef RowVectorView_< float >	SimTK::fRowVectorView
typedef RowVectorView_< double >	SimTK::dRowVectorView
typedef RowVectorView_< Complex >	SimTK::ComplexRowVectorView
typedef RowVectorView_< fComplex >	SimTK::fComplexRowVectorView
typedef RowVectorView_< dComplex >	SimTK::dComplexRowVectorView
typedef Matrix_< Real >	SimTK::Matrix
typedef Matrix_< float >	SimTK::fMatrix
typedef Matrix_< double >	SimTK::dMatrix
typedef Matrix_< Complex >	SimTK::ComplexMatrix
typedef Matrix_< fComplex >	SimTK::fComplexMatrix
typedef Matrix_< dComplex >	SimTK::dComplexMatrix
typedef MatrixView_< Real >	SimTK::MatrixView
typedef MatrixView_< float >	SimTK::fMatrixView
typedef MatrixView_< double >	SimTK::dMatrixView
typedef MatrixView_< Complex >	SimTK::ComplexMatrixView
typedef MatrixView_< fComplex >	SimTK::fComplexMatrixView
typedef MatrixView_< dComplex >	SimTK::dComplexMatrixView
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)
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)
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>

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>

BigMatrix.h File Reference

Classes

Namespaces

Typedefs

Functions

Detailed Description