/*****************************************************************************
*                                                                            *
*   LOGM.SPL     Copyright (C) 2011 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Computes the matrix logarithm                               *
*                                                                            *
*   Revisions:   20 Apr 2011  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/

#if @HELP_LOGM

    LOGM

    Purpose: Computes the principal logarithm of a square matrix.

    Syntax:  LOGM(a)

              a - input matrix, must be square


    Returns: A square matrix.
               
    Example:
             W1: ravel({1,2,3,4}, 2) 
             W2: logm(w1)

             produces the following matrix in W2:

             {{-0.3504 + 2.3911i, 1.3940 - 1.6406i},
              { 0.9294 - 1.0938i, 1.0436 + 0.7505i}}
    Example:
             W1: ravel(1..9, 3)
             W2: logm(W1);
             W3: expm(W2)

             W1 == {{1, 4, 7},
                    {2, 5, 8},
                    {3, 6, 9}}

             W2 == 

             {{-5.4773 + 2.7896i,  12.4510 - 0.7970i,  -4.8315 - 1.2421i},
              {12.1412 - 0.4325i, -22.6050 + 2.1623i,  13.0706 - 1.5262i},
              {-5.4511 - 0.5129i,  12.7608 - 1.1616i,  -4.2382 + 1.33129i}}

             W3 == {{1, 4, 7},
                    {2, 5, 8},
                    {3, 6, 9}}

             demonstrating that EXPM and LOGM are inverse functions.

    Remarks:
             LOGM(A) computes a matrix X, the principal matrix logarithm of A,                   such that expm(X) == A. 

             The principal logarithm is undefined if the matrix is singular or                   has negative real eigenvalues.

    See Also:
             Expm
             Funm
             Sqrtm
#endif


/* matrix log */
logm(a)
{
        local f;

        f = funm(a, "log");

        return(f);
}