matrix.h

大地测量专业计算软件

    \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 Two-Dimensional Fourier Transform of the matrix.
    FFT2 is equivalent to transpose( FFT( transpose( FFT(each column) ) ) )

    \code
    Matrix A;
    Matrix B;
    bool result;
    result = A.Inplace_colon(1.0,1.0,32.0);
    B = A*A.Transpose(); // (32x32 square matrix)
    result = B.Inplace_FFT2();
    \endcode

    endcode

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

    /**
    \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();


    /**
    \brief  Compute the inplace inverse Fourier Transform of the matrix.
    IFFT2 is equivalent to transpose( IFFT( transpose( IFFT(each column) ) ) )

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


  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
    // -15  22
    \endcode
    
    \return true if successful, false otherwise.
    */
    bool Multiply( const Matrix &B, const Matrix &C );


    /**
    \brief  Multiply A = transpose(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.TransposeMultiply( B, C ) )
      return false;
    // A
    // -10  14
    // -14  20
    \endcode
    
    \return true if successful, false otherwise.
    */
    bool TransposeMultiply( const Matrix &B, const Matrix &C );


    /**
    \brief  Multiply A = B*transpose(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.MultiplyTranspose( B, C ) )
      return false;
    // A
    // 3  5
    // 5  7
    \endcode
    
    \return true if successful, false otherwise.
    */
    bool MultiplyTranspose( const Matrix &B, const Matrix &C );
    

  public: // Matlab/Octave style functions

    /**
    \brief  Compute the absolute value of each element of the matrix inplace.
    
    \code
    Matrix A;
    A = "[-1 2 3]";
    if( !A.Inplace_abs() )
      return false;
    // A 
    // [1 2 3]
    \endcode

    \return true if successful, false otherwise.    
    */
    bool Inplace_abs();

    /**
    \brief  Compute the arc-cosine of each element of the matrix inplace.
            Complex results are obtained if elements are greater than abs(1).
            Results in radians.
    \code
    Matrix A;
    A = "[0 0.5 1]";
    if( !A.Inplace_acos() )
      return false;
    // A 
    // [pi/2 pi/3 0]
    \endcode
    
    \return true if successful, false otherwise.   
    */
    bool Inplace_acos();

    /**
    \brief  Compute the arc-cosine of each element of the matrix inplace.
            Complex results are obtained if elements are greater than abs(1).
            Results in degrees.
    \code
    Matrix A;
    A = "[0 0.5 1]";
    if( !A.Inplace_acosd() )
      return false;
    // A 
    // [90 60 0]
    \endcode    
    
    \return true if successful, false otherwise.    
    */
    bool Inplace_acosd();

    /**
    \brief  Compute the inverse hyperbolic cosine of each element of the matrix inplace.
            Results in radians.
    \code
    Matrix A;
    A = "[0  1.0471975511966 1.5707963267949]";
    if( !A.Inplace_acosh() )
      return false;
    // A 
    // [0 pi/3 pi/2]
    \endcode        
    
    \return true if successful, false otherwise.   
    */
    bool Inplace_acosh();

    /**
    \brief  Compute the phase angle in radians of the elements of the matrix.

    \code
    Matrix A;
    A = "[1+1i  1-1i 3+2i]";
    if( !A.Inplace_acosh() )
      return false;
    // A 
    // [pi/4 -pi/4 0.588002603547568]
    \endcode    
    
    \return true if successful, false otherwise.    
    */
    bool Inplace_angle();

    /**
    \brief  Compute the arc-sine of each element of the matrix inplace.
            Complex results are obtained if elements are greater than abs(1).
            Results in radians.
    \code
    Matrix A;
    A = "[0  0.5 1.0]";
    if( !A.Inplace_asin() )
      return false;
    // A 
    // [0 pi/6 pi/2]
    \endcode   
    
    \return true if successful, false otherwise.    
    */    
    bool Inplace_asin();

    /**
    \brief  Compute the arc-sine of each element of the matrix inplace.
            Complex results are obtained if elements are greater than abs(1).
            Results in degrees.
    \code
    Matrix A;
    A = "[0  0.5 1.0]";
    if( !A.Inplace_asind() )
      return false;
    // A 
    // [0 30 90]
    \endcode   
    
    \return true if successful, false other