matrix.h

矩阵类

    /**
    \brief  Computes the sqrt(value) of each element in the matrix.

    \code
    Matrix A;
    A = "[1 4; 9 16]";
    if( !A.Inplace_Sqrt() )
      return false;
    // A
    // 1 2
    // 3 4
    \endcode        
    
    \return true if successful, false otherwise.    
    */
    bool Inplace_Sqrt();

    /**
    \brief  Computes the exp(value) of each element in the matrix.

    \code
    Matrix A;
    A = "[1 2; 3 4]";
    if( !A.Inplace_Exp() )
      return false;
    // A ~
    //  2.71828  7.38905
    // 20.08553 54.59815
    \endcode        
    
    \return true if successful, false otherwise.    
    */
    bool Inplace_Exp();

    /**
    \brief  Computes the natural logarithm, ln(value) of each element in the matrix.

    \code
    Matrix A;
    A = "[2.71828  7.38905; 20.08553 54.59815]";    
    if( !A.Inplace_Ln() )
      return false;
    // A ~
    // 1 2
    // 3 4
    \endcode         
    
    \return true if successful, false otherwise.    
    */
    bool Inplace_Ln();

    /**
    \brief  Add +1.0 to all elements, e.g. M++.

    \code
    Matrix A;
    A = "[1 2; 3 4]";
    if( !A.Inplace_Increment() )
      return false;
    // A 
    // 2 3
    // 4 5
    \endcode        
    
    \return true if successful, false otherwise.   
    */
    bool Inplace_Increment();

    /**
    \brief  Subtract 1.0 from all elements, e.g. M--.

    \code
    Matrix A;
    A = "[1 2; 3 4]";
    if( !A.Inplace_Decrement() )
      return false;
    // A 
    // 0 1
    // 2 3
    \endcode            
    
    \return true if successful, false otherwise.    
    */
    bool Inplace_Decrement();

    /**
    \brief  Add matrix B to this matrix inplace. A += B, inplace.

    \code
    Matrix A;
    Matrix B;
    A = "[1 2; 3 4]";
    B = "[1 2; 3 4]";
    if( !A.Inplace_Add(B) )
      return false;
    // A 
    // 2 4
    // 6 8
    \endcode            
    
    \return true if successful, false otherwise.
    */
    bool Inplace_Add( const Matrix &B );

    /**
    \brief  Subtract matrix B from this matrix inplace. A -= B, inplace.

    \code
    Matrix A;
    Matrix B;
    A = "[1 2; 3 4]";
    B = "[1 2; 3 4]";
    if( !A.Inplace_Subtract(B) )
      return false;
    // A 
    // 0 0
    // 0 0
    \endcode            
    
    \return true if successful, false otherwise.
    */
    bool Inplace_Subtract( const Matrix &B );

    /**
    \brief  Pre-Multiply this matrix by B. A = B*A, inplace.

    \code
    Matrix A;
    Matrix B;
    A = "[1 2; 3 4]";
    B = "[1 2; 2 1]";
    if( !A.Inplace_PreMultiply(B) )
      return false;
    // A 
    // 7 10
    // 5 8
    \endcode  
    
    \return true if successful, false otherwise.
    */
    bool Inplace_PreMultiply( const Matrix &B );

    /**
    \brief  Post-Multiply this matrix by B. A = A*B, inplace.

    \code
    Matrix A;
    Matrix B;
    A = "[1 2; 3 4]";
    B = "[1 2; 2 1]";
    if( !A.Inplace_PostMultiply(B) )
      return false;
    // A 
    // 5 4
    // 11 10
    \endcode      
    
    \return true if successful, false otherwise.  
    */
    bool Inplace_PostMultiply( const Matrix &B );

    /**
    \brief  Dot multiply A .*= B, inplace. A and B must have the same dimensions.

    \code
    Matrix A;
    Matrix B;
    A = "[1 2; 3 4]";
    B = "[1 2; 2 1]";
    if( !A.Inplace_DotMultiply(B) )
      return false;
    // A 
    // 1 4
    // 6 4
    \endcode          
    
    \return true if successful, false otherwise.
    */
    bool Inplace_DotMultiply( const Matrix &B );

    /**
    \brief  Dot divide A ./= B, inplace. A and B must have the same dimensions.

    \code
    Matrix A;
    Matrix B;
    A = "[1 2; 3 4]";
    B = "[1 2; 2 1]";
    if( !A.Inplace_DotDivide(B) )
      return false;
    // A 
    // 1   1
    // 1.5 4
    \endcode          
    
    \return true if successful, false otherwise.
    */
    bool Inplace_DotDivide( const Matrix &B );

    /**
    \brief  Sorts each column of the matrix in ascending order.
            If complex, sorts based on magnitude.
    \code
    Matrix A;
    A = "[1;3;2;4;6;5;7]";
    if( !A.Inplace_SortAscending() )
      return false;
    // A
    // [1;2;3;4;5;6;7]
    \endcode
    
    \return true if successful, false otherwise.
    */
    bool Inplace_SortAscending();

    /**
    \brief  Sorts each column of M in descending order.
            If complex, sorts based on magnitude.
    \code
    Matrix A;
    A = "[1;3;2;4;6;5;7]";
    if( !A.Inplace_SortDescending() )
      return false;
    // A
    // [7;6;5;4;3;2;1]
    \endcode    
    
    \return true if successful, false otherwise.
    */
    bool Inplace_SortDescending();

    /**
    \brief  Sorts a specific column in ascending order.
            If complex, sorts based on magnitude.
    \code
    Matrix A;
    A = "[0 1;0 3;0 2;0 4;0 6;0 5;0 7]";
    if( !A.Inplace_SortColumnAscending(1) )
      return false;
    // A
    // A = "[0 1;0 2;0 3;0 4;0 5;0 6;0 7]";
    \endcode
       
    \return true if successful, false otherwise.
    */
    bool Inplace_SortColumnAscending( const unsigned col );

    /**
    \brief  Sorts a specific column in descending order.
            If complex, sorts based on magnitude.
    \code
    Matrix A;
    A = "[0 1;0 3;0 2;0 4;0 6;0 5;0 7]";
    if( !A.Inplace_SortColumnDescending(1) )
      return false;
    // A
    // A = "[0 7;0 6;0 5;0 4;0 3;0 2;0 1]";
    \endcode       
    
    \return true if successful, false otherwise.
    */
    bool Inplace_SortColumnDescending( const unsigned col );

    /**
    \brief  Sorts a specific column in ascending order and fills a  
            column vector with the sorted index. The index vector will be resized 
            if needed. If complex, sorts based on magnitude.
    \code
    Matrix A;
    Matrix I;
    A = "[0 1;0 3;0 2;0 4;0 6;0 5;0 7]";
    if( !A.Inplace_SortColumnIndexed(1, I) )
      return false;
    // A = "[0 1;0 2;0 3;0 4;0 5;0 6;0 7]";
    // I = "[0;2;1;3;5;4;6]"
    \endcode    
    
    \return true if successful, false otherwise.
    */
    bool Inplace_SortColumnIndexed( const unsigned col, Matrix &Index );

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

    \code
    Matrix A;
    Matrix I;
    A = "[0 1;2 3;1 2;3 4;5 6;4 5;6 7]";
    if( !A.Inplace_SortByColumn(0) )
      return false;
    // A = "[0 1;1 2;2 3;3 4;4 5;5 6;6 7]";
    \endcode 
    
    \return true if successful, false otherwise.
    */
    bool Inplace_SortByColumn( const unsigned col );

    /**
    \brief  Computes the inplace inverse of the matrix.
    
    Uses fast closed form solutions for:
    1x1, 2x2, 3x3
    
    Otherwise, 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.
    
    If the matrix is singular, the original matrix is unchanged.

    \code 
    Matrix A;
    A = "[10 14; 14 20]";
    if( !A.Inplace_Invert() )
      return false;
    // A
    //     5  -3.5
    //  -3.5   2.5
    \endcode
    
    \return true if successful, false if empty, singular or not square.
    */
    bool Inplace_Invert();

    /**
    \brief  Perfroms an inplace inverse using Gaussian Elimination methods.

    \code 
    Matrix A;
    A = "[1 2; 3 4]";
    if( !A.Inplace_InvertRobust() )
      return false;
    // A
    //   -2     1
    //  1.5  -0.5
    \endcode
    
    \return true if successful, false if empty, singular or not square.
    */
    bool Inplace_InvertRobust();

    /**
    \brief  Compute the inplace inverse of a unit lower triangular matrix. 
    
    \code
    Matrix A;
    // A
    //    1    0    0
    //   -2    2    0
    //    4   -3   -3    
    A = "[1 0 0; -2 2 0; 4 -3 -3]";
    if( !A.Inplace_LowerTriangularInverse() )
      return false;
    // A
    //    1    0    0
    //    1  1/2    0
    // -1/3  1/2  1/3
    \endcode
    
    \return true if successful, false if empty, singular or not square.
    */
    bool Inplace_LowerTriangularInverse();

    /**
    \brief  Compute the inplace Fourier Transform of each column of the matrix.

    \code
    Matrix A;
    A = "[0; 0; 0; 0; 1; 1; 1; 1;]"; 
    if( !A.Inplace_FFT() )
     return false;
    // A
    //  4                         
    // -1+2.41421356237309i
    //  0                         
    // -1+0.414213562373095i
    //  0                         
    // -1-0.414213562373095i
    //  0                         
    // -1-2.41421356237309i
    \endcode

    endcode

    \return   true if successful, false if unable to perform the FFT.
    */
    bool Inplace_FFT();

    /**
    \brief  Compute the inplace inverse Fourier Transform of each column of the matrix.

    \code
    Matrix A;
    A = "[4; -1+2.41421356237309i; 0; -1+0.414213562373095i; 0; -1-0.414213562373095i; 0; -1-2.41421356237309i;]"; 
    if( !A.Inplace_IFFT() )
     return false;
    // A
    // 0                         
    // 0
    // 0                         
    // 0
    // 1                         
    // 1
    // 1                         
    // 1
    \endcode

    \return   true if successful, false if unable to perform the FFT.
    */
    bool Inplace_IFFT();


  public: // Safe operations that set the matrix. Safe in that they return a boolean.

    /**
    \brief  Add A = B+C. The result, A, is stored in this matrix. 

    \code
    Matrix A;
    Matrix B;
    Matrix C;
    B = "[1 2; 3 4]";
    C = "[-1 2; -3 4]";
    if( !A.Add( B, C ) )
      return false;
    // A
    // 0 4
    // 0 8
    \endcode
    
    \return true if successful, false otherwise.
    */
    bool Add( const Matrix &B, const Matrix &C );

    /**
    \brief  Subtract A = B-C. The result, A, is stored in this matrix. 
    
    \code
    Matrix A;
    Matrix B;
    Matrix C;
    B = "[1 2; 3 4]";
    C = "[-1 2; -3 4]";
    if( !A.Subtract( B, C ) )
      return false;
    // A
    // 2 0
    // 6 0
    \endcode
    
    \return true if successful, false otherwise.
    */
    bool Subtract( const Matrix &B, const Matrix &C );

    /**
    \brief  Multiply A = B*C. The result, A, is stored in this matrix. 
    
    \code
    Matrix A;
    Matrix B;
    Matrix C;
    B = "[1 2; 3 4]";
    C = "[-1 2; -3 4]";
    if( !A.Multiply( B, C ) )
      return false;
    // A
    //  -7  10