cmatrix.h

矩阵类

/// \brief  Loads a binary compressed matrix that was saved using the MTX_SaveCompressed function.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ReadCompressed( MTX *M, const char *path );

/// \brief  Get attributes of the compressed file.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_GetCompressedFileAttributes( 
  const char *path,
  unsigned* nrows,
  unsigned* ncols,
  BOOL* isReal 
  );


/// \brief  Read an ASCII matrix data file and save it using MTX_SaveCompressed.
/// ADVANCED EDITION ONLY!
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_LoadAndSave( const char* infilepath, const char* outfilepath );

/// \brief  Read an ASCII matrix data file and save it using MTX_SaveCompressed.
/// This version saves the data to the same base filename and uses the .mtx extension.
/// ADVANCED EDITION ONLY!
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_LoadAndSaveQuick( const char* infilepath );


/// \brief  Alter the matrix, M, so that its data is within the startTime to the startTime+duration
/// and compensate for any rollovers in the time system (e.g. GPS time in seconds rolls over
/// at 604800.0 s). This function assumes that time is one of the matrix columns and requires
/// this index, the timeColumn.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_TimeWindow( 
  MTX* M,                     //!< Matrix to be altered
  const unsigned timeColumn,   //!< The column containing time
  const double startTime,      //!< The specified start time (inclusive)
  const double duration,       //!< The duration to include
  const double rolloverTime ); //!< The potential time at which system time rolls over

/// \brief  Alter the matrix, M, so that its data is within [startTime endTime].
/// This function assumes that time is one of the matrix columns and requires
/// this index, the timeColumn.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_TimeLimit( 
  MTX* M,                     //!< Matrix to be altered
  const unsigned timeColumn,   //!< The column containing time
  const double startTime,      //!< The specified start time (inclusive)
  const double endTime );      //!< The duration to include
  

/// \brief  This function matches matrices in time with specified precision
/// where time is a column of each matrix. This function also
/// allows time to rollover at a specified interval.
///
///    precision 0 = match to whole number \n
///    precision 1 = match to nearest 0.1 \n
///    precision 2 = match to nearest 0.01 \n
///    etc. \n
/// rolloverTime examples \n
///     GPS time of week (s): rolloverTime= 604800.0 \n
///     hours               : rolloverTime = 24.0 \n
///     minutes             : rolloverTime = 60.0 \n
///
/// The time data must be non-decreasing but the time may rollover
/// by the specified amount. 
/// e.g. rolloverTime = 60.0 \n
///      0,1,2,3,4,...59,60,1,2,5,10,60,1,2,3... \n
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_TimeMatch( 
  MTX *A,                      //!< The matrix with interpolation times
  const unsigned timeColumnA,  //!< The zero based column index for matrix A
  MTX *B,                      //!< The matrix to be interpolated
  const unsigned timeColumnB,  //!< The zero based column index for matrix B
  const unsigned precision,    //!< The rounding precision used for time matching, 0 = whole, 1 = 0.1, 2 = 0.01, etc
  const double rolloverTime    //!< The rollover time, e.g. 60 s for minute based timing, 0.0 means rollovers not allowed
  );



/// \brief  This function interpolates Matrix B values by the times defined 
/// in the column in Matrix A. Time must be increasing but times can 
/// rollover with the specified rolloverTime.
///
/// This function returns A and B with the same number of rows and 
/// time aligned time columns.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Interpolate( 
  MTX *A,                     //!< The matrix with interpolation times
  const unsigned timeColumnA, //!< The zero based column index for matrix A
  MTX *B,                     //!< The matrix to be interpolated
  const unsigned timeColumnB, //!< The zero based column index for matrix B
  const double maxInterpolationInterval, //!< The largest interpolation interval allowed
  const double rolloverTime   //!< The rollover time, e.g. 60 s for minute based timing, 0.0 means rollovers not allowed
  );


/// \brief  Compute the inverse, 1.0/x, inplace for each element
///         of the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Inv( MTX *src );


/// \brief  Compute the inplace inverse of the matrix.
///         Uses fast closed form solutions for:
///         Only for: 1x1, 2x2, 3x3
///
/// If the matrix is singular, the original matrix is unchanged.
///
/// \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 a postive definite 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  Perfroms an inplace 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 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 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[]
  );


  #ifdef ___MTX_RANDN_READY
/** \brief Produce a matrix that is composed of pseudo-random numbers. 
 *  The seed state is based on the system clock or alternatively by the seed
 *  parameter, a positive integer can set the seed state upon generation. 
 *  Elements are chosen from a normal distribution with mean zero, variance of 
 *  one and standard of deviation one.
 *
 * \code 
 *  MTX A;
 *  MTX_Init(&A);
 *  MTX_randn( 1000, 1 ); // create a 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 BOOL useSeed, 
  const unsigned seed 
  );
#endif


#ifdef __cplusplus
}
#endif


#endif // ZENUATICS_MTX_H