An STL-compliant matrix container class. More...
#include <scythestat/matrix.h>
Public Types | |
| typedef matrix_random_access_iterator < T_type, ORDER, ORDER, STYLE > | iterator |
| Random Access Iterator type. | |
| typedef const_matrix_random_access_iterator < T_type, ORDER, ORDER, STYLE > | const_iterator |
| Const Random Access Iterator type. | |
| typedef std::reverse_iterator < matrix_random_access_iterator < T_type, ORDER, ORDER, STYLE > > | reverse_iterator |
| Reverse Random Access Iterator type. | |
| typedef std::reverse_iterator < const_matrix_random_access_iterator < T_type, ORDER, ORDER, STYLE > > | const_reverse_iterator |
| Reverse Const Random Access Iterator type. | |
| typedef matrix_forward_iterator < T_type, ORDER, ORDER, STYLE > | forward_iterator |
| Forward Iterator type. | |
| typedef const_matrix_forward_iterator < T_type, ORDER, ORDER, STYLE > | const_forward_iterator |
| Const Forward Iterator type. | |
| typedef matrix_bidirectional_iterator < T_type, ORDER, ORDER, STYLE > | bidirectional_iterator |
| Bidirectional Iterator type. | |
| typedef const_matrix_bidirectional_iterator < T_type, ORDER, ORDER, STYLE > | const_bidirectional_iterator |
| Const Bidirectional Iterator type. | |
| typedef std::reverse_iterator < matrix_bidirectional_iterator < T_type, ORDER, ORDER, STYLE > > | reverse_bidirectional_iterator |
| Const Bidirectional Iterator type. | |
| typedef std::reverse_iterator < const_matrix_bidirectional_iterator < T_type, ORDER, ORDER, STYLE > > | const_reverse_bidirectional_iterator |
| Reverse Const Bidirectional Iterator type. | |
| typedef T_type | ttype |
| The Matrix' element type. | |
Public Member Functions | |
| Matrix () | |
| Default constructor. | |
| Matrix (T_type element) | |
| Parameterized type constructor. | |
| Matrix (uint rows, uint cols, bool fill=true, T_type fill_value=0) | |
| Standard constructor. | |
| template<typename T_iterator > | |
| Matrix (uint rows, uint cols, T_iterator it) | |
| Iterator constructor. | |
| Matrix (const std::string &path, bool oldstyle=false) | |
| File constructor. | |
| Matrix (const Matrix &M) | |
| Default copy constructor. | |
| template<matrix_order O, matrix_style S> | |
| Matrix (const Matrix< T_type, O, S > &M) | |
| Cross order and/or style copy constructor. | |
| template<typename S_type , matrix_order O, matrix_style S> | |
| Matrix (const Matrix< S_type, O, S > &M) | |
| Cross type copy constructor. | |
| template<matrix_order O, matrix_style S> | |
| Matrix (const Matrix< T_type, O, S > &M, uint x1, uint y1, uint x2, uint y2) | |
| Submatrix constructor. | |
| ~Matrix () | |
| Destructor. | |
| template<matrix_order O, matrix_style S> | |
| void | reference (const Matrix< T_type, O, S > &M) |
| View another Matrix's data. | |
| Matrix< T_type, ORDER, Concrete > | copy () const |
| Create a copy of this matrix. | |
| template<matrix_order O, matrix_style S> | |
| void | copy (const Matrix< T_type, O, S > &M) |
| Make this Matrix a copy of another. | |
| T_type & | operator[] (uint i) |
| Access or modify an element in this Matrix. | |
| T_type & | operator[] (uint i) const |
| Access an element in this Matrix. | |
| T_type & | operator() (uint i) |
| Access or modify an element in this Matrix. | |
| T_type & | operator() (uint i) const |
| Access an element in this Matrix. | |
| T_type & | operator() (uint i, uint j) |
| Access or modify an element in this Matrix. | |
| T_type & | operator() (uint i, uint j) const |
| Access an element in this Matrix. | |
| Matrix< T_type, ORDER, View > | operator() (uint x1, uint y1, uint x2, uint y2) |
| Returns a view of a submatrix. | |
| Matrix< T_type, ORDER, View > | operator() (uint x1, uint y1, uint x2, uint y2) const |
| Returns a view of a submatrix. | |
| Matrix< T_type, ORDER, View > | operator() (const all_elements a, uint j) |
| Returns a view of a column vector. | |
| Matrix< T_type, ORDER, View > | operator() (const all_elements a, uint j) const |
| Returns a view of a column vector. | |
| Matrix< T_type, ORDER, View > | operator() (uint i, const all_elements b) |
| Returns a view of a row vector. | |
| Matrix< T_type, ORDER, View > | operator() (uint i, const all_elements b) const |
| Returns a view of a row vector. | |
| Matrix & | operator= (const Matrix &M) |
| Returns single element in matrix as scalar type. | |
| template<matrix_order O, matrix_style S> | |
| Matrix & | operator= (const Matrix< T_type, O, S > &M) |
| Assign the contents of one Matrix to another. | |
| ListInitializer< T_type, iterator, ORDER, STYLE > | operator= (T_type x) |
| Copy values in a comma-separated list into this Matrix. | |
| template<typename ITERATOR , matrix_order O, matrix_style S> | |
| Matrix & | operator= (ListInitializer< T_type, ITERATOR, O, S > li) |
| A special assignment operator. | |
| template<matrix_order O, matrix_style S> | |
| Matrix & | operator+= (const Matrix< T_type, O, S > &M) |
| Add another Matrix to this Matrix. | |
| Matrix & | operator+= (T_type x) |
| Add a scalar to this Matrix. | |
| template<matrix_order O, matrix_style S> | |
| Matrix & | operator-= (const Matrix< T_type, O, S > &M) |
| Subtract another Matrix from this Matrix. | |
| Matrix & | operator-= (T_type x) |
| Subtract a scalar from this Matrix. | |
| template<matrix_order O, matrix_style S> | |
| Matrix & | operator%= (const Matrix< T_type, O, S > &M) |
| Multiply the elements of this Matrix with another's. | |
| Matrix & | operator%= (T_type x) |
| Multiply this Matrix by a scalar. | |
| template<matrix_order O, matrix_style S> | |
| Matrix & | operator/= (const Matrix< T_type, O, S > &M) |
| Divide the elements of this Matrix by another's. | |
| Matrix & | operator/= (T_type x) |
| Divide this Matrix by a scalar. | |
| template<matrix_order O, matrix_style S> | |
| Matrix & | operator^= (const Matrix< T_type, O, S > &M) |
| Exponentiate the elements of this Matrix by another's. | |
| Matrix & | operator^= (T_type x) |
| Exponentiate this Matrix by a scalar. | |
| template<matrix_order O, matrix_style S> | |
| Matrix & | operator*= (const Matrix< T_type, O, S > &M) |
| Multiply this Matrix by another. | |
| Matrix & | operator*= (T_type x) |
| Multiply this Matrix by a scalar. | |
| template<matrix_order O, matrix_style S> | |
| Matrix & | kronecker (const Matrix< T_type, O, S > &M) |
| Kronecker multiply this Matrix by another. | |
| Matrix & | kronecker (T_type x) |
| Kronecker multiply this Matrix by a scalar. | |
| template<matrix_order O, matrix_style S> | |
| Matrix & | operator&= (const Matrix< T_type, O, S > &M) |
| Logically AND this Matrix with another. | |
| Matrix & | operator&= (T_type x) |
| Logically AND this Matrix with a scalar. | |
| template<matrix_order O, matrix_style S> | |
| Matrix & | operator|= (const Matrix< T_type, O, S > &M) |
| Logically OR this Matrix with another. | |
| Matrix & | operator|= (T_type x) |
| Logically OR this Matrix with a scalar. | |
| void | resize (uint rows, uint cols, bool preserve=false) |
| Resize or reshape a Matrix. | |
| template<typename T , matrix_order O, matrix_style S> | |
| void | resize2Match (const Matrix< T, O, S > &M, bool preserve=false) |
| Resize a Matrix to match another. | |
| void | detach () |
| Copy the contents of this Matrix to a new DataBlock. | |
| void | swap (Matrix &M) |
| Swap this Matrix with another. | |
| bool | isZero () const |
| Returns true if every element in this Matrix equals 0. | |
| bool | isDiagonal () const |
| Returns true if this Matrix is square and its off-diagonal elements are all 0. | |
| bool | isIdentity () const |
| Returns true if this Matrix is diagonal and its diagonal elements are all 1s. | |
| bool | isLowerTriangular () const |
| Returns true if all of this Matrix's above-diagonal elements equal 0. | |
| bool | isUpperTriangular () const |
| Returns true if all of this Matrix's below-diagonal elements equal 0. | |
| bool | isSingular () const |
| Returns true if this Matrix is square and has no inverse. | |
| bool | isSymmetric () const |
| bool | isSkewSymmetric () const |
| template<matrix_order O, matrix_style S> | |
| bool | equals (const Matrix< T_type, O, S > &M) const |
| Test Matrix equality. | |
| bool | equals (T_type x) const |
| Test Matrix equality. | |
| T_type * | getArray () const |
| Returns a pointer to this Matrix's internal data array. | |
| void | save (const std::string &path, const char flag= 'n', const bool header=false) const |
| Saves a Matrix to disk. | |
| template<matrix_order I_ORDER> | |
| matrix_random_access_iterator < T_type, I_ORDER, ORDER, STYLE > | begin () |
| Get an iterator pointing to the start of a Matrix. | |
| template<matrix_order I_ORDER> | |
| const_matrix_random_access_iterator < T_type, I_ORDER, ORDER, STYLE > | begin () const |
| Get an iterator pointing to the start of a Matrix. | |
| template<matrix_order I_ORDER> | |
| matrix_random_access_iterator < T_type, I_ORDER, ORDER, STYLE > | end () |
| Get an iterator pointing to the end of a Matrix. | |
| template<matrix_order I_ORDER> | |
| const_matrix_random_access_iterator < T_type, I_ORDER, ORDER, STYLE > | end () const |
| Get an iterator pointing to the end of a Matrix. | |
| template<matrix_order I_ORDER> | |
| std::reverse_iterator < matrix_random_access_iterator < T_type, I_ORDER, ORDER, STYLE > > | rbegin () |
| Get a reverse iterator pointing to the end of a Matrix. | |
| template<matrix_order I_ORDER> | |
| std::reverse_iterator < const_matrix_random_access_iterator < T_type, I_ORDER, ORDER, STYLE > > | rbegin () const |
| Get a reverse iterator pointing to the end of a Matrix. | |
| template<matrix_order I_ORDER> | |
| std::reverse_iterator < matrix_random_access_iterator < T_type, I_ORDER, ORDER, STYLE > > | rend () |
| Get a reverse iterator pointing to the start of a Matrix. | |
| template<matrix_order I_ORDER> | |
| std::reverse_iterator < const_matrix_random_access_iterator < T_type, I_ORDER, ORDER, STYLE > > | rend () const |
| Get a reverse iterator pointing to the start of a Matrix. | |
| iterator | begin () |
| Get an iterator pointing to the start of a Matrix. | |
| const_iterator | begin () const |
| Get an iterator pointing to the start of a Matrix. | |
| iterator | end () |
| Get an iterator pointing to the end of a Matrix. | |
| const_iterator | end () const |
| Get an iterator pointing to the end of a Matrix. | |
| reverse_iterator | rbegin () |
| Get a reverse iterator pointing to the end of a Matrix. | |
| const_reverse_iterator | rbegin () const |
| Get a reverse iterator pointing to the end of a Matrix. | |
| reverse_iterator | rend () |
| Get a reverse iterator pointing to the start of a Matrix. | |
| const_reverse_iterator | rend () const |
| Get a reverse iterator pointing to the start of a Matrix. | |
| template<matrix_order I_ORDER> | |
| matrix_forward_iterator < T_type, I_ORDER, ORDER, STYLE > | begin_f () |
| Get an iterator pointing to the start of a Matrix. | |
| template<matrix_order I_ORDER> | |
| const_matrix_forward_iterator < T_type, I_ORDER, ORDER, STYLE > | begin_f () const |
| Get an iterator pointing to the start of a Matrix. | |
| template<matrix_order I_ORDER> | |
| matrix_forward_iterator < T_type, I_ORDER, ORDER, STYLE > | end_f () |
| Get an iterator pointing to the end of a Matrix. | |
| template<matrix_order I_ORDER> | |
| const_matrix_forward_iterator < T_type, I_ORDER, ORDER, STYLE > | end_f () const |
| Get an iterator pointing to the end of a Matrix. | |
| forward_iterator | begin_f () |
| Get an iterator pointing to the start of a Matrix. | |
| const_forward_iterator | begin_f () const |
| Get an iterator pointing to the start of a Matrix. | |
| forward_iterator | end_f () |
| Get an iterator pointing to the end of a Matrix. | |
| const_forward_iterator | end_f () const |
| Get an iterator pointing to the end of a Matrix. | |
| template<matrix_order I_ORDER> | |
| matrix_bidirectional_iterator < T_type, I_ORDER, ORDER, STYLE > | begin_bd () |
| Get an iterator pointing to the start of a Matrix. | |
| template<matrix_order I_ORDER> | |
| const_matrix_bidirectional_iterator < T_type, I_ORDER, ORDER, STYLE > | begin_bd () const |
| Get an iterator pointing to the start of a Matrix. | |
| template<matrix_order I_ORDER> | |
| matrix_bidirectional_iterator < T_type, I_ORDER, ORDER, STYLE > | end_bd () |
| Get an iterator pointing to the end of a Matrix. | |
| template<matrix_order I_ORDER> | |
| const_matrix_bidirectional_iterator < T_type, I_ORDER, ORDER, STYLE > | end_bd () const |
| Get an iterator pointing to the end of a Matrix. | |
| template<matrix_order I_ORDER> | |
| std::reverse_iterator < matrix_bidirectional_iterator < T_type, I_ORDER, ORDER, STYLE > > | rbegin_bd () |
| Get a reverse iterator pointing to the end of a Matrix. | |
| template<matrix_order I_ORDER> | |
| std::reverse_iterator < const_matrix_bidirectional_iterator < T_type, I_ORDER, ORDER, STYLE > > | rbegin_bd () const |
| Get a reverse iterator pointing to the end of a Matrix. | |
| template<matrix_order I_ORDER> | |
| std::reverse_iterator < matrix_bidirectional_iterator < T_type, I_ORDER, ORDER, STYLE > > | rend_bd () |
| Get a reverse iterator pointing to the start of a Matrix. | |
| template<matrix_order I_ORDER> | |
| std::reverse_iterator < const_matrix_bidirectional_iterator < T_type, I_ORDER, ORDER, STYLE > > | rend_bd () const |
| Get a reverse iterator pointing to the start of a Matrix. | |
| bidirectional_iterator | begin_bd () |
| Get an iterator pointing to the start of a Matrix. | |
| const_bidirectional_iterator | begin_bd () const |
| Get an iterator pointing to the start of a Matrix. | |
| bidirectional_iterator | end_bd () |
| Get an iterator pointing to the end of a Matrix. | |
| const_bidirectional_iterator | end_bd () const |
| Get an iterator pointing to the end of a Matrix. | |
| reverse_bidirectional_iterator | rbegin_bd () |
| Get a reverse iterator pointing to the end of a Matrix. | |
| const_reverse_bidirectional_iterator | rbegin_bd () const |
| Get a reverse iterator pointing to the end of a Matrix. | |
| reverse_bidirectional_iterator | rend_bd () |
| Get a reverse iterator pointing to the start of a Matrix. | |
| const_reverse_iterator | rend_bd () const |
| Get a reverse iterator pointing to the start of a Matrix. | |
Detailed Description
template<typename T_type = double, matrix_order ORDER = Col, matrix_style STYLE = Concrete>
class scythe::Matrix< T_type, ORDER, STYLE >
An STL-compliant matrix container class.
The Matrix class provides a matrix object with an interface similar to standard mathematical notation. The class provides a number of unary and binary operators for manipulating matrices. Operators provide such functionality as addition, multiplication, and access to specific elements within the Matrix. One can test two matrices for equality or use provided methods to test the size, shape, or symmetry of a given Matrix. In addition, we provide a number of facilities for saving, loading, and printing matrices. Other portions of the library provide functions for manipulating matrices. Most notably, la.h provides definitions of common linear algebra routines and ide.h defines functions that perform inversion and decomposition.
This Matrix data structure sits at the core of the library. In addition to standard matrix operations, this class allows multiple matrices to view and modify the same underlying data. This ability provides an elegant way in which to access and modify submatrices such as isolated row vectors and greatly increases the overall flexibility of the class. In addition, we provide iterators (defined in matrix_random_access_iterator.h, matrix_forward_iterator.h, and matrix_bidirectional_iterator.h) that allow Matrix objects to interact seamlessly with the generic algorithms provided by the Standard Template Library (STL).
The Matrix class uses template parameters to define multiple behaviors. Matrices are templated on data type, matrix_order, and matrix_style.
Matrix objects can contain elements of any type. For the most part, uses will wish to fill their matrices with single or double precision floating point numbers, but matrices of integers, boolean values, complex numbers, and user-defined types are all possible and useful. Although the basic book-keeping methods in the Matrix class will support virtually any type, certain operators require that one or more mathematical operator be defined for the given type and many of the functions in the wider Scythe library expect, or even demand, matrices containing floating point numbers.
There are two possible Matrix element orderings, row- or column-major. Differences in matrix ordering will be most noticeable at construction time. Constructors that build matrices from streams or other list-like structures will place elements into the matrix in its given order. In general, any method that processes a matrix in order will use the given matrix_order. For the most part, matrices of both orderings should exhibit the same performance, but when a trade-off must be made, we err on the side of column-major ordering. In one respect, this bias is very strong. If you enable LAPACK/BLAS support in with the SCYTHE_LAPACK compiler flag, the library will use these optimized fortran routines to perform a number of operations on column major matrices; we provide no LAPACK/BLAS support for row-major matrices. Operations on matrices with mismatched ordering are legal and supported, but not guaranteed to be as fast as same-order operations, especially when SCYTHE_LAPACK is enabled.
There are also two possible styles of Matrix template, concrete and view. These two types of matrix provide distinct ways in which to interact with an underlying block of data.
Concrete matrices behave like matrices in previous Scythe releases. They directly encapsulate a block of data and always process it in the same order as it is stored (their matrix_order always matches the underlying storage order). All copy constructions and assignments on concrete matrices make deep copies and it is not possible to use the reference() method to make a concrete Matrix a view of another Matrix. Furthermore, concrete matrices are guaranteed to have unit stride (That is, adjacent Matrix elements are stored adjacently in memory).
Views, on the other hand, provide references to data blocks. More than one view can look at the same underlying block of data, possibly at different portions of the data at the same time. Furthermore, a view may look at the data block of a concrete matrix, perhaps accessing a single row vector or a small submatrix of a larger matrix. When you copy construct a view a deep copy is not made, rather the view simply provides access to the extant block of data underlying the copied object. Furthermore, when you assign to a view, you overwrite the data the view is currently pointing to, rather than generating a new data block. Together, these behaviors allow for matrices that view portions of other matrices (submatrices) and submatrix assignment. Views do not guarantee unit stride and may even logically access their elements in a different order than they are stored in memory. Copying between concretes and views is fully supported and often transparent to the user.
There is a fundamental trade-off between concrete matrices and views. Concrete matrices are simpler to work with, but not as flexible as views. Because they always have unit stride, concrete matrices have fast iterators and access operators but, because they must always be copied deeply, they provide slow copies (for example, copy construction of a Matrix returned from a function wastes cycles). Views are more flexible but also somewhat more complicated to program with. Furthermore, because they cannot guarantee unit stride, their iterators and access operations are somewhat slower than those for concrete matrices. On the other hand, they provide very fast copies. The average Scythe user may find that she virtually never works with views directly (although they can be quite useful in certain situations) but they provide a variety of functionality underneath the hood of the library and underpin many common operations.
- Note:
- The Matrix interface is split between two classes: this Matrix class and Matrix_base, which Matrix extends. Matrix_base includes a range of accessors that provide the programmer with information about such things as the dimensionality of Matrix objects.
The documentation for this class was generated from the following file:
- scythestat/matrix.h
