cmatrix.h

大地测量专业计算软件

/// \return TRUE if successful, FALSE if empty or has dimensions larger
///         than 3x3, false if singular or not square
BOOL MTX_InvertInPlaceClosedForm( MTX *M );

/// \brief  Compute the inplace inverse of the matrix.
///         Uses fast closed form solutions for:
///         Only for: 1x1, 2x2, 3x3
///
/// \return TRUE if successful, FALSE if empty or has dimensions larger
///         than 3x3, false if singular or not square
BOOL MTX_InvertClosedForm( const MTX *M, MTX *dst );


/// \brief  Compute the inplace inverse of a matrix.
///
/// The matrix is first tested to determine if it is a symmetric 
/// positive-definite matrix. If so, Cholesky decomposition is used
/// to facilitate the inversion of a lower triangular matrix. If the
/// matrix is not symmetric and positive-definite robust inversion
/// using gaussing elimination is attempted.
///
/// 3x3 matrices or smaller dimensions are computed using 
/// MTX_InvertInPlaceClosedForm.
/// 
/// If the matrix is singular, the original matrix is unchanged.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_InvertInPlace( MTX *M  );


/// \brief  Compute the inverse of a matrix.
///
/// The matrix is first tested to determine if it is a symmetric 
/// positive-definite matrix. If so, Cholesky decomposition is used
/// to facilitate the inversion of a lower triangular matrix. If the
/// matrix is not symmetric and positive-definite robust inversion
/// using gaussing elimination is attempted.
///
/// 3x3 matrices or smaller dimensions are computed using 
/// MTX_InvertClosedForm.
/// 
/// If the matrix is singular, the original matrix is unchanged.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Invert( const MTX *src, MTX *dst );

/// \brief  Perfroms an inplace matrix inverse using Gaussian Elimination methods.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_InvertInPlaceRobust( MTX *M );

/// \brief  Computes a moving average using N lead samples and M lagging samples
/// for the specified column and stores it in dst.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ColumnMovAvg( const MTX *src, const unsigned col, const unsigned lead, const unsigned lag, MTX *dst );

/// \brief  Computes a moving average using N lead samples and M lagging samples
/// for the matrix and stores it in dst.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_MovAvg( const MTX *src, const unsigned lead, const unsigned lag, MTX *dst );



/// \brief  Computes: InvATA = inverse( transpose(A) * A ).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ATAInverse( const MTX *A, MTX *InvATA );

/// \brief  Compute the inplace inverse of a unit lower triangular matrix.
/// An example unit lower triangular matrix is: \n
///      A = [     1    0    0;          \n
///               -2    2    0;          \n
///                4   -3    3 ]; with   \n
/// inv(A) = [     1    0    0;          \n
///                1  1/2    0;          \n
///             -1/3  1/2  1/3 ];        \n
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_LowerTriangularInverseInplace( MTX *src );


/// \brief  Computes the determinatnt of the square matrix M.
/// If the matrix is real, only the real value, re is set, im = 0. 
/// If the matrix is complex, both re and im are set.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Det( const MTX *M, double *re, double *im );


/// \brief  LU factorization.
/// Performs a factorization to produce a unit lower  triangular matrix, L, 
/// an upper triangular matrix, U, and permutation matrix P so that
/// P*X = L*U.
/// P, L and U are copmuted correctly if IsFullRank is set to true.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_LUFactorization( const MTX *src, BOOL *IsFullRank, MTX *P, MTX *L, MTX *U );


/// \brief  Retrieve the elements of the matrix specified by the index vectors. 
/// The index vectors must be nx1 real vectors.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_IndexedValues( const MTX *src, const MTX *row_index, const MTX *col_index, MTX *dst );


/// \brief  Set the elements of the matrix specified by the index vectors. 
/// The index vectors must be nx1 real vectors.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_SetIndexedValues( MTX *dst, const MTX *row_index, const MTX *col_index, const MTX *src );


/// \brief  Compute the Fast Fourier Transform of each columns in the src matrix and
/// store it in the dst matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_FFT( const MTX *src, MTX *dst );

/// \brief  Compute the inverse Fast Fourier Transform of each columns in the src matrix and
/// store it in the dst matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_IFFT( const MTX *src, MTX *dst );

/// \brief  Compute the Two-Dimensional Fast Fourier Transform of the src matrix and
/// store it in the dst matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_FFT2( const MTX *src, MTX *dst );

/// \brief  Compute the Two-Dimensional Inverse Fast Fourier Transform of the src matrix and
/// store it in the dst matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_IFFT2( const MTX *src, MTX *dst );


/// \brief  Compute the inplace Fast Fourier Transform of each column of the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_FFT_Inplace( MTX *src);

/// \brief  Compute the inplace inverse Fast Fourier Transform of each column of the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_IFFT_Inplace( MTX *src);


/// \brief  Compute the inplace two dimensional Fast Fourier Transform of the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_FFT2_Inplace( MTX *src);

/// \brief  Compute the inplace two dimensional inverse Fast Fourier Transform of the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_IFFT2_Inplace( MTX *src);



/// \brief  Compute the sine of each element in the matrix. Assumes elements are radians.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_sin( MTX *src );

/// \brief  Compute the sin(pi*x)/(pi*) of each element in the matrix. 
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_sinc( MTX *src );

/// \brief  Compute the hyperbolic sine of each element in the matrix. Assumes elements are radians.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_sinh( MTX *src );

/// \brief  Compute the inverse hyperbolic sine of each element in the matrix. 
/// Results in radians.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_asinh( MTX *src );

/// \brief  Compute the cosine of each element in the matrix. Assumes elements are radians.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_cos( MTX *src );

/// \brief  Compute the hyperbolic cosine of each element in the matrix. Assumes elements are radians.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_cosh( MTX *src );

/// \brief  Compute the inverse hyperbolic cosine of each element in the matrix. 
/// Results in radians.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_acosh( MTX *src );

/// \brief  Compute the tangent of each element in the matrix. Assumes elements are radians.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_tan( MTX *src );

/// \brief  Compute the hyperbolic tangent of each element in the matrix. Assumes elements are radians.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_tanh( MTX *src );

/// \brief  Compute the inverse hyperbolic tangent of each element in the matrix. 
/// Results in radians.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_atanh( MTX *src );


/// \brief  Compute the cotangent of each element in the matrix. Assumes elements are radians.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_cot( MTX *src );

/// \brief  Compute the hyperbolic cotangent of each element in the matrix. Assumes elements are radians.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_coth( MTX *src );



/// \brief  Create a column vector [start:increment:end) beginning at start
/// with step size of increment until less than or equal to end. 
/// Note that arguments must be real scalars. \n
/// e.g. a = 2:2:9   = [2; 4; 6; 8;] \n
/// e.g. b = 2:-2:-9 = [2; 0; -2; -4; -6; -9;] \n
///
/// \return TRUE if successful, FALSE otherwise.    
BOOL MTX_Colon( MTX *dst, const double start, const double increment, const double end );


/** \brief  A very efficient method to remove rows and columns from the matrix.
*
* \code 
*  MTX A;
*  unsigned rows[2];
*  unsigned cols[2];
*  MTX_Init(&A);
*  MTX_Calloc( &A, 4, 4 );
*  MTX_Identity( &A );
*  A.data[0][0] = 100.0;
*  A.data[2][1] = 10.0;
*  A.data[1][2] = 20.0;
*  // remove the first row and column and the third row and column.
*  rows[0] = 0;
*  rows[1] = 2;
*  cols[0] = 0;
*  cols[1] = 2;
*  MTX_RemoveRowsAndColumns( &A, 2, (unsigned*)rows, 2 (unsigned*)cols );
*  // A is now a 2x2 identity matrix.
*  \endcode
*
*  \return TRUE if successful, FALSE otherwise.
*/
BOOL MTX_RemoveRowsAndColumns( 
  MTX *src,        //!< The pointer to the matrix object.
  const unsigned nrows,  //!< The number of rows to remove (the length of the rows array).
  const unsigned rows[], //!< The array of row indices to remove.
  const unsigned ncols,  //!< The number of columns to remove (the length of hte cols array).
  const unsigned cols[]
  );


/** 
\brief  Sets the matrix as the NxN hilbert matrix. H_ij = 1.0 / (i+j-1.0) for i=1:N, j=1:N.

\code
MTX H;
BOOL result;
MTX_Init( &H );
result = MTX_Hilbert( &H, 3);
// H == "[1 1/2 1/3; 1/2 1/3 1/4; 1/3 1/4 1/5]";
\endcode    

\return TRUE if successful, FALSE otherwise.
*/
BOOL MTX_Hilbert( MTX *src, const unsigned N );


/** 
\brief Produce a matrix that is composed of pseudo-random numbers. 
Values are elements are standard normal distribution with mean zero, 
variance of one and standard of deviation one. N(0,1)
 
\code 
MTX A;
MTX_Init(&A);
MTX_randn( 1000, 1 ); // create a standard-normal distributed random vector of 1000 rows by 1 column.
\endcode
 
\return TRUE if successful, FALSE otherwise.
*/
BOOL MTX_randn( 
  MTX* M, 
  const unsigned nrows, 
  const unsigned ncols,   
  const unsigned seed 
  );

/** 
\brief Produce a matrix that is composed of pseudo-random numbers. 
Values are elements are uniform distribution [0,1].
 
\code 
MTX A;
MTX_Init(&A);
MTX_rand( 1000, 1 ); // create a uniformly distributed random vector of 1000 rows by 1 column.
\endcode
 
\return TRUE if successful, FALSE otherwise.
*/
BOOL MTX_rand( 
  MTX* M, 
  const unsigned nrows, 
  const unsigned ncols,   
  const unsigned seed 
  );


/// \brief  Test if a double value is NaN.
BOOL MTX_IsNAN( double value );

/// \brief  Test if a double value is +INF.
BOOL MTX_IsPostiveINF( double value );

/// \brief  Test if a double value is -INF.
BOOL MTX_IsNegativeINF( double value );


/// \brief  A quick plot, to a RLE compressed windows bitmap file, x_column vs y_column of the matrix M.
/// \return