/**
\file     cmatrix.h
\brief    'c' functions for vector and matrix operations.
\author   Glenn D. MacGougan (GDM)
\date     2008-09-22
\version  0.06 Beta

\b Version \b Information \n
This is the open source version (BSD license). The Professional Version
is avaiable via http://www.zenautics.com. The Professional Version
is highly optimized using SIMD and includes optimization for multi-core 
processors.

\b License \b Information \n
Copyright (c) 2008, Glenn D. MacGougan, Zenautics Technologies Inc. \n

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

- Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer. \n
- Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution. \n
- The name(s) of the contributor(s) may not be used to endorse or promote 
  products derived from this software without specific prior written 
  permission. \n

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.

\b NOTES: \n
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.\n
*/

#ifndef ZENUATICS_MTX_H
#define ZENUATICS_MTX_H

#ifdef __cplusplus
extern "C" 
{
#endif

typedef int BOOL;

#ifndef FALSE
#define FALSE (0)
#endif
#ifndef TRUE
#define TRUE (1)
#endif

/// \brief  A complex data struct.
typedef struct 
{ 
  double re; //!< The real part.
  double im; //!< The imaginary part.
} stComplex;

/// \brief  The deep level matrix struct. The matrix is either real or complex.
typedef struct
{  
  unsigned   nrows;   //!< The number of rows in the matrix.
  unsigned   ncols;   //!< The number of columns in the matrix.
  BOOL       isReal;  //!< This indicates if is the matrix real or complex.
  double     **data;  //!< This is a pointer to an array of double column vectors.
  stComplex  **cplx;  //!< Thsi is a pointer to an array of complex column vectors.
  char      *comment; //!< This is a comment string (if applicable).
} MTX;


/// \brief  This function must be called first by users of cmatrix!
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Initialize_MTXEngine();


/// \brief  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.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Enable1x1MatricesForTreatmentAsScalars( BOOL enable );

/// \brief  Is this a null matrix?
///
/// \return TRUE if the matrix is null, FALSE otherwise.
BOOL MTX_isNull( const MTX *M );


/// \brief  Are matrices A & B conformal for multiplication, real * real
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_isConformalForMultiplication( const MTX *A, const MTX *B );

/// \brief  Are matrices A & B conformat for addition/subtraction, real + real
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_isConformalForAddition( const MTX *A, const MTX *B );

/// \brief  Is this a square matrix?
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_isSquare( const MTX *A );

/// \brief  are A and B the same size?
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_isSameSize( const MTX *A, const MTX *B );

/// \brief  Initialize a MTX matrix struct to appropriate zero values. This must always be called for proper operation!
/// \code
/// MTX matrix;
/// MTX_Init( &matrix );
/// \endcode
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Init( MTX *M );



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

/// \brief  Clear the matrix data from memory if dynamically allocated. Zero the struct members.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Free( MTX *M );

/// \brief  Allocate matrix data (set to zero).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Calloc( MTX *M, const unsigned nrows, const unsigned ncols, const BOOL isReal );

/// \brief  Allocate matrix data (not set to zero).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Malloc( MTX *M, const unsigned nrows, const unsigned ncols, const BOOL isReal );

/// \brief  Set a scalar value in the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_SetValue( MTX *M, const unsigned row, const unsigned col, const double value );

/// \brief  Set a complex value in the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_SetComplexValue( MTX *M, const unsigned row, const unsigned col, const double re, const double im );

/// \brief  Matrix M = Re + Im*i, where Re and Im are real matrices.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Complex( MTX *M, const MTX *Re, const MTX *Im );

/// \brief  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.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_SetComplexColumn( MTX *M, const unsigned col, const MTX *Re, const MTX *Im );

/// \brief  Convert a real matrix to a complex matrix
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ConvertRealToComplex( MTX *M );

/// \brief  Convert a complex marix to a real matrix using only the imaginary component A = real(B).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ConvertComplexToReal( MTX *M );

/// \brief  Convert a complex marix to a real matrix using only the imaginary component A = imag(B).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ConvertComplexToImag( MTX *M );

/// \brief  Extract the real component of matrix M.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Real( const MTX *M, MTX *Re );

/// \brief  Check if the matrix contains only real values. 
/// Alter the matrix if it is stored as complex and only has real values.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_isReal( MTX *M, BOOL *isReal );

/// \brief  Extract the real component of column col of matrix M.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_RealColumn( const MTX *M, const unsigned col, MTX *Re );

/// \brief  Extract the imaginary component of matrix M.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Imag( const MTX *M, MTX *Im );

/// \brief  Extract the imaginary component of column col of matrix M.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_ImagColumn( const MTX *M, const unsigned col, MTX *Im );

/// \brief  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 ).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Magnitude( const MTX *M, MTX *Magnitude );

/// \brief  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).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Phase( const MTX *M, MTX *Phase );

/// \brief  If M is a real matrix, nothing is done.
/// If M is a complex matrix, the conjugate is set.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Conjugate( MTX *M );

/// \brief  Remove a single column from the matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_RemoveColumn( MTX *M, const unsigned col );

/// \brief  remove all the columns 'after' the column index given.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_RemoveColumnsAfterIndex( MTX *dst, const unsigned col );

/// \brief  insert a column into another matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_InsertColumn( MTX *dst, const MTX *src, const unsigned dst_col, const unsigned src_col );

/// \brief  Add a column to the Matrix.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_AddColumn( MTX *dst, const MTX *src, const unsigned src_col );

/// \brief  Combine two matrices with the same nrows, A becomes A|B,
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Concatonate( MTX *dst, const MTX *src );

/// \brief  A becomes A|0|0|0|.. etc      
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_AddZeroValuedColumns( MTX *dst, const unsigned nr_new_cols );


/// \brief  Redimension the matrix, original data is saved in place, new data is set to zero.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Redim( MTX *dst, const unsigned nrows, const unsigned ncols );

/// \brief  Resize the matrix, original data is lost, new data is set to zero, must specify if the matrix is real or complex.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Resize( MTX *dst, const unsigned nrows, const unsigned ncols, const BOOL isReal );



/// \brief  Copy the src data to dst matrix, resize dst if possible & necessary.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_Copy( const MTX *src, MTX *dst );

/// \brief  Copy the src matrix data [m cols x n rows] to dst vector [1 col x m*n rows], resize dst if possible & necessary.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_CopyIntoColumnWiseVector( const MTX *src, MTX *dst );

/// \brief  Set the dst matrix from the static 'c' style matrix indexed by mat[i*ncols + j].
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_SetFromStaticMatrix( MTX *dst, const double mat[], const unsigned nrows, const unsigned ncols );

/// \brief  Copy the src data in column col to dst matrix, resize dst if possible & necessary.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_CopyColumn( const MTX *src, const unsigned col, MTX *dst );

/// \brief  Copy the src data in row, row, to dst matrix, resize dst if possible & necessary.
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_CopyRow( const MTX *src, const unsigned row, MTX *dst );

/// \brief  Copy the src data in row 'row' (1xn) to dst matrix (nx1), resize dst if possible & necessary.
/// dst becomes (nx1).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_CopyRowIntoAColumnMatrix( const MTX *src, const unsigned row, MTX *dst );

/// \brief  Insert a submatrix (src) into dst, starting at indices dst(row,col).
///
/// \return TRUE if successful, FALSE otherwise.
BOOL MTX_InsertSubMatrix( MTX *dst, const MTX *src, const unsigned dst_row, const unsigned dst_col );

/**
\brief  Extract a submatrix (dst) from this matrix from (inclusive) 
        the rows and columns specified.
\code 
MTX A;
MTX B;
BOOL result;
MTX_Init( &A );
MTX_Init( &B );

result = MTX_SetFromMatrixString( &A, "[1 2 3; 4 5 6; 7 8 9]" );
result = MTX_ExtractSubMatrix( &A, &B, 1, 0, 2, 2 );
// B == [4 5 6; 7 8 9]
\endcode

\return TRUE if successful, FALSE otherwise.
*/
BOOL MTX_ExtractSubMatrix( 
  const MTX* src,          //!< The source matrix.                        
  MTX* dst,                //!< The destination matrix to contain the submatrix.
  const unsigned from_row, //!< The zero-based index for the from row.
  const unsigned from_col, //!< The zero-based index for the from column.
  const unsigned to_row,   //!< The zero-based index for the to row.
  const unsigned to_col    //!< The zero-based index for the to column.
  );