cmatrix.h File Reference


Detailed Description

'c' functions for vector and matrix operations.

Author:
Glenn D. MacGougan (GDM)
Date:
2007-12-21
Version:
1.11
LICENSE INFORMATION
Copyright (c) 2007, Glenn D. MacGougan, Zenautics Technologies Inc.

Redistribution pertains only to the following files and their contents.

Redistribution and use in source and binary forms, with or without modification, of the specified files is permitted provided the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

NOTES:
This code was developed using rigourous unit testing for every function and operation. Despite any rigorous development process, bugs are inevitable. Please report bugs and suggested fixes to glenn@zenautics.com.

Definition in file cmatrix.h.

Go to the source code of this file.

Data Structures

struct  stComplex
 A complex data struct. More...
struct  MTX
 The deep level matrix struct. The matrix is either real or complex. More...

Functions

BOOL MTX_Initialize_MTXEngine ()
 This function must be called first by users of cmatrix!
BOOL MTX_Enable1x1MatricesForTreatmentAsScalars (BOOL enable)
 This function is used to set if matrices that are single elements (1x1) are treated as scalars for math operations or whether the regular matrix rules apply. THIS IS ENABLED BY DEFAULT.
BOOL MTX_isNull (const MTX *M)
 Is this a null matrix?
BOOL MTX_isConformalForMultiplication (const MTX *A, const MTX *B)
 Are matrices A & B conformal for multiplication, real * real.
BOOL MTX_isConformalForAddition (const MTX *A, const MTX *B)
 Are matrices A & B conformat for addition/subtraction, real + real.
BOOL MTX_isSquare (const MTX *A)
 Is this a square matrix?
BOOL MTX_isSameSize (const MTX *A, const MTX *B)
 are A and B the same size?
BOOL MTX_Init (MTX *M)
 Initialize a MTX matrix struct to appropriate zero values. This must always be called for proper operation!
BOOL MTX_SetComment (MTX *M, const char *comment)
 Set the matrix comment string.
BOOL MTX_Free (MTX *M)
 Clear the matrix data from memory if dynamically allocated. Zero the struct members.
BOOL MTX_Calloc (MTX *M, const unsigned nrows, const unsigned ncols, const BOOL isReal)
 Allocate matrix data (set to zero).
BOOL MTX_Malloc (MTX *M, const unsigned nrows, const unsigned ncols, const BOOL isReal)
 Allocate matrix data (not set to zero).
BOOL MTX_SetValue (MTX *M, const unsigned row, const unsigned col, const double value)
 Set a scalar value in the matrix.
BOOL MTX_SetComplexValue (MTX *M, const unsigned row, const unsigned col, const double re, const double im)
 Set a complex value in the matrix.
BOOL MTX_Complex (MTX *M, const MTX *Re, const MTX *Im)
 Matrix M = Re + Im*i, where Re and Im are real matrices.
BOOL MTX_SetComplexColumn (MTX *M, const unsigned col, const MTX *Re, const MTX *Im)
 Set the specified column in Matrix M to Re + Im*i, where Re and Im are real matrices. The dimensions of M must already be valid.
BOOL MTX_ConvertRealToComplex (MTX *M)
 Convert a real matrix to a complex matrix.
BOOL MTX_ConvertComplexToReal (MTX *M)
 Convert a complex marix to a real matrix using only the imaginary component A = real(B).
BOOL MTX_ConvertComplexToImag (MTX *M)
 Convert a complex marix to a real matrix using only the imaginary component A = imag(B).
BOOL MTX_Real (const MTX *M, MTX *Re)
 Extract the real component of matrix M.
BOOL MTX_isReal (MTX *M, BOOL *isReal)
 Check if the matrix contains only real values. Alter the matrix if it is stored as complex and only has real values.
BOOL MTX_RealColumn (const MTX *M, const unsigned col, MTX *Re)
 Extract the real component of column col of matrix M.
BOOL MTX_Imag (const MTX *M, MTX *Im)
 Extract the imaginary component of matrix M.
BOOL MTX_ImagColumn (const MTX *M, const unsigned col, MTX *Im)
 Extract the imaginary component of column col of matrix M.
BOOL MTX_Magnitude (const MTX *M, MTX *Magnitude)
 If M is a real matrix, Magnitude is a copy. If M is a complex matrix, Magnitude is a real matrix = sqrt( re*re + im*im ).
BOOL MTX_Phase (const MTX *M, MTX *Phase)
 If M is a real matrix, Phase is a zero matrix. If M is a complex matrix, Phase is a real matrix = atan2(im,re).
BOOL MTX_Conjugate (MTX *M)
 If M is a real matrix, nothing is done. If M is a complex matrix, the conjugate is set.
BOOL MTX_RemoveColumn (MTX *M, const unsigned col)
 Remove a single column from the matrix.
BOOL MTX_RemoveColumnsAfterIndex (MTX *dst, const unsigned col)
 remove all the columns 'after' the column index given.
BOOL MTX_InsertColumn (MTX *dst, const MTX *src, const unsigned dst_col, const unsigned src_col)
 insert a column into another matrix.
BOOL MTX_AddColumn (MTX *dst, const MTX *src, const unsigned src_col)
 Add a column to the Matrix.
BOOL MTX_Concatonate (MTX *dst, const MTX *src)
 Combine two matrices with the same nrows, A becomes A|B,.
BOOL MTX_Redim (MTX *dst, const unsigned nrows, const unsigned ncols)
 Redimension the matrix, original data is saved in place, new data is set to zero.
BOOL MTX_Resize (MTX *dst, const unsigned nrows, const unsigned ncols, const BOOL isReal)
 Resize the matrix, original data is lost, new data is set to zero, must specify if the matrix is real or complex.
BOOL MTX_Copy (const MTX *src, MTX *dst)
 Copy the src data to dst matrix, resize dst if possible & necessary.
BOOL MTX_CopyIntoColumnWiseVector (const MTX *src, MTX *dst)
 Copy the src matrix data [m cols x n rows] to dst vector [1 col x m*n rows], resize dst if possible & necessary.
BOOL MTX_SetFromStaticMatrix (MTX *dst, const double mat[], const unsigned nrows, const unsigned ncols)
 Set the dst matrix from the static 'c' style matrix indexed by mat[i*ncols + j].
BOOL MTX_CopyColumn (const MTX *src, const unsigned col, MTX *dst)
 Copy the src data in column col to dst matrix, resize dst if possible & necessary.
BOOL MTX_CopyRow (const MTX *src, const unsigned row, MTX *dst)
 Copy the src data in row, row, to dst matrix, resize dst if possible & necessary.
BOOL MTX_CopyRowIntoAColumnMatrix (const MTX *src, const unsigned row, MTX *dst)
 Copy the src data in row 'row' (1xn) to dst matrix (nx1), resize dst if possible & necessary. dst becomes (nx1).
BOOL MTX_InsertSubMatrix (MTX *dst, const MTX *src, const unsigned dst_row, const unsigned dst_col)
 Insert a submatrix (src) into dst, starting at indices dst(row,col).
BOOL MTX_Zero (MTX *dst)
 Zero the entire matrix.
BOOL MTX_ZeroColumn (MTX *dst, const unsigned col)
 Zero all elements in a specified column.
BOOL MTX_ZeroRow (MTX *dst, const unsigned row)
 Zero all elements in a specified row.
BOOL MTX_Fill (MTX *dst, const double value)
 Fill the matrix with the given value.
BOOL MTX_FillComplex (MTX *dst, const double re, const double im)
 Fill the matrix with the given complex value.
BOOL MTX_FillColumn (MTX *dst, const unsigned col, const double value)
 Fill the matrix column with the given value.
BOOL MTX_FillColumnComplex (MTX *dst, const unsigned col, const double re, const double im)
 Fill the matrix column with the given complex value.
BOOL MTX_FillRow (MTX *dst, const unsigned row, const double value)
 Fill the matrix row with the given value.
BOOL MTX_FillRowComplex (MTX *dst, const unsigned row, const double re, const double im)
 Fill the matrix row with the given complex value.
BOOL MTX_FlipColumn (MTX *M, const unsigned col)
 Reverse the order of elements of a column.
BOOL MTX_FlipRow (MTX *M, const unsigned row)
 Reverse the order of elements of a row.
BOOL MTX_Identity (MTX *dst)
 Set the matrix to an identity.
BOOL MTX_Transpose (const MTX *src, MTX *dst)
 Transpose the matrix src into the matris dst.
BOOL MTX_TransposeInplace (MTX *M)
 Transpose the matrix as an inplace operation.
BOOL MTX_Round (MTX *M, const unsigned precision)
 Round the matrix elements to the specified precision.
e.g. precision = 0 1.8 -> 2
e.g. precision = 1, 1.45 -> 1.5
e.g. precision = 2 1.456 -> 1.46
e.g. precision = 3, 1.4566 -> 1.457
precision has a maximum of 32. After which no rounding occurs.
BOOL MTX_Floor (MTX *M)
 Round the matrix elements to the nearest integers towards minus infinity.
BOOL MTX_Ceil (MTX *M)
 Round the matrix elements to the nearest integers towards infinity.
BOOL MTX_Fix (MTX *M)
 Round the matrix elements of X to the nearest integers towards zero.
BOOL MTX_DetermineFileDelimiter (const char *path, char *delimiter, BOOL *hasComment, char **comment)
 Determine the matrix file delimiter and if a comment line is available.
BOOL MTX_DetermineFileSize (const char *path, unsigned *size)
 Determine the size of a file.
BOOL MTX_DetermineNumberOfColumnsInDataString (const char *datastr, unsigned *ncols)
 Determine the number of columns in the data string provided.
BOOL MTX_DetermineNumberOfColumnsInDataStringCplx (const char *datastr, const char delimiter, unsigned *ncols)
 Determine the number of columns in the complex data string provided. The delimiter is needed, 'w' indicates whitespace.
BOOL MTX_ReadFromFileRealOnly (MTX *M, const char *path)
 Read a real-only matrix from a file (ASCII formatted, any common delimiters). This function will also read in MTX BINARY formatted files.
BOOL MTX_ReadFromFile (MTX *M, const char *path)
 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.
BOOL MTX_SetFromMatrixString (MTX *M, const char *strMatrix)
 Set the matrix from a matrix string.
BOOL MTX_ValueToString (const double value, const unsigned width, const unsigned precision, const BOOL isReal, const BOOL alignLeft, char *ValueBuffer, const unsigned ValueBufferSize)
 Convert a value to a string with the specified width and precision. analogous to sprintf( ValueBuffer, "%'blank''-'width.precision'g'", value );.
BOOL MTX_Print (const MTX *M, const char *path, const unsigned width, const unsigned precision, const BOOL append)
 Print the matrix to a file with specifed width and precision. MTX_PrintAutoWidth is recommended over this function, "%'blank''-'width.precision'g'".
BOOL MTX_Print_ToBuffer (const MTX *M, char *buffer, const unsigned maxlength, const unsigned width, const unsigned precision)
 Print the matrix to a buffer of maxlength with specifed width and precision. MTX_PrintAutoWidth is recommended over this function, "%'blank''-'width.precision'g'".
BOOL MTX_PrintAutoWidth (const MTX *M, const char *path, const unsigned precision, const BOOL append)
 Print the matrix to a file with automatically determined column width. and the specified precision, uses "%'blank''-'autowidth.precision'g'".
BOOL MTX_PrintStdoutAutoWidth (const MTX *M, const unsigned precision)
 Print the matrix to stdout with automatically determined column width. and the specified precision, uses "%'blank''-'autowidth.precision'g'".
BOOL MTX_PrintAutoWidth_ToBuffer (const MTX *M, char *buffer, const unsigned maxlength, const unsigned precision)
 Print the matrix to a buffer of maxlenth with automatically determined column width. and the specified precision, uses "%'blank''-'autowidth.precision'g'".
BOOL MTX_PrintDelimited (const MTX *M, const char *path, const unsigned precision, const char delimiter, const BOOL append)
 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'".
BOOL MTX_PrintDelimited_ToBuffer (const MTX *M, char *buffer, const unsigned maxlength, const unsigned precision, const char delimiter)
 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'".
BOOL MTX_PrintRowToString (const MTX *M, const unsigned row, char *buffer, const unsigned maxlength, const int width, const int precision)
 Print a row to a string buffer.
BOOL MTX_Add_Scalar (MTX *M, const double scalar)
 Adds a scalar double to matrix M, ie: M += 5.
BOOL MTX_Add_ScalarComplex (MTX *M, const double re, const double im)
 Adds a scalar complex to matrix M, ie: M += (5 + 3i).
BOOL MTX_Subtract_Scalar (MTX *M, const double scalar)
 Subtracts a scalar double from matrix M, ie: M -= 5.
BOOL MTX_Subtract_ScalarComplex (MTX *M, const double re, const double im)
 Subtracts a scaler complex from matrix M, ie: M -= (5+3i).
BOOL MTX_Multiply_Scalar (MTX *M, const double scalar)
 Multiply M with a double scalar inplace, ie: M *= 5.
BOOL MTX_Multiply_ScalarComplex (MTX *M, const double re, const double im)
 Multiply M with a complex scalar inplace, ie: M *= (5+3i).
BOOL MTX_Divide_Scalar (MTX *M, const double scalar)
 Divide M by scaler double inplace, ie: M /= 5.
BOOL MTX_Divide_ScalarComplex (MTX *M, const double re, const double im)
 Divide M by scaler complex inplace, ie: M /= (5+3i).
BOOL MTX_Abs (MTX *M)
 Computes the absolute value of each element in the matrix.
BOOL MTX_acos (MTX *M)
 Compute the arc-cosine of each element of the matrix inplace. Complex results are obtained if elements are greater than abs(1).
BOOL MTX_angle (MTX *M)
 Compute the phase angle in radians of the elements in the matrix. If all elements are real, the results are 0. If complex.
BOOL MTX_asin (MTX *M)
 Compute the arc-sine of each element of the matrix inplace. Complex results are obtained if elements are greater than abs(1).
BOOL MTX_Sqr (MTX *M)
 Computes the value^2 of each element in the matrix.
BOOL MTX_Sqrt (MTX *M)
 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.
BOOL MTX_Exp (MTX *M)
 If real, computes the exp(value) of each element in the matrix. If complex, computes exp(M) = exp(real)*(cos(imag)+i*sin(imag)).
BOOL MTX_Eye (MTX *M, const unsigned nrows, const unsigned ncols)
 Create an indentity matrix with nrows and ncols.
BOOL MTX_Ln (MTX *M)
 Computes the natural logarithm, ln(value) of each element in the matrix.
BOOL MTX_Pow (const MTX *src, MTX *dst, const double power_re, const double power_im)
 Raise all elements in src^(power_re + power_im*i) and store in dst. If power is just real, power_im = 0.0.
BOOL MTX_PowInplace (MTX *src, const double power_re, const double power_im)
 Raise all elements in src^(power_re + power_im*i). If power is just real, power_im = 0.0.
BOOL MTX_atan (MTX *M)
 Computes the arctan, atan(value) of each element in the matrix.
BOOL MTX_Increment (MTX *M)
 Add +1.0 to all elements, e.g. M++.
BOOL MTX_Decrement (MTX *M)
 Subtract 1.0 from all elements, e.g. M--.
BOOL MTX_Add_Inplace (MTX *A, const MTX *B)
 Add A += B, inplace.
BOOL MTX_Subtract_Inplace (MTX *A, const MTX *B)
 Subtract A -= B, inplace.
BOOL MTX_PreMultiply_Inplace (MTX *A, const MTX *B)
 Multiply A = B*A, inplace.
BOOL MTX_PostMultiply_Inplace (MTX *A, const MTX *B)
 Multiply A = A*B, inplace.
BOOL MTX_DotMultiply_Inplace (MTX *A, const MTX *B)
 Dot multiply A .*= B, inplace (A.data[col][row] = A.data[col][row]*B.data[col][row]).
BOOL MTX_DotDivide_Inplace (MTX *A, const MTX *B)
 Dot divide A ./= B, inplace (A.data[col][row] = A.data[col][row]/B.data[col][row]).
BOOL MTX_Add (MTX *A, const MTX *B, const MTX *C)
 Add A = B+C.
BOOL MTX_Subtract (MTX *A, const MTX *B, const MTX *C)
 Subtract A = B-C.
BOOL MTX_Multiply (MTX *A, const MTX *B, const MTX *C)
 Multiply A = B*C.
BOOL MTX_IsEqual (const MTX *A, const MTX *B, const double tolerance, BOOL *isEqual)
 Rest if A == B to within the specified tolerance.
BOOL MTX_ColumnDiff (const MTX *M, MTX *Diff, const unsigned col)
 Difference and approximte derivative for column col. The Diff is the column difference vector. diff = col[1:N-2] - col[0:N-1].
BOOL MTX_Diff (const MTX *M, MTX *Diff)
 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] }.
BOOL MTX_MaxColIndex (const MTX *M, const unsigned col, double *re, double *im, unsigned *row)
 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.
BOOL MTX_MaxRowIndex (const MTX *M, const unsigned row, double *re, double *im, unsigned *col)
 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.
BOOL MTX_MinColIndex (const MTX *M, const unsigned col, double *re, double *im, unsigned *row)
 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.
BOOL MTX_MinRowIndex (const MTX *M, const unsigned row, double *re, double *im, unsigned *col)
 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.
BOOL MTX_MaxAbsColIndex (const MTX *M, const unsigned col, double *value, unsigned *row)
 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.
BOOL MTX_MaxAbsRowIndex (const MTX *M, const unsigned row, double *value, unsigned *col)
 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.
BOOL MTX_MinAbsColIndex (const MTX *M, const unsigned col, double *value, unsigned *row)
 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.
BOOL MTX_MinAbsRowIndex (const MTX *M, const unsigned row, double *value, unsigned *col)
 Computes the absolute minimum element in the specified row and its index. If there are several equal minimum elements, the first index from the beginning is returned.
BOOL MTX_MaxColumn (const MTX *M, const unsigned col, double *re, double *im)
 Computes the maximum element in 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.
BOOL MTX_MaxRow (const MTX *M, const unsigned row, double *re, double *im)
 Computes the maximum element in 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.
BOOL MTX_MinColumn (const MTX *M, const unsigned col, double *re, double *im)
 Computes the minimum element in 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.
BOOL MTX_MinRow (const MTX *M, const unsigned row, double *re, double *im)
 Computes the minimum element in 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.
BOOL MTX_MaxAbsColumn (const MTX *M, const unsigned col, double *value)
 Computes the absolute maximum element in the specified column.
BOOL MTX_MaxAbsRow (const MTX *M, const unsigned row, double *value)
 Computes the absolute maximum element in the specified row.
BOOL MTX_MinAbsColumn (const MTX *M, const unsigned col, double *value)
 Computes the absolute minimum element in the specified column.
BOOL MTX_MinAbsRow (const MTX *M, const unsigned row, double *value)
 Computes the absolute minimum element in the specified row.
BOOL MTX_MaxAbsIndex (const MTX *M, double *value, unsigned *row, unsigned *col)
 Computes the absolute maximum element for the entire matrix and its row and column index. If there are several equal maximum elements, the first index from the beginning is returned.
BOOL MTX_MaxIndex (const MTX *M, double *re, double *im, unsigned *row, unsigned *col)
 Computes the maximum element for the entire matrix and its row and column index. If there are several equal maximum elements, the first index from the beginning is returned.
BOOL MTX_MaxAbs (const MTX *M, double *value)
 Computes the absolute maximum element for the entire matrix.
BOOL MTX_Max (const MTX *M, double *re, double *im)
 Computes the maximum element for the entire matrix.
BOOL MTX_MinAbsIndex (const MTX *M, double *value, unsigned *row, unsigned *col)
 Computes the absolute minimum element for the entire matrix and its row and column index. If there are several equal minimum elements, the first index from the beginning is returned.
BOOL MTX_MinIndex (const MTX *M, double *re, double *im, unsigned *row, unsigned *col)
 Computes the minimum element for the entire matrix and its row and column index. If there are several equal minimum elements, the first index from the beginning is returned.
BOOL MTX_MinAbs (const MTX *M, double *value)
 Computes the absolute minimum element for the entire matrix.
BOOL MTX_Min (const MTX *M, double *re, double *im)
 Computes the minimum element for the entire matrix.
BOOL MTX_ColumnRange (const MTX *M, const unsigned col, double *re, double *im)
 Computes the range of the data in the specified column. Range = MaxVal - MinVal. 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.
BOOL MTX_RowRange (const MTX *M, const unsigned row, double *re, double *im)
 Computes the range of the data in the specified row. Range = MaxVal - MinVal. 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.
BOOL MTX_Range (const MTX *M, double *re, double *im)
 Computes the range of the data in the matrix. Range = MaxVal - MinVal. 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.
BOOL MTX_ColumnSum (const MTX *M, const unsigned col, double *re, double *im)
 Computes the sum 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.
BOOL MTX_ColumnSumAbs (const MTX *M, const unsigned col, double *value)
 Computes the sum of the absolute values for the specified column.
BOOL MTX_RowSum (const MTX *M, const unsigned row, double *re, double *im)
 Computes the sum 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.
BOOL MTX_Sum (const MTX *M, double *re, double *im)
 Computes the sum of the data in 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.
BOOL MTX_ColumnMean (const MTX *M, const unsigned col, double *re, double *im)
 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.
BOOL MTX_RowMean (const MTX *M, const unsigned row, double *re, double *im)
 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.
BOOL MTX_Mean (const MTX *M, double *re, double *im)
 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.
BOOL MTX_ColumnStdev (const MTX *M, const unsigned col, double *value)
 Computes the sample standard deviation for the specified column.
BOOL MTX_RowStdev (const MTX *M, const unsigned row, double *value)
 Computes the sample standard deviation for the specified row.
BOOL MTX_Stdev (const MTX *M, double *value)
 Computes the sample standard deviation for the matrix.
BOOL MTX_ColumnVar (const MTX *M, const unsigned col, double *value)
 Computes the sample variance for the specified column.
BOOL MTX_RowVar (const MTX *M, const unsigned row, double *value)
 Computes the sample variance for the specified row.
BOOL MTX_Var (const MTX *M, double *value)
 Computes the sample variance for the matrix.
BOOL MTX_ColumnNorm (const MTX *M, const unsigned col, double *value)
 Computes the norm of the specified column. If real, norm = sqrt( sum( val*val ) ). If complex, norm = sqrt( sum( val*conjugate(val) ) ).
BOOL MTX_RowNorm (const MTX *M, const unsigned row, double *value)
 Computes the norm of the specified row. If real, norm = sqrt( sum( val*val ) ). If complex, norm = sqrt( sum( val*conjugate(val) ) ).
BOOL MTX_Norm (const MTX *M, double *value)
 Computes the norm of the matrix. If real, norm = sqrt( sum( val*val ) ). If complex, norm = sqrt( sum( val*conjugate(val) ) ).
BOOL MTX_ColumnRMS (const MTX *M, const unsigned col, double *value)
 Computes the sample RMS value for the specified column.
BOOL MTX_RowRMS (const MTX *M, const unsigned row, double *value)
 Computes the sample RMS value for the specified row.
BOOL MTX_RMS (const MTX *M, double *value)
 Computes the sample RMS value for the matrix.
BOOL MTX_ColumnSkewness (const MTX *M, const unsigned col, double *re, double *im)
 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.
BOOL MTX_RowSkewness (const MTX *M, const unsigned row, double *re, double *im)
 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.
BOOL MTX_Skewness (const MTX *M, double *re, double *im)
 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.
BOOL MTX_ColumnKurtosis (const MTX *M, const unsigned col, double *re, double *im)
 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).
BOOL MTX_RowKurtosis (const MTX *M, const unsigned row, double *re, double *im)
 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).
BOOL MTX_Kurtosis (const MTX *M, double *re, double *im)
 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).
BOOL MTX_Trace (const MTX *M, double *re, double *im)
 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.
BOOL MTX_Diagonal (const MTX *M, MTX *D)
 Sets the diagonal elements of M into D as a column vector.
BOOL MTX_SortAscending (MTX *M)
 Sorts each column of M in ascending order. If complex, sorts based on magnitude.
BOOL MTX_SortDescending (MTX *M)
 Sorts each column of M in descending order. If complex, sorts based on magnitude.
BOOL MTX_SortColumnAscending (MTX *M, const unsigned col)
 Sorts a specific column in ascending order. If complex, sorts based on magnitude.
BOOL MTX_SortColumnDescending (MTX *M, const unsigned col)
 Sorts a specific column in descending order. If complex, sorts based on magnitude.
BOOL MTX_SortColumnIndexed (MTX *M, const unsigned col, MTX *index)
 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.
BOOL MTX_SortByColumn (MTX *M, const unsigned col)
 Sorts the entire matrix by a specific column. If complex, sorts based on magnitude.
BOOL MTX_SaveCompressed (const MTX *M, const char *path)
 Saves a matrix to the specified file path using a proprietary compressed format. ADVANCED EDITION ONLY!
BOOL MTX_ReadCompressed (MTX *M, const char *path)
 Loads a binary compressed matrix that was saved using the MTX_SaveCompressed function.
BOOL MTX_GetCompressedFileAttributes (const char *path, unsigned *nrows, unsigned *ncols, BOOL *isReal)
 Get attributes of the compressed file.
BOOL MTX_LoadAndSave (const char *infilepath, const char *outfilepath)
 Read an ASCII matrix data file and save it using MTX_SaveCompressed. ADVANCED EDITION ONLY!
BOOL MTX_LoadAndSaveQuick (const char *infilepath)
 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!
BOOL MTX_TimeWindow (MTX *M, const unsigned timeColumn, const double startTime, const double duration, const double rolloverTime)
 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.
BOOL MTX_TimeLimit (MTX *M, const unsigned timeColumn, const double startTime, const double endTime)
 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.
BOOL MTX_TimeMatch (MTX *A, const unsigned timeColumnA, MTX *B, const unsigned timeColumnB, const unsigned precision, const double rolloverTime)
 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.
BOOL MTX_Interpolate (MTX *A, const unsigned timeColumnA, MTX *B, const unsigned timeColumnB, const double maxInterpolationInterval, const double rolloverTime)
 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.
BOOL MTX_Inv (MTX *src)
 Compute the inverse, 1.0/x, inplace for each element of the matrix.
BOOL MTX_InvertInPlaceClosedForm (MTX *M)
 Compute the inplace inverse of the matrix. Uses fast closed form solutions for: Only for: 1x1, 2x2, 3x3.
BOOL MTX_InvertInPlace (MTX *M)
 Compute the inplace inverse of a postive definite matrix.
BOOL MTX_InvertInPlaceRobust (MTX *M)
 Perfroms an inplace inverse using Gaussian Elimination methods.
BOOL MTX_ColumnMovAvg (const MTX *src, const unsigned col, const unsigned lead, const unsigned lag, MTX *dst)
 Computes a moving average using N lead samples and M lagging samples for the specified column and stores it in dst.
BOOL MTX_MovAvg (const MTX *src, const unsigned lead, const unsigned lag, MTX *dst)
 Computes a moving average using N lead samples and M lagging samples for the matrix and stores it in dst.
BOOL MTX_ATAInverse (const MTX *A, MTX *InvATA)
 Computes: InvATA = inverse( transpose(A) * A ).
BOOL MTX_LowerTriangularInverseInplace (MTX *src)
 Compute the inplace inverse of a unit lower triangular matrix. An example unit lower triangular matrix is:
A = [ 1 0 0;
-2 2 0;
4 -3 3 ]; with
inv(A) = [ 1 0 0;
1 1/2 0;
-1/3 1/2 1/3 ];
.
BOOL MTX_Det (const MTX *M, double *re, double *im)
 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.
BOOL MTX_LUFactorization (const MTX *src, BOOL *IsFullRank, MTX *P, MTX *L, MTX *U)
 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.
BOOL MTX_IndexedValues (const MTX *src, const MTX *row_index, const MTX *col_index, MTX *dst)
 Retrieve the elements of the matrix specified by the index vectors. The index vectors must be nx1 real vectors.
BOOL MTX_SetIndexedValues (MTX *dst, const MTX *row_index, const MTX *col_index, const MTX *src)
 Set the elements of the matrix specified by the index vectors. The index vectors must be nx1 real vectors.
BOOL MTX_FFT (const MTX *src, MTX *dst)
 Compute the Fast Fourier Transform of each columns in the src matrix and store it in the dst matrix.
BOOL MTX_IFFT (const MTX *src, MTX *dst)
 Compute the inverse Fast Fourier Transform of each columns in the src matrix and store it in the dst matrix.
BOOL MTX_FFT_Inplace (MTX *src)
 Compute the inplace Fast Fourier Transform of each column of the matrix.
BOOL MTX_IFFT_Inplace (MTX *src)
 Compute the inplace inverse Fast Fourier Transform of each column of the matrix.
BOOL MTX_sin (MTX *src)
 Compute the sine of each element in the matrix. Assumes elements are radians.
BOOL MTX_sinc (MTX *src)
 Compute the sin(pi*x)/(pi*) of each element in the matrix.
BOOL MTX_sinh (MTX *src)
 Compute the hyperbolic sine of each element in the matrix. Assumes elements are radians.
BOOL MTX_asinh (MTX *src)
 Compute the inverse hyperbolic sine of each element in the matrix. Results in radians.
BOOL MTX_cos (MTX *src)
 Compute the cosine of each element in the matrix. Assumes elements are radians.
BOOL MTX_cosh (MTX *src)
 Compute the hyperbolic cosine of each element in the matrix. Assumes elements are radians.
BOOL MTX_acosh (MTX *src)
 Compute the inverse hyperbolic cosine of each element in the matrix. Results in radians.
BOOL MTX_tan (MTX *src)
 Compute the tangent of each element in the matrix. Assumes elements are radians.
BOOL MTX_tanh (MTX *src)
 Compute the hyperbolic tangent of each element in the matrix. Assumes elements are radians.
BOOL MTX_atanh (MTX *src)
 Compute the inverse hyperbolic tangent of each element in the matrix. Results in radians.
BOOL MTX_cot (MTX *src)
 Compute the cotangent of each element in the matrix. Assumes elements are radians.
BOOL MTX_coth (MTX *src)
 Compute the hyperbolic cotangent of each element in the matrix. Assumes elements are radians.
BOOL MTX_Colon (MTX *dst, const double start, const double increment, const double end)
 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.
e.g. a = 2:2:9 = [2; 4; 6; 8;]
e.g. b = 2:-2:-9 = [2; 0; -2; -4; -6; -9;]
.
BOOL MTX_RemoveRowsAndColumns (MTX *src, const unsigned nrows, const unsigned rows[], const unsigned ncols, const unsigned cols[])
 A very efficient method to remove rows and columns from the matrix.
BOOL MTX_IsNAN (double value)
 Test if a double value is NaN.
BOOL MTX_IsPostiveINF (double value)
 Test if a double value is +INF.
BOOL MTX_IsNegativeINF (double value)
 Test if a double value is -INF.


Function Documentation

BOOL MTX_Abs ( MTX M  ) 

Computes the absolute value of each element in the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_acos ( MTX M  ) 

Compute the arc-cosine of each element of the matrix inplace. Complex results are obtained if elements are greater than abs(1).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_acosh ( MTX src  ) 

Compute the inverse hyperbolic cosine of each element in the matrix. Results in radians.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Add ( MTX A,
const MTX B,
const MTX C 
)

Add A = B+C.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Add_Inplace ( MTX A,
const MTX B 
)

Add A += B, inplace.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Add_Scalar ( MTX M,
const double  scalar 
)

Adds a scalar double to matrix M, ie: M += 5.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Add_ScalarComplex ( MTX M,
const double  re,
const double  im 
)

Adds a scalar complex to matrix M, ie: M += (5 + 3i).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_AddColumn ( MTX dst,
const MTX src,
const unsigned  src_col 
)

Add a column to the Matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_angle ( MTX M  ) 

Compute the phase angle in radians of the elements in the matrix. If all elements are real, the results are 0. If complex.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_asin ( MTX M  ) 

Compute the arc-sine of each element of the matrix inplace. Complex results are obtained if elements are greater than abs(1).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_asinh ( MTX src  ) 

Compute the inverse hyperbolic sine of each element in the matrix. Results in radians.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ATAInverse ( const MTX A,
MTX InvATA 
)

Computes: InvATA = inverse( transpose(A) * A ).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_atan ( MTX M  ) 

Computes the arctan, atan(value) of each element in the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_atanh ( MTX src  ) 

Compute the inverse hyperbolic tangent of each element in the matrix. Results in radians.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Calloc ( MTX M,
const unsigned  nrows,
const unsigned  ncols,
const BOOL  isReal 
)

Allocate matrix data (set to zero).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Ceil ( MTX M  ) 

Round the matrix elements to the nearest integers towards infinity.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Colon ( MTX dst,
const double  start,
const double  increment,
const double  end 
)

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.
e.g. a = 2:2:9 = [2; 4; 6; 8;]
e.g. b = 2:-2:-9 = [2; 0; -2; -4; -6; -9;]
.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ColumnDiff ( const MTX M,
MTX Diff,
const unsigned  col 
)

Difference and approximte derivative for column col. The Diff is the column difference vector. diff = col[1:N-2] - col[0:N-1].

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ColumnKurtosis ( const MTX M,
const unsigned  col,
double *  re,
double *  im 
)

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).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ColumnMean ( const MTX M,
const unsigned  col,
double *  re,
double *  im 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ColumnMovAvg ( const MTX src,
const unsigned  col,
const unsigned  lead,
const unsigned  lag,
MTX dst 
)

Computes a moving average using N lead samples and M lagging samples for the specified column and stores it in dst.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ColumnNorm ( const MTX M,
const unsigned  col,
double *  value 
)

Computes the norm of the specified column. If real, norm = sqrt( sum( val*val ) ). If complex, norm = sqrt( sum( val*conjugate(val) ) ).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ColumnRange ( const MTX M,
const unsigned  col,
double *  re,
double *  im 
)

Computes the range of the data in the specified column. Range = MaxVal - MinVal. 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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ColumnRMS ( const MTX M,
const unsigned  col,
double *  value 
)

Computes the sample RMS value for the specified column.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ColumnSkewness ( const MTX M,
const unsigned  col,
double *  re,
double *  im 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ColumnStdev ( const MTX M,
const unsigned  col,
double *  value 
)

Computes the sample standard deviation for the specified column.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ColumnSum ( const MTX M,
const unsigned  col,
double *  re,
double *  im 
)

Computes the sum 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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ColumnSumAbs ( const MTX M,
const unsigned  col,
double *  value 
)

Computes the sum of the absolute values for the specified column.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ColumnVar ( const MTX M,
const unsigned  col,
double *  value 
)

Computes the sample variance for the specified column.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Complex ( MTX M,
const MTX Re,
const MTX Im 
)

Matrix M = Re + Im*i, where Re and Im are real matrices.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Concatonate ( MTX dst,
const MTX src 
)

Combine two matrices with the same nrows, A becomes A|B,.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Conjugate ( MTX M  ) 

If M is a real matrix, nothing is done. If M is a complex matrix, the conjugate is set.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ConvertComplexToImag ( MTX M  ) 

Convert a complex marix to a real matrix using only the imaginary component A = imag(B).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ConvertComplexToReal ( MTX M  ) 

Convert a complex marix to a real matrix using only the imaginary component A = real(B).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ConvertRealToComplex ( MTX M  ) 

Convert a real matrix to a complex matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Copy ( const MTX src,
MTX dst 
)

Copy the src data to dst matrix, resize dst if possible & necessary.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_CopyColumn ( const MTX src,
const unsigned  col,
MTX dst 
)

Copy the src data in column col to dst matrix, resize dst if possible & necessary.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_CopyIntoColumnWiseVector ( const MTX src,
MTX dst 
)

Copy the src matrix data [m cols x n rows] to dst vector [1 col x m*n rows], resize dst if possible & necessary.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_CopyRow ( const MTX src,
const unsigned  row,
MTX dst 
)

Copy the src data in row, row, to dst matrix, resize dst if possible & necessary.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_CopyRowIntoAColumnMatrix ( const MTX src,
const unsigned  row,
MTX dst 
)

Copy the src data in row 'row' (1xn) to dst matrix (nx1), resize dst if possible & necessary. dst becomes (nx1).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_cos ( MTX src  ) 

Compute the cosine of each element in the matrix. Assumes elements are radians.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_cosh ( MTX src  ) 

Compute the hyperbolic cosine of each element in the matrix. Assumes elements are radians.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_cot ( MTX src  ) 

Compute the cotangent of each element in the matrix. Assumes elements are radians.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_coth ( MTX src  ) 

Compute the hyperbolic cotangent of each element in the matrix. Assumes elements are radians.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Decrement ( MTX M  ) 

Subtract 1.0 from all elements, e.g. M--.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Det ( const MTX M,
double *  re,
double *  im 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_DetermineFileDelimiter ( const char *  path,
char *  delimiter,
BOOL *  hasComment,
char **  comment 
)

Determine the matrix file delimiter and if a comment line is available.

Returns:
TRUE if successful, FALSE otherwise.
Parameters:
path  path to the input file
delimiter  delimiter, 'b' is binary
hasComment  BOOL to indicate if a comment line is present
comment  pointer to a string to store the comment line, *comment memory must be freed later.

BOOL MTX_DetermineFileSize ( const char *  path,
unsigned *  size 
)

Determine the size of a file.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_DetermineNumberOfColumnsInDataString ( const char *  datastr,
unsigned *  ncols 
)

Determine the number of columns in the data string provided.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_DetermineNumberOfColumnsInDataStringCplx ( const char *  datastr,
const char  delimiter,
unsigned *  ncols 
)

Determine the number of columns in the complex data string provided. The delimiter is needed, 'w' indicates whitespace.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Diagonal ( const MTX M,
MTX D 
)

Sets the diagonal elements of M into D as a column vector.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Diff ( const MTX M,
MTX Diff 
)

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] }.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Divide_Scalar ( MTX M,
const double  scalar 
)

Divide M by scaler double inplace, ie: M /= 5.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Divide_ScalarComplex ( MTX M,
const double  re,
const double  im 
)

Divide M by scaler complex inplace, ie: M /= (5+3i).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_DotDivide_Inplace ( MTX A,
const MTX B 
)

Dot divide A ./= B, inplace (A.data[col][row] = A.data[col][row]/B.data[col][row]).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_DotMultiply_Inplace ( MTX A,
const MTX B 
)

Dot multiply A .*= B, inplace (A.data[col][row] = A.data[col][row]*B.data[col][row]).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Enable1x1MatricesForTreatmentAsScalars ( BOOL  enable  ) 

This function is used to set if matrices that are single elements (1x1) are treated as scalars for math operations or whether the regular matrix rules apply. THIS IS ENABLED BY DEFAULT.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Exp ( MTX M  ) 

If real, computes the exp(value) of each element in the matrix. If complex, computes exp(M) = exp(real)*(cos(imag)+i*sin(imag)).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Eye ( MTX M,
const unsigned  nrows,
const unsigned  ncols 
)

Create an indentity matrix with nrows and ncols.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_FFT ( const MTX src,
MTX dst 
)

Compute the Fast Fourier Transform of each columns in the src matrix and store it in the dst matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_FFT_Inplace ( MTX src  ) 

Compute the inplace Fast Fourier Transform of each column of the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Fill ( MTX dst,
const double  value 
)

Fill the matrix with the given value.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_FillColumn ( MTX dst,
const unsigned  col,
const double  value 
)

Fill the matrix column with the given value.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_FillColumnComplex ( MTX dst,
const unsigned  col,
const double  re,
const double  im 
)

Fill the matrix column with the given complex value.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_FillComplex ( MTX dst,
const double  re,
const double  im 
)

Fill the matrix with the given complex value.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_FillRow ( MTX dst,
const unsigned  row,
const double  value 
)

Fill the matrix row with the given value.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_FillRowComplex ( MTX dst,
const unsigned  row,
const double  re,
const double  im 
)

Fill the matrix row with the given complex value.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Fix ( MTX M  ) 

Round the matrix elements of X to the nearest integers towards zero.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_FlipColumn ( MTX M,
const unsigned  col 
)

Reverse the order of elements of a column.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_FlipRow ( MTX M,
const unsigned  row 
)

Reverse the order of elements of a row.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Floor ( MTX M  ) 

Round the matrix elements to the nearest integers towards minus infinity.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Free ( MTX M  ) 

Clear the matrix data from memory if dynamically allocated. Zero the struct members.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_GetCompressedFileAttributes ( const char *  path,
unsigned *  nrows,
unsigned *  ncols,
BOOL *  isReal 
)

Get attributes of the compressed file.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Identity ( MTX dst  ) 

Set the matrix to an identity.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_IFFT ( const MTX src,
MTX dst 
)

Compute the inverse Fast Fourier Transform of each columns in the src matrix and store it in the dst matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_IFFT_Inplace ( MTX src  ) 

Compute the inplace inverse Fast Fourier Transform of each column of the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Imag ( const MTX M,
MTX Im 
)

Extract the imaginary component of matrix M.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ImagColumn ( const MTX M,
const unsigned  col,
MTX Im 
)

Extract the imaginary component of column col of matrix M.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Increment ( MTX M  ) 

Add +1.0 to all elements, e.g. M++.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_IndexedValues ( const MTX src,
const MTX row_index,
const MTX col_index,
MTX dst 
)

Retrieve the elements of the matrix specified by the index vectors. The index vectors must be nx1 real vectors.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Init ( MTX M  ) 

Initialize a MTX matrix struct to appropriate zero values. This must always be called for proper operation!

 MTX matrix;
 MTX_Init( &matrix );

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Initialize_MTXEngine (  ) 

This function must be called first by users of cmatrix!

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_InsertColumn ( MTX dst,
const MTX src,
const unsigned  dst_col,
const unsigned  src_col 
)

insert a column into another matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_InsertSubMatrix ( MTX dst,
const MTX src,
const unsigned  dst_row,
const unsigned  dst_col 
)

Insert a submatrix (src) into dst, starting at indices dst(row,col).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Interpolate ( MTX A,
const unsigned  timeColumnA,
MTX B,
const unsigned  timeColumnB,
const double  maxInterpolationInterval,
const double  rolloverTime 
)

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.

Returns:
TRUE if successful, FALSE otherwise.
Parameters:
A  The matrix with interpolation times
timeColumnA  The zero based column index for matrix A
B  The matrix to be interpolated
timeColumnB  The zero based column index for matrix B
maxInterpolationInterval  The largest interpolation interval allowed
rolloverTime  The rollover time, e.g. 60 s for minute based timing, 0.0 means rollovers not allowed

BOOL MTX_Inv ( MTX src  ) 

Compute the inverse, 1.0/x, inplace for each element of the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_InvertInPlace ( MTX M  ) 

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_InvertInPlaceClosedForm ( MTX M  ) 

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.

Returns:
TRUE if successful, FALSE if empty or has dimensions larger than 3x3, false if singular or not square

BOOL MTX_InvertInPlaceRobust ( MTX M  ) 

Perfroms an inplace inverse using Gaussian Elimination methods.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_isConformalForAddition ( const MTX A,
const MTX B 
)

Are matrices A & B conformat for addition/subtraction, real + real.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_isConformalForMultiplication ( const MTX A,
const MTX B 
)

Are matrices A & B conformal for multiplication, real * real.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_IsEqual ( const MTX A,
const MTX B,
const double  tolerance,
BOOL *  isEqual 
)

Rest if A == B to within the specified tolerance.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_IsNAN ( double  value  ) 

Test if a double value is NaN.

BOOL MTX_IsNegativeINF ( double  value  ) 

Test if a double value is -INF.

BOOL MTX_isNull ( const MTX M  ) 

Is this a null matrix?

Returns:
TRUE if the matrix is null, FALSE otherwise.

BOOL MTX_IsPostiveINF ( double  value  ) 

Test if a double value is +INF.

BOOL MTX_isReal ( MTX M,
BOOL *  isReal 
)

Check if the matrix contains only real values. Alter the matrix if it is stored as complex and only has real values.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_isSameSize ( const MTX A,
const MTX B 
)

are A and B the same size?

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_isSquare ( const MTX A  ) 

Is this a square matrix?

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Kurtosis ( const MTX M,
double *  re,
double *  im 
)

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).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Ln ( MTX M  ) 

Computes the natural logarithm, ln(value) of each element in the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_LoadAndSave ( const char *  infilepath,
const char *  outfilepath 
)

Read an ASCII matrix data file and save it using MTX_SaveCompressed. ADVANCED EDITION ONLY!

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_LoadAndSaveQuick ( const char *  infilepath  ) 

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!

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_LowerTriangularInverseInplace ( MTX src  ) 

Compute the inplace inverse of a unit lower triangular matrix. An example unit lower triangular matrix is:
A = [ 1 0 0;
-2 2 0;
4 -3 3 ]; with
inv(A) = [ 1 0 0;
1 1/2 0;
-1/3 1/2 1/3 ];
.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_LUFactorization ( const MTX src,
BOOL *  IsFullRank,
MTX P,
MTX L,
MTX U 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Magnitude ( const MTX M,
MTX Magnitude 
)

If M is a real matrix, Magnitude is a copy. If M is a complex matrix, Magnitude is a real matrix = sqrt( re*re + im*im ).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Malloc ( MTX M,
const unsigned  nrows,
const unsigned  ncols,
const BOOL  isReal 
)

Allocate matrix data (not set to zero).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Max ( const MTX M,
double *  re,
double *  im 
)

Computes the maximum element for the entire matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MaxAbs ( const MTX M,
double *  value 
)

Computes the absolute maximum element for the entire matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MaxAbsColIndex ( const MTX M,
const unsigned  col,
double *  value,
unsigned *  row 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MaxAbsColumn ( const MTX M,
const unsigned  col,
double *  value 
)

Computes the absolute maximum element in the specified column.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MaxAbsIndex ( const MTX M,
double *  value,
unsigned *  row,
unsigned *  col 
)

Computes the absolute maximum element for the entire matrix and its row and column index. If there are several equal maximum elements, the first index from the beginning is returned.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MaxAbsRow ( const MTX M,
const unsigned  row,
double *  value 
)

Computes the absolute maximum element in the specified row.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MaxAbsRowIndex ( const MTX M,
const unsigned  row,
double *  value,
unsigned *  col 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MaxColIndex ( const MTX M,
const unsigned  col,
double *  re,
double *  im,
unsigned *  row 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MaxColumn ( const MTX M,
const unsigned  col,
double *  re,
double *  im 
)

Computes the maximum element in 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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MaxIndex ( const MTX M,
double *  re,
double *  im,
unsigned *  row,
unsigned *  col 
)

Computes the maximum element for the entire matrix and its row and column index. If there are several equal maximum elements, the first index from the beginning is returned.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MaxRow ( const MTX M,
const unsigned  row,
double *  re,
double *  im 
)

Computes the maximum element in 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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MaxRowIndex ( const MTX M,
const unsigned  row,
double *  re,
double *  im,
unsigned *  col 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Mean ( const MTX M,
double *  re,
double *  im 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Min ( const MTX M,
double *  re,
double *  im 
)

Computes the minimum element for the entire matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MinAbs ( const MTX M,
double *  value 
)

Computes the absolute minimum element for the entire matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MinAbsColIndex ( const MTX M,
const unsigned  col,
double *  value,
unsigned *  row 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MinAbsColumn ( const MTX M,
const unsigned  col,
double *  value 
)

Computes the absolute minimum element in the specified column.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MinAbsIndex ( const MTX M,
double *  value,
unsigned *  row,
unsigned *  col 
)

Computes the absolute minimum element for the entire matrix and its row and column index. If there are several equal minimum elements, the first index from the beginning is returned.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MinAbsRow ( const MTX M,
const unsigned  row,
double *  value 
)

Computes the absolute minimum element in the specified row.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MinAbsRowIndex ( const MTX M,
const unsigned  row,
double *  value,
unsigned *  col 
)

Computes the absolute minimum element in the specified row and its index. If there are several equal minimum elements, the first index from the beginning is returned.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MinColIndex ( const MTX M,
const unsigned  col,
double *  re,
double *  im,
unsigned *  row 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MinColumn ( const MTX M,
const unsigned  col,
double *  re,
double *  im 
)

Computes the minimum element in 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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MinIndex ( const MTX M,
double *  re,
double *  im,
unsigned *  row,
unsigned *  col 
)

Computes the minimum element for the entire matrix and its row and column index. If there are several equal minimum elements, the first index from the beginning is returned.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MinRow ( const MTX M,
const unsigned  row,
double *  re,
double *  im 
)

Computes the minimum element in 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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MinRowIndex ( const MTX M,
const unsigned  row,
double *  re,
double *  im,
unsigned *  col 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_MovAvg ( const MTX src,
const unsigned  lead,
const unsigned  lag,
MTX dst 
)

Computes a moving average using N lead samples and M lagging samples for the matrix and stores it in dst.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Multiply ( MTX A,
const MTX B,
const MTX C 
)

Multiply A = B*C.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Multiply_Scalar ( MTX M,
const double  scalar 
)

Multiply M with a double scalar inplace, ie: M *= 5.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Multiply_ScalarComplex ( MTX M,
const double  re,
const double  im 
)

Multiply M with a complex scalar inplace, ie: M *= (5+3i).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Norm ( const MTX M,
double *  value 
)

Computes the norm of the matrix. If real, norm = sqrt( sum( val*val ) ). If complex, norm = sqrt( sum( val*conjugate(val) ) ).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Phase ( const MTX M,
MTX Phase 
)

If M is a real matrix, Phase is a zero matrix. If M is a complex matrix, Phase is a real matrix = atan2(im,re).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_PostMultiply_Inplace ( MTX A,
const MTX B 
)

Multiply A = A*B, inplace.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Pow ( const MTX src,
MTX dst,
const double  power_re,
const double  power_im 
)

Raise all elements in src^(power_re + power_im*i) and store in dst. If power is just real, power_im = 0.0.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_PowInplace ( MTX src,
const double  power_re,
const double  power_im 
)

Raise all elements in src^(power_re + power_im*i). If power is just real, power_im = 0.0.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_PreMultiply_Inplace ( MTX A,
const MTX B 
)

Multiply A = B*A, inplace.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Print ( const MTX M,
const char *  path,
const unsigned  width,
const unsigned  precision,
const BOOL  append 
)

Print the matrix to a file with specifed width and precision. MTX_PrintAutoWidth is recommended over this function, "%'blank''-'width.precision'g'".

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Print_ToBuffer ( const MTX M,
char *  buffer,
const unsigned  maxlength,
const unsigned  width,
const unsigned  precision 
)

Print the matrix to a buffer of maxlength with specifed width and precision. MTX_PrintAutoWidth is recommended over this function, "%'blank''-'width.precision'g'".

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_PrintAutoWidth ( const MTX M,
const char *  path,
const unsigned  precision,
const BOOL  append 
)

Print the matrix to a file with automatically determined column width. and the specified precision, uses "%'blank''-'autowidth.precision'g'".

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_PrintAutoWidth_ToBuffer ( const MTX M,
char *  buffer,
const unsigned  maxlength,
const unsigned  precision 
)

Print the matrix to a buffer of maxlenth with automatically determined column width. and the specified precision, uses "%'blank''-'autowidth.precision'g'".

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_PrintDelimited ( const MTX M,
const char *  path,
const unsigned  precision,
const char  delimiter,
const BOOL  append 
)

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'".

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_PrintDelimited_ToBuffer ( const MTX M,
char *  buffer,
const unsigned  maxlength,
const unsigned  precision,
const char  delimiter 
)

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'".

Returns:
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 
)

Print a row to a string buffer.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_PrintStdoutAutoWidth ( const MTX M,
const unsigned  precision 
)

Print the matrix to stdout with automatically determined column width. and the specified precision, uses "%'blank''-'autowidth.precision'g'".

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Range ( const MTX M,
double *  re,
double *  im 
)

Computes the range of the data in the matrix. Range = MaxVal - MinVal. 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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ReadCompressed ( MTX M,
const char *  path 
)

Loads a binary compressed matrix that was saved using the MTX_SaveCompressed function.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ReadFromFile ( MTX M,
const char *  path 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ReadFromFileRealOnly ( MTX M,
const char *  path 
)

Read a real-only matrix from a file (ASCII formatted, any common delimiters). This function will also read in MTX BINARY formatted files.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Real ( const MTX M,
MTX Re 
)

Extract the real component of matrix M.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RealColumn ( const MTX M,
const unsigned  col,
MTX Re 
)

Extract the real component of column col of matrix M.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Redim ( MTX dst,
const unsigned  nrows,
const unsigned  ncols 
)

Redimension the matrix, original data is saved in place, new data is set to zero.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RemoveColumn ( MTX M,
const unsigned  col 
)

Remove a single column from the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RemoveColumnsAfterIndex ( MTX dst,
const unsigned  col 
)

remove all the columns 'after' the column index given.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RemoveRowsAndColumns ( MTX src,
const unsigned  nrows,
const unsigned  rows[],
const unsigned  ncols,
const unsigned  cols[] 
)

A very efficient method to remove rows and columns from the matrix.

  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.

Returns:
TRUE if successful, FALSE otherwise.
Parameters:
src  The pointer to the matrix object.
nrows  The number of rows to remove (the length of the rows array).
rows  The array of row indices to remove.
ncols  The number of columns to remove (the length of hte cols array).

BOOL MTX_Resize ( MTX dst,
const unsigned  nrows,
const unsigned  ncols,
const BOOL  isReal 
)

Resize the matrix, original data is lost, new data is set to zero, must specify if the matrix is real or complex.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RMS ( const MTX M,
double *  value 
)

Computes the sample RMS value for the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Round ( MTX M,
const unsigned  precision 
)

Round the matrix elements to the specified precision.
e.g. precision = 0 1.8 -> 2
e.g. precision = 1, 1.45 -> 1.5
e.g. precision = 2 1.456 -> 1.46
e.g. precision = 3, 1.4566 -> 1.457
precision has a maximum of 32. After which no rounding occurs.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RowKurtosis ( const MTX M,
const unsigned  row,
double *  re,
double *  im 
)

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).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RowMean ( const MTX M,
const unsigned  row,
double *  re,
double *  im 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RowNorm ( const MTX M,
const unsigned  row,
double *  value 
)

Computes the norm of the specified row. If real, norm = sqrt( sum( val*val ) ). If complex, norm = sqrt( sum( val*conjugate(val) ) ).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RowRange ( const MTX M,
const unsigned  row,
double *  re,
double *  im 
)

Computes the range of the data in the specified row. Range = MaxVal - MinVal. 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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RowRMS ( const MTX M,
const unsigned  row,
double *  value 
)

Computes the sample RMS value for the specified row.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RowSkewness ( const MTX M,
const unsigned  row,
double *  re,
double *  im 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RowStdev ( const MTX M,
const unsigned  row,
double *  value 
)

Computes the sample standard deviation for the specified row.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RowSum ( const MTX M,
const unsigned  row,
double *  re,
double *  im 
)

Computes the sum 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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_RowVar ( const MTX M,
const unsigned  row,
double *  value 
)

Computes the sample variance for the specified row.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SaveCompressed ( const MTX M,
const char *  path 
)

Saves a matrix to the specified file path using a proprietary compressed format. ADVANCED EDITION ONLY!

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SetComment ( MTX M,
const char *  comment 
)

Set the matrix comment string.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SetComplexColumn ( MTX M,
const unsigned  col,
const MTX Re,
const MTX Im 
)

Set the specified column in Matrix M to Re + Im*i, where Re and Im are real matrices. The dimensions of M must already be valid.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SetComplexValue ( MTX M,
const unsigned  row,
const unsigned  col,
const double  re,
const double  im 
)

Set a complex value in the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SetFromMatrixString ( MTX M,
const char *  strMatrix 
)

Set the matrix from a matrix string.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SetFromStaticMatrix ( MTX dst,
const double  mat[],
const unsigned  nrows,
const unsigned  ncols 
)

Set the dst matrix from the static 'c' style matrix indexed by mat[i*ncols + j].

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SetIndexedValues ( MTX dst,
const MTX row_index,
const MTX col_index,
const MTX src 
)

Set the elements of the matrix specified by the index vectors. The index vectors must be nx1 real vectors.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SetValue ( MTX M,
const unsigned  row,
const unsigned  col,
const double  value 
)

Set a scalar value in the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_sin ( MTX src  ) 

Compute the sine of each element in the matrix. Assumes elements are radians.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_sinc ( MTX src  ) 

Compute the sin(pi*x)/(pi*) of each element in the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_sinh ( MTX src  ) 

Compute the hyperbolic sine of each element in the matrix. Assumes elements are radians.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Skewness ( const MTX M,
double *  re,
double *  im 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SortAscending ( MTX M  ) 

Sorts each column of M in ascending order. If complex, sorts based on magnitude.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SortByColumn ( MTX M,
const unsigned  col 
)

Sorts the entire matrix by a specific column. If complex, sorts based on magnitude.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SortColumnAscending ( MTX M,
const unsigned  col 
)

Sorts a specific column in ascending order. If complex, sorts based on magnitude.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SortColumnDescending ( MTX M,
const unsigned  col 
)

Sorts a specific column in descending order. If complex, sorts based on magnitude.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SortColumnIndexed ( MTX M,
const unsigned  col,
MTX index 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_SortDescending ( MTX M  ) 

Sorts each column of M in descending order. If complex, sorts based on magnitude.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Sqr ( MTX M  ) 

Computes the value^2 of each element in the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Sqrt ( MTX M  ) 

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Stdev ( const MTX M,
double *  value 
)

Computes the sample standard deviation for the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Subtract ( MTX A,
const MTX B,
const MTX C 
)

Subtract A = B-C.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Subtract_Inplace ( MTX A,
const MTX B 
)

Subtract A -= B, inplace.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Subtract_Scalar ( MTX M,
const double  scalar 
)

Subtracts a scalar double from matrix M, ie: M -= 5.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Subtract_ScalarComplex ( MTX M,
const double  re,
const double  im 
)

Subtracts a scaler complex from matrix M, ie: M -= (5+3i).

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Sum ( const MTX M,
double *  re,
double *  im 
)

Computes the sum of the data in 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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_tan ( MTX src  ) 

Compute the tangent of each element in the matrix. Assumes elements are radians.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_tanh ( MTX src  ) 

Compute the hyperbolic tangent of each element in the matrix. Assumes elements are radians.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_TimeLimit ( MTX M,
const unsigned  timeColumn,
const double  startTime,
const double  endTime 
)

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.

Returns:
TRUE if successful, FALSE otherwise. The duration to include
Parameters:
M  Matrix to be altered
timeColumn  The column containing time
startTime  The specified start time (inclusive)

BOOL MTX_TimeMatch ( MTX A,
const unsigned  timeColumnA,
MTX B,
const unsigned  timeColumnB,
const unsigned  precision,
const double  rolloverTime 
)

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
precision 1 = match to nearest 0.1
precision 2 = match to nearest 0.01
etc.
rolloverTime examples
GPS time of week (s): rolloverTime= 604800.0
hours : rolloverTime = 24.0
minutes : rolloverTime = 60.0

The time data must be non-decreasing but the time may rollover by the specified amount. e.g. rolloverTime = 60.0
0,1,2,3,4,...59,60,1,2,5,10,60,1,2,3...

Returns:
TRUE if successful, FALSE otherwise.
Parameters:
A  The matrix with interpolation times
timeColumnA  The zero based column index for matrix A
B  The matrix to be interpolated
timeColumnB  The zero based column index for matrix B
precision  The rounding precision used for time matching, 0 = whole, 1 = 0.1, 2 = 0.01, etc
rolloverTime  The rollover time, e.g. 60 s for minute based timing, 0.0 means rollovers not allowed

BOOL MTX_TimeWindow ( MTX M,
const unsigned  timeColumn,
const double  startTime,
const double  duration,
const double  rolloverTime 
)

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.

Returns:
TRUE if successful, FALSE otherwise. The potential time at which system time rolls over
Parameters:
M  Matrix to be altered
timeColumn  The column containing time
startTime  The specified start time (inclusive)
duration  The duration to include

BOOL MTX_Trace ( const MTX M,
double *  re,
double *  im 
)

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.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Transpose ( const MTX src,
MTX dst 
)

Transpose the matrix src into the matris dst.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_TransposeInplace ( MTX M  ) 

Transpose the matrix as an inplace operation.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ValueToString ( const double  value,
const unsigned  width,
const unsigned  precision,
const BOOL  isReal,
const BOOL  alignLeft,
char *  ValueBuffer,
const unsigned  ValueBufferSize 
)

Convert a value to a string with the specified width and precision. analogous to sprintf( ValueBuffer, "%'blank''-'width.precision'g'", value );.

Returns:
TRUE if successful, FALSE otherwise.
Parameters:
value  The double value to output.
width  The width of the field.
precision  The precision, g style.
isReal  The the value the real part or the imaginary part.
alignLeft  Align the output left (for real data only).
ValueBuffer  The output buffer.
ValueBufferSize  The size of the output buffer.

BOOL MTX_Var ( const MTX M,
double *  value 
)

Computes the sample variance for the matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_Zero ( MTX dst  ) 

Zero the entire matrix.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ZeroColumn ( MTX dst,
const unsigned  col 
)

Zero all elements in a specified column.

Returns:
TRUE if successful, FALSE otherwise.

BOOL MTX_ZeroRow ( MTX dst,
const unsigned  row 
)

Zero all elements in a specified row.

Returns:
TRUE if successful, FALSE otherwise.