### 18.4 Functions of a Matrix ¶

`r =` expm `(A)` ¶

  Return the exponential of a matrix.

  The matrix exponential is defined as the infinite Taylor series

      expm (A) = I + A + A^2/2! + A^3/3! + ...

  However, the Taylor series is not the way to compute the matrix exponential; see Moler and Van Loan, "Nineteen Dubious Ways to Compute the Exponential of a Matrix", SIAM Review, 1978. This routine uses Ward’s diagonal Padé approximation method with three step preconditioning (SIAM Journal on Numerical Analysis, 1977). Diagonal Padé approximations are rational polynomials of matrices

           -1
      D (A)   N (A)

  whose Taylor series matches the first `2q+1` terms of the Taylor series above; direct evaluation of the Taylor series (with the same preconditioning steps) may be desirable in lieu of the Padé approximation when `Dq(A)` is ill-conditioned.

  See also: logm, sqrtm.

`s =` logm `(A)` ¶
`s =` logm `(A, opt_iters)` ¶
`[s, iters] =` logm `(…)` ¶

  Compute the matrix logarithm of the square matrix A.

  The implementation utilizes a Padé approximant and the identity

      logm (A) = 2^k * logm (A^(1 / 2^k))

  The optional input opt_iters is the maximum number of square roots to compute and defaults to 100.

  The optional output iters is the number of square roots actually computed.

  See also: expm, sqrtm.

`s =` sqrtm `(A)` ¶
`[s, error_estimate] =` sqrtm `(A)` ¶

  Compute the matrix square root of the square matrix A.

  Ref: N.J. Higham, A New sqrtm for MATLAB, Numerical Analysis Report No. 336, Manchester Centre for Computational Mathematics, Manchester, England, January 1999.

  See also: expm, logm.

`F =` funm `(A, fun)` ¶
`F =` funm `(A, fun, options)` ¶
`F =` funm `(A, fun, options, p1, …)` ¶
`[F, exitflag] =` funm `(…)` ¶
`[F, exitflag, output] =` funm `(…)` ¶

  Evaluate a general matrix function.

  `funm (A, fun)` evaluates the function fun at the square matrix A. The input `fun (x, k)` must return the k’th derivative of the function represented by fun evaluated at the vector x. The function fun must have a Taylor series representation with an infinite radius of convergence.

  The special functions `exp`, `log`, `sin`, `cos`, `sinh`, and `cosh` can be passed by function handle; for example `funm (A, @cos)`.

  For matrix square roots, use `sqrtm` instead. For matrix exponentials, either `expm` or `funm (A, @exp)` may be faster or more accurate, depending on A.

  An optional third input in the form of an options struct options can be used to specify verbosity of the function and to influence certain of the algorithms. See the references below for more details on the latter.

  options can have the following fields:

  `Display`

    Specify what information will be printed to the screen during the course of calculations. It can be either a string value of `"off"` (no info, the default), `"on"` (some info), `"verbose"` (maximum info); or a scalar value between `0` (no info, the default) and `5` (maximum info). When `Display` is `"verbose"` or a scalar value ≥ `3`, a plot of the eigenvalues and groups will also be shown.

  `TolBlk`

    Tolerance used in determining the blocking (positive scalar, default: `0.1`).

  `TolTay`

    Tolerance used in the convergence test for evaluating the Taylor series (positive scalar, default: `eps`).

  `MaxTerms`

    The maximum number of Taylor series terms (positive integer, default: `250`).

  `MaxSqrt`

    The maximum number of square roots evaluated in the course of inverse scaling and squaring (positive integer, default: `100`). This option is only used when computing a logarithm where it functions similarly to `MaxTerms`.

  `Ord`

    Define a custom blocking pattern in the form of a vector whose length equals the order of the matrix A.

  Octave accepts any case for these fieldnames.

  All inputs beyond options will be passed as positional arguments to the function fun.

  Optional outputs:

  exitflag

    Scalar exit flag that describes the exit condition:

    - `0` — The algorithm was successful.
    - `1` — One or more Taylor series evaluations did not converge, but the computed value of F might still be accurate.
  output

    Structure with the following fields:

    `terms`

      Vector for which `output.terms(i)` is the number of Taylor series terms used when evaluating the i’th block, or, in the case of the logarithm, the number of square roots of matrices of dimension greater than 2.

    `ind`

      Cell array for which the (i,j) block of the reordered Schur factor T is `T(output.ind{i}, output.ind{j})`.

    `ord`

      Ordering of the Schur form, as passed to `ordschur`.

    `T`

      Reordered Schur form.

    If the Schur form is diagonal then `output = struct ("terms", ones (n, 1), "ind", {1:n}, "ord", [], "T", T)`.

  Example:

      F = funm (magic (3), @sin);
      ⇒ F =
         -0.3850    1.0191    0.0162
          0.6179    0.2168   -0.1844
          0.4173   -0.5856    0.8185

  The code

      S = funm (X, @sin);
      C = funm (X, @cos);

  will produce the same results (within possible rounding error) as

      E = expm (i*X);
      C = real (E);
      S = imag (E);

  References:

  Philip I. Davies and Nicholas J. Higham, "A Schur-Parlett algorithm for computing matrix functions", SIAM Journal on Matrix Analysis and Applications, Vol. 25(2), pp. 464–485, 2003.

  Nicholas J. Higham, Functions of Matrices: Theory and Computation, SIAM, pp. 425, 2008, ISBN 978-0-898716-46-7.

  See also: expm, logm, sqrtm.

`C =` kron `(A, B)` ¶
`C =` kron `(A1, A2, …)` ¶

  Form the Kronecker product of two or more matrices.

  This is defined block by block as

      c = [ a(i,j)*b ]

  For example:

      kron (1:4, ones (3, 1))
           ⇒   1  2  3  4
               1  2  3  4
               1  2  3  4

  If there are more than two input arguments A1, A2, …, An the Kronecker product is computed as

      kron (kron (A1, A2), ..., An)

  Since the Kronecker product is associative, this is well-defined.

  See also: tensorprod.

`C =` tensorprod `(A, B, dimA, dimB)` ¶
`C =` tensorprod `(A, B, dim)` ¶
`C =` tensorprod `(A, B)` ¶
`C =` tensorprod `(A, B, "all")` ¶
`C =` tensorprod `(A, B, …, "NumDimensionsA", value)` ¶

  Compute the tensor product between numeric tensors A and B.

  The dimensions of A and B that are contracted are defined by dimA and dimB, respectively. dimA and dimB are scalars or equal length vectors that define the dimensions to match up. The matched dimensions of A and B must have the same number of elements.

  When only dim is used, it is equivalent to `dimA = dimB = dim`.

  When no dimensions are specified, `dimA = dimB = []`. This computes the outer product between A and B.

  Using the `"all"` option results in the inner product between A and B. This requires `size (A) == size (B)`.

  Use the property-value pair with the property name `"NumDimensionsA"` when A has trailing singleton dimensions that should be transferred to C. The specified value should be the total number of dimensions of A.

  MATLAB Compatibility: Octave does not currently support the `"property_name=value"` syntax for the `"NumDimensionsA"` parameter.

  See also: kron, dot, mtimes.

`C =` blkmm `(A, B)` ¶

  Compute products of matrix blocks.

  The blocks are given as 2-dimensional subarrays of the arrays A, B. The size of A must have the form `[m,k,…]` and size of B must be `[k,n,…]`. The result is then of size `[m,n,…]` and is computed as follows:

      for i = 1:prod (size (A)(3:end))
        C(:,:,i) = A(:,:,i) * B(:,:,i)
      endfor

`X =` sylvester `(A, B, C)` ¶

  Solve the Sylvester equation.

  The Sylvester equation is defined as:

      A X + X B = C

  The solution is computed using standard LAPACK subroutines.

  For example:

      sylvester ([1, 2; 3, 4], [5, 6; 7, 8], [9, 10; 11, 12])
         ⇒  [ 0.50000, 0.66667; 0.66667, 0.50000 ]