mi32/matrix.h

Go to the documentation of this file.

/**
 * \file matrix.h <mi32/matrix.h>
 * \brief Definitions for matrix manipulation functions
 *
 * \if NODOC
 * $Id: matrix.h_v 1.23 2005/03/31 16:57:15 fileserver!dwilliss Exp $
 *
 * $Log: matrix.h_v $
 * Revision 1.23  2005/03/31 16:57:15  fileserver!dwilliss
 * Rename one of our types to MIUNICODE because it conflicted with a Microsoft #define
 *
 * Revision 1.22  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.21  2002/06/12 13:13:25  mju
 * nc.
 *
 * Revision 1.20  2000/12/22 17:50:23  dwilliss
 * Principle Componants function now takes real pointer for type-safety
 * instead of (void*)
 *
 * Revision 1.19  2000/06/20 17:56:01  sparsons
 * Genitor documentation.
 *
 * Revision 1.18  2000/06/14 13:26:27  mju
 * Include stddefns so compiles in isolation.
 *
 * \endif
**/

#ifndef  INC_MI32_MATRIX_H
#define  INC_MI32_MATRIX_H

#ifndef INC_MI32_STDDEFNS_H
#include <mi32/stddefns.h>
#endif

#if defined(__cplusplus)
extern "C" {
#endif


struct PRINCOMPPARMS;   //!< For a prototype later...

typedef struct _MATRIX {
   double **matrix;                    //!<  Matrix data 
   UINT16 rows;                        //!<  Number of rows 
   UINT16 cols;                        //!<  Number of columns 
   UINT32 flags;
   } *MATRIX;

#define  MATFLAG_Symmetric       0x00000001        //!<  Matrix is symmetric 
#define  MATFLAG_NoDiagonal      0x00000002        //!<  Don't allocate space for diagonal (symmetric only) 

//! Retrieve value from matrix.
#define  MatGetValue(m,i,j)      ((m)->matrix[i][j])
//! Set single matrix entry to a specified value.
#define  MatSetValue(m,i,j,v)    ((m)->matrix[i][j]=(v))
//! Determine if "symmetric" flag set for a matrix.
#define  MatIsSymmetric(m)       ((m)->flags&MATFLAG_Symmetric)

//! Add one matrix to another of the same size.
int MatAddMatrix (
   MATRIX outmatrix,                   //!< Output matrix, may be the same as either input matrix
   MATRIX matrixA,                     //!< First input matrix
   MATRIX matrixB                      //!< Second input matrix, if NULL will use outmatrix
   );

//! Add scalar value to a matrix.
void MatAddScalar (
   MATRIX matrix,                      //!< Matrix to use 
   double value                        //!< Value to add to all matrix elements
   );

//! Copy one matrix to another.
//!
//! The output matrix will be resized if it exists and is not the same size as the input matrix.
int MatCopy (
   MATRIX *outmatrix,                  //!< Matrix to copy to, will be created if NULL
   MATRIX inmatrix                     //!< Matrix to copy from
   );

//! Create a new matrix.
//!
//! Flags:
//!      MATFLAG_Symmetric    Matrix is symmetric, don't allocate space for elements above diagonal
//!      MATFLAG_NoDiagonal   Don't allocate space for diagonal elements (symmetric only)
//!
//!   All matrix elements will be initialized to 0.
int MatCreate (
   MATRIX *matrix,                     //!< Matrix returned
   UINT16 rows,                        //!< Number of rows in matrix
   UINT16 cols,                        //!< Number of columns in matrix
   UINT32 flags                        //!< Flags
   );

//! Destroy a matrix.
void MatDestroy (
   MATRIX matrix                       //!< Matrix to be destroyed
   );

//! Compute determinate of a square matrix.
int MatDeterminant (
   MATRIX matrix,                      //!< Matrix to compute determinant for
   double *detvalue                    //!< Determinant returned
   );

//! Create or extract diagonals.
//!
//! If input is a vector with N components MatDiag(input,K) is a square matrix
//!   of order N + ABS(K) with elements of input on the K-th diagonal.
//!   K = 0 is a main diagonal, K > 0 is above main diagonal , K < 0 below.
//!   If input is a matrix, MatDiag(input,K) is a column vector formed from the
//!   element of K-th diagonal.
int MatDiag (
   MATRIX input,                       //!< Input matrix
   int k,                              //!< Diagonal number
   MATRIX *output                      //!< Output matrix (or vector) created 
   );

//! Compute eigenvectors and eigenvalues of the SYMMETRIC matrix.
//!
//! WARNING: This function computes eigen-stuff for SYMMETRIC matrices ONLY.
//!   Example: correlation /covariation matrix. 
//!   NO CHECKING IS PERFORMED ON INPUT TO MAKE SURE IT'S SYMMETRIC.
int MatEigenvectors (
   MATRIX matrix,                      //!< Matrix to use
   MATRIX *vectors,                    //!< Matrix returned, that contain eigenvectors as columns
   MATRIX *values                      //!< Matrix returned (vector), that contains eigenvalues
   );

//! Get a "condition number" of the matrix.
//!
//! @return 0.0 instead of INFINITY just to simplify handling of the result.
//!
//! EXPLANATION:
//!   The condition number of a matrix is defined as the ratio of the largest
//!   (in magnitude) of the elements of matrix W to the smallest one.
//!   Where W is one of the results of SVD defined as:
//!                      T
//!         A = U * W * V  (see MatSVD function).              
//!   A matrix is singular if it's condition number approaches infinity or
//!   just very large. 
double MatGetConditionNumber (
   MATRIX matrix
   );

//! Retrieve value from matrix with range check.
//!
//! @return Value in matrix. 
//! This function will return 0.0 for values outside the matrix.  It also handles symmetric matrices.
double MatGetValueTest (
   MATRIX matrix,                      //!< Matrix to retrieve value from
   UINT16 row,                         //!< Row in matrix (0 - numrows-1)
   UINT16 col                          //!< Column in matrix (0 - numcols-1)
   );

//! Compute inverse of a square matrix.
int MatInverse (
   MATRIX outmatrix,                   //!< Inverse matrix computed
   MATRIX inmatrix,                    //!< Matrix to compute inverse of
   int maxiterations,                  //!< Maximum iterations for convergence (0 for default)
   double maxerror                     //!< Maximum error, (0.0 for default)
   );

//! Determine if matrix has at least one non-zero on diagonal and zeros elsewhere.
int MatIsDiagonal (
   MATRIX matrix,                      //!< Matrix to use
   double tolerance                    //!< Define minimal value, everything less than tolerance will be treated as zero.
   );

//! Determine if matrix A equals to matrix B.
//!
//! This function checks if 2 matrices have similar size and all 
//!   corresponding values are equal within tolerance.
int MatIsEqual (
   MATRIX A,                           //!< Matrix to use
   MATRIX B,                           //!< Matrix to use
   double tolerance                    //!< Define minimal value, everything less than tolerance will be treated as zero.
   );

//! Determine if matrix is singular.
//!
//! NOTE: This function computes SVD, so it's no a fast check!
//!   This function calls MatGetConditionNumber() with some default tolerances.
int MatIsSingular (
   MATRIX matrix                       //!< Matrix to use
   );

//! Determine if matrix has all elements equal to 0.0.
int MatIsZero (
   MATRIX matrix,                      //!< Matrix to use 
   DOUBLE tolerance                    //!< Define minimal value, everything less than tolerance will be treated as zero.
   );

//! Multiply one matrix by another.
int MatMultMatrix (
   MATRIX outmatrix,                   //!< Output matrix, may be the same as either input matrix
   MATRIX matrixA,                     //!< Left matrix, will use outmatrix if NULL
   MATRIX matrixB                      //!< Right matrix, will use outmatrix if NULL
   );

//! Multiply a matrix by a scalar.
void MatMultScalar (
   MATRIX matrix,                      //!< Matrix to use
   double value                        //!< Value to multiply all matrix elements by
   );

//! Compute orthonormal basis for set of vectors.
//! 
//! Suppose that you have N vectors in an M-dimensional vector space,
//!   with N <= M. Then N vectors span some subspace of the full vector space.
//!   The right way to construct an orthonormal basis for a subspace is by SVD.
//!   Form M x N matrix A whose N columns are your vectors. Run the matrix
//!   through MatSVD. The columns of the matrix U are your desired orthonormal basis vectors.
int MatOrthoBasis (
   MATRIX *vectors,                    //!< Array of vectors (number of columns = 1)
   int numvectors,                     //!< Number of input vectors
   MATRIX *basis                       //!< Matrix returned, columns are orthonormal basis vectors
   );

//! Compute pseudoinverse of the matrix using SVD  
//!
//! If Input matrix is not singular pseudoinverse is equal to
//!   normal inverse of the matrix. 
//! EXPLANATION:
//!   Pseudoinverse is such matrix X that satisfy the following condition:
//!      A * X * A = A, if matrix A is singular X still exists.
int MatPseudoInverse (
   MATRIX inverse,                     //!< Output pseudoinverse
   MATRIX input,                       //!< Input matrix
   double tolerance                    //!< Tolerance to use, if in doubt pass 0.0 and function will use built-in defaults
   );

//! Resize a matrix.
//!
//! Newly created elements will be initialized to 0.
int MatResize (
   MATRIX matrix,                      //!< Matrix to be resized
   UINT16 newrows,                     //!< New number of rows
   UINT16 newcols                      //!< New number of columns
   );

//! Determine if two matrices are the same size.
//!
//! @return 1 if matrices have the same number of rows/columns, 0 if not.
int MatSameSize (
   MATRIX matrix1, 
   MATRIX matrix2
   );

//! Set all entries in a matrix to a specified scalar value.
void MatSetScalar (
   MATRIX matrix,                      //!< Matrix to use
   double value                        //!< Value to set all matrix elements to
   );

//! Set matrix to a identity.
int MatSetIdentity (
   MATRIX matrix                       //!< Matrix to use
   );

//! Compute Singular Value Decomposition (SVD).
//!
//! This function computes SVD as A = U * W * V ;
//!   Output matrix U has the same dimension as input matrix A. 
//!   The diagonal matrix of singular values W is output as a vector.
//!   The matrix V (not transpose of V) is output as a matrix.
int MatSVD (
   MATRIX A,                           //!< Input matrix
   MATRIX *U,                          //!< Returned
   MATRIX *W,                          //!< Returned
   MATRIX *V                           //!< Returned
   );

//! Stable Solution of system of linear equation using SVD algorithm.
//!
//! A * X = B where A(M x N) matrix and X (N) vector. B(M) is also a vector.
//!   X is the output solution vector.
//!   Matrix A is decomposed into U(M x N), W(N) and V(N x N) matrices using SVD operation.
int MatSVDSolve (
   MATRIX A,                           //!< Input matrix of equations
   MATRIX B,                           //!< Input vector that contains right side of equations
                                       //! NOTE: you can pass ANY type of vector: numrows = 1 or numcols = 1
   MATRIX X,                           //!< Solution returned
   double tolerance                    //!< Tolerance to use, if in doubt pass 0.0 for defaults
   );

//! 
int MatSVDSolveAutoTolerance (
   MATRIX A, 
   MATRIX B, 
   MATRIX X                            //!< Size of A->cols x 1
   );

//! 
int MatSVDSolveAutoToleranceFast (
   MATRIX A, 
   MATRIX U, 
   MATRIX W, 
   MATRIX V, 
   MATRIX B, 
   MATRIX X                            //!< Size of A->cols x 1
   );

//! Subtract one matrix from another.
int MatSubMatrix (
   MATRIX outmatrix,                   //!< Output matrix, may be the same as either input matrix
   MATRIX matrixA,                     //!< Matrix to subtract FROM
   MATRIX matrixB                      //!< Second to subtract, if NULL will subtract matrixA from outmatrix
   );

//! Compute trace of the matrix: sum of it's diagonal elements.
double MatTrace (
   MATRIX matrix                       //!< Matrix to use
   );

//! Transpose a matrix.
int MatTranspose (
   MATRIX outmatrix,                   //!< Output matrix (may be the same as the input matrix)
   MATRIX inmatrix                     //!< Input matrix
   );

//! Computes forward and inverse principal components transformation.
int RasterLinearCombComputePrinComp (
   FNAMEINODEUC *fnameinode,           //!< List of input rasters (must be the same size)
   MIUNICODE *maskfilename,               //!< NULL if not needed
   INT32 maskinode,                    //!< Mask object inode
   INT32 colsample,                    //!< Sampling rates for analysis (1 - default)
   INT32 linsample,                    
   MATRIX *forward,                    //!< Forward PC transformation
   MATRIX *inverse,                    //!< Inverse PC transformation
   PRINCOMPPARMS *parm,                //!< See mi32p/princomp.h, NULL if not needed
   UINT32 flags                        //!< Flags
   );

//! Computes coefficients of multilinear regression equations.
int RasterLinearCombMultRegression (
   FNAMEINODEUC *fnameinode,           //!< List of input rasters (must be the same size) 
   MIUNICODE *maskfilename,               //!< NULL if not needed
   INT32 maskinode,                    //!< Mask object inode
   INT32 colsample,                    //!< Sampling rates for analysis (1 - default)
   INT32 linsample,                    
   MATRIX *MatMLR,                     //!< Matrix of MLR coefficients returned: 
                                       //!      matrix(numrasts,numrasts+1), first column - offsets;
   UINT32 flags                        //!< Flags
   );

#if defined(__cplusplus)
}
#endif

#endif   //!<  #ifdef INC_MI32_MATRIX_H 

---