FST::Indexed_Matrix< DATATYPE, DIMTYPE, SUBSET > Class Template Reference

Matrix representation and operations, allows operation in selected subspace. More...

#include <indexed_matrix.hpp>

Public Types
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to the feature subset consumed by narrow_to()

Public Member Functions
	Indexed_Matrix (const DIMTYPE n, bool LUstorage=false)
	allocates for an n x n matrix; LUstorage true also allocates the permutation/whereis buffers LUdecompose() needs (i.e. this instance is meant to serve as an LU-decomposition result buffer)
	Indexed_Matrix (const Indexed_Matrix &im)
	copy-constructor (deep-copies the raw buffer, index map, and any allocated LU/temporary buffers)
Indexed_Matrix &	operator= (Indexed_Matrix const &im)
	deep-copy assignment (reallocates only where capacity or LU-storage presence differs from im's)
void	reset (const DIMTYPE n_max, bool LUstorage=false)
	reallocates
void	redim (const DIMTYPE n=0)
	keeps main allocations, just resets index arrays and adjusts _n; n==0 here equals _n_max
DATATYPE &	at_raw (const DIMTYPE row, const DIMTYPE col)
	raw (unindexed) element access, row and col in [0,get_n())
DATATYPE &	at (const DIMTYPE row, const DIMTYPE col)
	indexed access through the narrow_to() subset map – both row and col are mapped, row/col in [0,get_d())
DATATYPE *	get_row_raw (const DIMTYPE row)
	pointer to the start of raw row row (unindexed, get_n() entries), row in [0,get_n())
DATATYPE *	get_row (const DIMTYPE row)
	pointer to the start of matrix row _index[row] (only the row is subset-mapped – the returned row still spans all get_n() raw columns, unlike at()), row in [0,get_d())
void	narrow_to (const PSubset sub)
	fill _index[] -> access to data is then mapped to sub-matrix
void	denarrow ()
	reset _index[] -> access is reset to the full matrix
DIMTYPE	get_n_max () const
	the allocated capacity (max n the matrix can reset()/redim() to without reallocating)
DIMTYPE	get_n () const
	the full ("raw") dimensionality currently in use, get_n()<=get_n_max()
DIMTYPE	get_d () const
	the current virtual (narrow_to()'d) dimensionality, get_d()<=get_n()
void	set_all_raw_to (const DATATYPE val)
	sets all get_n()*get_n() raw entries to val (ignores the index map)
void	add_raw (const Indexed_Matrix &mr)
	this += mr, elementwise over the raw get_n()*get_n() entries (requires mr.get_n()==get_n())
void	add_constmul_raw (const Indexed_Matrix &mr, const DATATYPE mul)
	this += mul * mr, elementwise over the raw get_n()*get_n() entries (requires mr.get_n()==get_n())
void	copy_constmul_raw (const Indexed_Matrix &mr, const DATATYPE mul)
	this = mul * mr, elementwise over the raw get_n()*get_n() entries (an assignment, not an accumulation; requires mr.get_n()==get_n())
void	copy_raw (const Indexed_Matrix &mr)
	this = mr, elementwise over the raw get_n()*get_n() entries (requires mr.get_n()==get_n())
void	LUdecompose (Indexed_Matrix &result)
void	solve_equations (Indexed_Vector< DATATYPE, DIMTYPE, SUBSET > &result_vec, const Indexed_Matrix &LU_matrix, Indexed_Vector< DATATYPE, DIMTYPE, SUBSET > &coef_vec)
void	invert (Indexed_Matrix &result, const Indexed_Matrix &LU_matrix)
DATATYPE	determinant (const Indexed_Matrix &LU_matrix)
DATATYPE	log_determinant (const Indexed_Matrix &LU_matrix)

Protected Attributes
DIMTYPE	_n_max
	allocated space can hold _n_max*_n_max matrix
DIMTYPE	_n
	full feature set dimensionality
std::unique_ptr< DATATYPE[]>	_data
	raw matrix data, _n_max*_n_max entries, row by row
std::unique_ptr< DIMTYPE[]>	_permut
	LU row permutation, physical row -> logical row (the inverse of _tmp_whereis); allocated only for an LUstorage matrix.
int	_sign
	sign of the LU row permutation (+1/-1; 0 before any decomposition), the factor determinant() needs
DIMTYPE	_d
	virtual sub-matrix (as represented by _index) dimensionality
std::unique_ptr< DIMTYPE[]>	_index
	maps virtual sub-matrix _d dimensions to original _n dimensions
std::unique_ptr< DATATYPE[]>	_tmp_rowscale
	reciprocals of the row maxima (implicit row scaling used for pivot choice); allocated on the first LUdecompose() call and kept
std::unique_ptr< DIMTYPE[]>	_tmp_whereis
	LU row permutation, logical row -> physical row in _data (the map that replaces physical row swapping); allocated only for an LUstorage matrix.
std::unique_ptr< Indexed_Vector< DATATYPE, DIMTYPE, SUBSET > >	_tmp_eq_coefs
	right-hand side handed to solve_equations() by invert() (allocated on first use)
std::unique_ptr< Indexed_Vector< DATATYPE, DIMTYPE, SUBSET > >	_tmp_eq_roots
	solution vector returned by solve_equations() to invert() (allocated on first use)

Friends
std::ostream &	operator<< (std::ostream &os, const Indexed_Matrix &mr)
	grants operator<< access to print this object's contents (see the out-of-class definition below)

Detailed Description

template<typename DATATYPE, typename DIMTYPE, class SUBSET>
class FST::Indexed_Matrix< DATATYPE, DIMTYPE, SUBSET >

Matrix representation and operations, allows operation in selected subspace.

Member Function Documentation

determinant()

template<typename DATATYPE, typename DIMTYPE, class SUBSET>

DATATYPE FST::Indexed_Matrix< DATATYPE, DIMTYPE, SUBSET >::determinant

(

const Indexed_Matrix< DATATYPE, DIMTYPE, SUBSET > &

LU_matrix

)

Determinant of the matrix that LU_matrix was decomposed from: the product of the LU diagonal times the permutation sign. The product over- or underflows well before the matrix itself becomes numerically hopeless – prefer log_determinant() above roughly a hundred dimensions.

invert()

template<typename DATATYPE, typename DIMTYPE, class SUBSET>

void FST::Indexed_Matrix< DATATYPE, DIMTYPE, SUBSET >::invert	(	Indexed_Matrix< DATATYPE, DIMTYPE, SUBSET > &	result,
		const Indexed_Matrix< DATATYPE, DIMTYPE, SUBSET > &	LU_matrix )

Inverts the matrix that LU_matrix was decomposed from, into result (raw, pre-allocated with get_n()==this->get_d()). Implemented as get_d() solve_equations() calls against the unit vectors, so it inherits their underflow behaviour. Uses two internal work vectors of this object, allocated on first use.

log_determinant()

template<typename DATATYPE, typename DIMTYPE, class SUBSET>

DATATYPE FST::Indexed_Matrix< DATATYPE, DIMTYPE, SUBSET >::log_determinant

(

const Indexed_Matrix< DATATYPE, DIMTYPE, SUBSET > &

LU_matrix

)

ln|det| of the matrix that LU_matrix was decomposed from, as the sum of the logarithms of the LU diagonal magnitudes: the overflow-safe companion of determinant() for high dimensionalities. The sign is discarded (the normal-model callers work with positive-definite covariance matrices).

LUdecompose()

template<typename DATATYPE, typename DIMTYPE, class SUBSET>

void FST::Indexed_Matrix< DATATYPE, DIMTYPE, SUBSET >::LUdecompose

(

Indexed_Matrix< DATATYPE, DIMTYPE, SUBSET > &

result

)

Decomposes the currently narrowed get_d() x get_d() sub-matrix into the LU factorization stored in result (L and U packed into one raw matrix, plus the row permutation and its sign). result must be an LUstorage matrix with get_n()==this->get_d(); it is denarrow()'d and overwritten. Throws fst_error (code 23) when some row of the sub-matrix is entirely zero to within the smallest representable magnitude, i.e. the matrix is singular; individual pivots that merely underflow are clamped instead (see the definition below).

solve_equations()

template<typename DATATYPE, typename DIMTYPE, class SUBSET>

void FST::Indexed_Matrix< DATATYPE, DIMTYPE, SUBSET >::solve_equations	(	Indexed_Vector< DATATYPE, DIMTYPE, SUBSET > &	result_vec,
		const Indexed_Matrix< DATATYPE, DIMTYPE, SUBSET > &	LU_matrix,
		Indexed_Vector< DATATYPE, DIMTYPE, SUBSET > &	coef_vec )

Solves A*x=b for the matrix A that LU_matrix was decomposed from: coef_vec is the right-hand side b (read raw, unchanged), result_vec receives the solution x (raw, pre-allocated to at least get_d() entries). Back-substitution by a pivot below the smallest representable magnitude yields +/-max() for that component and a notify() message rather than an exception.

---

The documentation for this class was generated from the following file:

• /Users/psms/dev/devtest1/_src_criteria/indexed_matrix.hpp