cmatrix.h

矩阵类

/// e.g. precision = 1,   1.45   -> 1.5\n
/// e.g. precision = 2    1.456  -> 1.46\n
/// e.g. precision = 3,   1.4566 -> 1.457\n
/// precision has a maximum of 32. After which no rounding occurs.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Round( MTX *M, const unsigned precision );                             

/// \brief  Round the matrix elements to the nearest integers towards minus infinity.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Floor( MTX *M );

/// \brief  Round the matrix elements to the nearest integers towards infinity.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Ceil( MTX *M );

/// \brief  Round the matrix elements of X to the nearest integers towards zero.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Fix( MTX *M );


/// \brief  Determine the matrix file delimiter and if a comment line is available.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_DetermineFileDelimiter( 
  const char *path,    //!< path to the input file
  char *delimiter,     //!< delimiter, 'b' is binary
  BOOL *hasComment,    //!< BOOL to indicate if a comment line is present
  char **comment       //!< pointer to a string to store the comment line, *comment memory must be freed later.
  );

/// \brief  Determine the size of a file.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_DetermineFileSize( const char *path, unsigned *size );

/// \brief  Determine the number of columns in the data string provided.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_DetermineNumberOfColumnsInDataString( const char *datastr, unsigned *ncols );

/// \brief  Determine the number of columns in the complex data string provided. 
/// The delimiter is needed, 'w' indicates whitespace.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_DetermineNumberOfColumnsInDataStringCplx( const char *datastr, const char delimiter, unsigned *ncols );



/// \brief  Read a real-only matrix from a file (ASCII formatted, any common delimiters).
/// This function will also read in MTX BINARY formatted files.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ReadFromFileRealOnly( MTX *M, const char *path );


/// \brief  Read either a real or complex matrix from a file (ASCII formatted, any common delimiters).
/// This function will also read in MTX BINARY formatted files.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ReadFromFile( MTX *M, const char *path );


/// \brief  Set the matrix from a matrix string.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_SetFromMatrixString( MTX *M, const char *strMatrix );



/// \brief  Convert a value to a string with the specified width and precision.
/// analogous to sprintf( ValueBuffer, "%'blank''-'width.precision'g'", value );
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ValueToString( 
  const double value,             //!< The double value to output.
  const unsigned width,           //!< The width of the field.
  const unsigned precision,       //!< The precision, %g style.
  const BOOL isReal,              //!< The the value the real part or the imaginary part.
  const BOOL alignLeft,           //!< Align the output left (for real data only).
  char *ValueBuffer,              //!< The output buffer.
  const unsigned ValueBufferSize  //!< The size of the output buffer.
  );

/// \brief  Print the matrix to a file with specifed width and precision.
/// MTX_PrintAutoWidth is recommended over this function, "%'blank''-'width.precision'g'".
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Print( const MTX *M, const char *path, const unsigned width, const unsigned precision, const BOOL append );

/// \brief  Print the matrix to a buffer of maxlength with specifed width and precision.
/// MTX_PrintAutoWidth is recommended over this function, "%'blank''-'width.precision'g'".
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Print_ToBuffer( const MTX *M, char *buffer, const unsigned maxlength, const unsigned width, const unsigned precision );

/// \brief  Print the matrix to a file with automatically determined column width.
/// and the specified precision, uses "%'blank''-'autowidth.precision'g'".
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_PrintAutoWidth( const MTX *M, const char *path, const unsigned precision, const BOOL append );

/// \brief  Print the matrix to stdout with automatically determined column width.
/// and the specified precision, uses "%'blank''-'autowidth.precision'g'".
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_PrintStdoutAutoWidth( const MTX *M, const unsigned precision );

/// \brief  Print the matrix to a buffer of maxlenth with automatically determined column width.
/// and the specified precision, uses "%'blank''-'autowidth.precision'g'".
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_PrintAutoWidth_ToBuffer( const MTX *M, char *buffer, const unsigned maxlength, const unsigned precision );

/// \brief  Print the matrix to a file with specifed precision and delimiter.
/// Use MTX_PrintAutoWidth if print using whitespace as a delimiter is required, uses "%.precision'g'"
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_PrintDelimited( const MTX *M, const char *path, const unsigned precision, const char delimiter, const BOOL append );

/// \brief  Print the matrix to a file with specifed precision and delimiter.
/// Use MTX_PrintAutoWidth if print using whitespace as a delimiter is required, uses "%.precision'g'".
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_PrintDelimited_ToBuffer( const MTX *M, char *buffer, const unsigned maxlength, const unsigned precision, const char delimiter );

/// \brief  Print a row to a string buffer.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_PrintRowToString( const MTX *M, const unsigned row, char *buffer, const unsigned maxlength, const int width, const int precision );


////
// Math operations

/// \brief  Adds a scalar double to matrix M, ie: M += 5.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Add_Scalar( MTX *M, const double scalar );

/// \brief  Adds a scalar complex to matrix M, ie: M += (5 + 3i).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Add_ScalarComplex( MTX *M, const double re, const double im );

/// \brief  Subtracts a scalar double from matrix M, ie: M -= 5.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Subtract_Scalar( MTX *M, const double scalar );

/// \brief  Subtracts a scaler complex from matrix M, ie: M -= (5+3i).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Subtract_ScalarComplex( MTX *M, const double re, const double im );

/// \brief  Multiply M with a double scalar inplace, ie: M *= 5.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Multiply_Scalar( MTX *M, const double scalar );

/// \brief  Multiply M with a complex scalar inplace, ie: M *= (5+3i).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Multiply_ScalarComplex( MTX *M, const double re, const double im );

/// \brief  Divide M by scaler double inplace, ie: M /= 5.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Divide_Scalar( MTX *M, const double scalar );

/// \brief  Divide M by scaler complex inplace, ie: M /= (5+3i).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Divide_ScalarComplex( MTX *M, const double re, const double im );


/// \brief  Computes the absolute value of each element in the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Abs( MTX *M );

/// \brief  Compute the arc-cosine of each element of the matrix inplace.
///         Complex results are obtained if elements are greater than abs(1).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_acos( MTX *M );

/// \brief  Compute the phase angle in radians of the elements in the matrix.
/// If all elements are real, the results are 0. If complex
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_angle( MTX *M );

/// \brief  Compute the arc-sine of each element of the matrix inplace.
///         Complex results are obtained if elements are greater than abs(1).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_asin( MTX *M );


/// \brief  Computes the value^2 of each element in the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Sqr( MTX *M );

/// \brief  Computes the sqrt(value) of each element in the matrix.
/// A real matrix is converted to complex if any elements are negative.
/// e.g. sqrt(-1) = -i.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Sqrt( MTX *M );

/// \brief  If real, computes the exp(value) of each element in the matrix.
/// If complex, computes exp(M) = exp(real)*(cos(imag)+i*sin(imag)).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Exp( MTX *M );

/// \brief  Create an indentity matrix with nrows and ncols.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Eye( MTX *M, const unsigned nrows, const unsigned ncols );

/// \brief  Computes the natural logarithm, ln(value) of each element in the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Ln( MTX *M );

/// \brief  Raise all elements in src^(power_re + power_im*i) and store in dst.
/// If power is just real, power_im = 0.0.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Pow( const MTX *src, MTX *dst, const double power_re, const double power_im );

/// \brief  Raise all elements in src^(power_re + power_im*i).
/// If power is just real, power_im = 0.0.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_PowInplace( MTX *src, const double power_re, const double power_im );


/// \brief  Computes the arctan, atan(value) of each element in the matrix
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_atan( MTX *M );

/// \brief  Add +1.0 to all elements, e.g. M++.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Increment( MTX *M );

/// \brief  Subtract 1.0 from all elements, e.g. M--.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Decrement( MTX *M );

/// \brief  Add A += B, inplace.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Add_Inplace( MTX *A, const MTX *B );

/// \brief  Subtract A -= B, inplace.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Subtract_Inplace( MTX *A, const MTX *B );

/// \brief  Multiply A = B*A, inplace.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_PreMultiply_Inplace( MTX *A, const MTX *B ); // A = B*A

/// \brief  Multiply A = A*B, inplace.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_PostMultiply_Inplace( MTX *A, const MTX* B ); // A = A*B


/// \brief  Dot multiply A .*= B, inplace (A.data[col][row] = A.data[col][row]*B.data[col][row]).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_DotMultiply_Inplace( MTX *A, const MTX *B );

/// \brief  Dot divide A ./= B, inplace (A.data[col][row] = A.data[col][row]/B.data[col][row]).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_DotDivide_Inplace( MTX *A, const MTX *B );



/// \brief  Add A = B+C.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Add( MTX *A, const MTX *B, const MTX *C );

/// \brief  Subtract A = B-C.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Subtract( MTX *A, const MTX *B, const MTX *C );

/// \brief  Multiply A = B*C.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Multiply( MTX *A, const MTX *B, const MTX *C );

/// \brief  Rest if A == B to within the specified tolerance.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_IsEqual( const MTX *A, const MTX *B, const double tolerance, BOOL *isEqual );



/// \brief  Difference and approximte derivative for column col.
/// The Diff is the column difference vector.
/// diff = col[1:N-2] - col[0:N-1].
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ColumnDiff( const MTX *M, MTX *Diff, const unsigned col );

/// \brief  Difference and approximate derivative.
/// The Diff matrix is composed of the column difference vectors.
/// for(i=0:M-1){ diff_i = col_i[1:N-2] - col_i[0:N-1] }
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Diff( const MTX *M, MTX *Diff );


    
//// 
// Statistics

/// \brief  Computes the maximum element in the specified column and its index.
/// 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.
/// If there are several equal maximum elements, the first index from the beginning is returned.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_MaxColIndex( const MTX *M, const unsigned col, double *re, double *im, unsigned *row );

/// \brief  Computes the maximum element in the specified row and its index.
/// 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.
/// If there are several equal maximum elements, the first index from the beginning is returned.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_MaxRowIndex( const MTX *M, const unsigned row, double *re, double *im, unsigned *col );


/// \brief  Computes the minimum element in the specified column and its index.
/// 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.
/// If there are several equal minimum elements, the first index from the beginning is returned.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_MinColIndex( const MTX *M, const unsigned col, double *re, double *im, unsigned *row );  

/// \brief  Computes the minimum element in the specified row and its index.
/// 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.
/// If there are several equal minimum elements, the first index from the beginning is returned.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_MinRowIndex( const MTX *M, const unsigned row, double *re, double *im, unsigned *col );


/// \brief  Computes the absolute maximum element in the specified column and its index.
/// If there are several equal maximum elements, the first index from the beginning is returned.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_MaxAbsColIndex( const MTX *M, const unsigned col, double *value, unsigned *row );  

/// \brief  Computes the absolue maximum element in the specified row and a its column index.
/// If there are several equal maximum elements, the first index from the beginning is returned.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_MaxAbsRowIndex( const MTX *M, const unsigned row, double *value, unsigned *col );

/// \brief  Computes the absolute minimum element in the specified column and its index.
/// If there are several equal minimum elements, the first index from the beginning is returned.
///
/// \return TRUE if successful, FALSE otherwise.