cmatrix.h

大地测量专业计算软件

/// \brief  Computes the sample mean for the specified column.
/// 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_ColumnMean( const MTX *M, const unsigned col, double *re, double *im );

/// \brief  Computes the sample mean for the specified row.
/// 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_RowMean( const MTX *M, const unsigned row, double *re, double *im );

/// \brief  Computes the sample mean for the matrix.
/// 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_Mean( const MTX *M, double *re, double *im );




/// \brief  Computes the sample standard deviation for the specified column.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ColumnStdev( const MTX *M, const unsigned col, double *value );

/// \brief  Computes the sample standard deviation for the specified row.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_RowStdev( const MTX *M, const unsigned row, double *value );

/// \brief  Computes the sample standard deviation for the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Stdev( const MTX *M, double *value );



/// \brief  Computes the sample variance for the specified column.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ColumnVar( const MTX *M, const unsigned col, double *value );

/// \brief  Computes the sample variance for the specified row.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_RowVar( const MTX *M, const unsigned row, double *value );

/// \brief  Computes the sample variance for the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Var( const MTX *M, double *value );


/// \brief  Computes the norm of the specified column.
/// If real, norm = sqrt( sum( val*val ) ).
/// If complex, norm = sqrt( sum( val*conjugate(val) ) ).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ColumnNorm( const MTX *M, const unsigned col, double *value );

/// \brief  Computes the norm of the specified row.
/// If real, norm = sqrt( sum( val*val ) ).
/// If complex, norm = sqrt( sum( val*conjugate(val) ) ).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_RowNorm( const MTX *M, const unsigned row, double *value );

/// \brief  Computes the norm of the matrix.
/// If real, norm = sqrt( sum( val*val ) ).
/// If complex, norm = sqrt( sum( val*conjugate(val) ) ).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Norm( const MTX *M, double *value );


/// \brief  Computes the sample RMS value for the specified column.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ColumnRMS( const MTX *M, const unsigned col, double *value );

/// \brief  Computes the sample RMS value for the specified row.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_RowRMS( const MTX *M, const unsigned row, double *value );

/// \brief  Computes the sample RMS value for the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_RMS( const MTX *M, double *value );


/// \brief  Computes the sample skewness value for the specified column.
/// The skewness is the third central moment divided by the cube of the standard deviation.
/// 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_ColumnSkewness( const MTX *M, const unsigned col, double *re, double* im );

/// \brief  Computes the sample skewness value for the specified row.
/// The skewness is the third central moment divided by the cube of the standard deviation.
/// 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_RowSkewness( const MTX *M, const unsigned row, double *re, double* im );

/// \brief  Computes the sample skewness value for the matrix.
/// The skewness is the third central moment divided by the cube of the standard deviation.
/// 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_Skewness( const MTX *M, double *re, double* im );



/// \brief  Computes the sample kurtosis value for the specified column.
/// The kurtosis is the fourth central moment divided by fourth power of the standard deviation.
/// 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.
/// To adjust the computed kurtosis value for bias, subtract 3 from the real component.
/// Reference: http://en.wikipedia.org/wiki/Kurtosis.
/// Reference: http://mathworld.wolfram.com/Kurtosis.html (kurtosis proper is computed).
/// \return TRUE if successful, FALSE otherwise.
// g_2 = \frac{m_4}{m_{2}^2} = \frac{n\,\sum_{i=1}^n (x_i - \overline{x})^4}{\left(\sum_{i=1}^n (x_i - \overline{x})^2\right)^2}.
BOOL MTX_ColumnKurtosis( const MTX *M, const unsigned col, double *re, double *im );

/// \brief  Computes the sample kurtosis value for the specified row.
/// The kurtosis is the fourth central moment divided by fourth power of the standard deviation.
/// 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.
/// To adjust the computed kurtosis value for bias, subtract 3 from the real component.
/// Reference: http://en.wikipedia.org/wiki/Kurtosis.
/// Reference: http://mathworld.wolfram.com/Kurtosis.html (kurtosis proper is computed).
///
/// \return TRUE if successful, FALSE otherwise.
// g_2 = \frac{m_4}{m_{2}^2} = \frac{n\,\sum_{i=1}^n (x_i - \overline{x})^4}{\left(\sum_{i=1}^n (x_i - \overline{x})^2\right)^2}.
BOOL MTX_RowKurtosis( const MTX *M, const unsigned row, double *re, double *im );


/// \brief  Computes the sample kurtosis value for the matrix.
/// The kurtosis is the fourth central moment divided by fourth power of the standard deviation.
/// 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.
/// To adjust the computed kurtosis value for bias, subtract 3 from the real component.
/// Reference: http://en.wikipedia.org/wiki/Kurtosis.
/// Reference: http://mathworld.wolfram.com/Kurtosis.html (kurtosis proper is computed).
///
/// \return TRUE if successful, FALSE otherwise.
// g_2 = \frac{m_4}{m_{2}^2} = \frac{n\,\sum_{i=1}^n (x_i - \overline{x})^4}{\left(\sum_{i=1}^n (x_i - \overline{x})^2\right)^2}.
BOOL MTX_Kurtosis( const MTX *M, double *re, double *im );





////
// Matrix specific

/// \brief  Computes the trace of M where M is a square matrix.
/// Trace = Sum of diagonal elements.
/// 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_Trace( const MTX *M, double *re, double *im );

/// \brief  Sets the diagonal elements of M into D as a column vector
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Diagonal( const MTX *M, MTX *D );

/// \brief  Sorts each column of M in ascending order.
/// If complex, sorts based on magnitude.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_SortAscending( MTX *M );
                                                       
/// \brief  Sorts each column of M in descending order.
/// If complex, sorts based on magnitude.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_SortDescending( MTX *M );

/// \brief  Sorts a specific column in ascending order.
/// If complex, sorts based on magnitude.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_SortColumnAscending( MTX *M, const unsigned col );

/// \brief  Sorts a specific column in descending order.
/// If complex, sorts based on magnitude.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_SortColumnDescending( MTX *M, const unsigned col );

/// \brief  Sorts a specific column in ascending order and fills a MTX column vector with the sorted index.
/// The index vector will be resized if index->nrows != M->nrows
/// If complex, sorts based on magnitude.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_SortColumnIndexed( MTX *M, const unsigned col, MTX *index );

/// \brief  Sorts the entire matrix by a specific column.
/// If complex, sorts based on magnitude.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_SortByColumn( MTX *M, const unsigned col );



/// \brief  Saves a matrix to the specified file path using a proprietary compressed format.
/// ADVANCED EDITION ONLY!
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_SaveCompressed( const MTX *M, const char *path );


/// \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.
///