Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_matop_complex_gen_matrix_pow (f01fq)

## Purpose

nag_matop_complex_gen_matrix_pow (f01fq) computes an abitrary real power ${A}^{p}$ of a complex $n$ by $n$ matrix $A$.

## Syntax

[a, ifail] = f01fq(a, p, 'n', n)
[a, ifail] = nag_matop_complex_gen_matrix_pow(a, p, 'n', n)

## Description

For a matrix $A$ with no eigenvalues on the closed negative real line, ${A}^{p}$ ($p\in ℝ$) can be defined as
 $Ap= expplogA$
where $\mathrm{log}\left(A\right)$ is the principal logarithm of $A$ (the unique logarithm whose spectrum lies in the strip $\left\{z:-\pi <\mathrm{Im}\left(z\right)<\pi \right\}$).
${A}^{p}$ is computed using the Schur–Padé algorithm described in Higham and Lin (2011) and Higham and Lin (2013).
The real number $p$ is expressed as $p=q+r$ where $q\in \left(-1,1\right)$ and $r\in ℤ$. Then ${A}^{p}={A}^{q}{A}^{r}$. The integer power ${A}^{r}$ is found using a combination of binary powering and, if necessary, matrix inversion. The fractional power ${A}^{q}$ is computed using a Schur decomposition and a Padé approximant.

## References

Higham N J (2008) Functions of Matrices: Theory and Computation SIAM, Philadelphia, PA, USA
Higham N J and Lin L (2011) A Schur–Padé algorithm for fractional powers of a matrix SIAM J. Matrix Anal. Appl. 32(3) 1056–1078
Higham N J and Lin L (2013) An improved Schur–Padé algorithm for fractional powers of a matrix and their Fréchet derivatives MIMS Eprint 2013.1 Manchester Institute for Mathematical Sciences, School of Mathematics, University of Manchester http://eprints.ma.man.ac.uk/

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a must be at least ${\mathbf{n}}$.
The second dimension of the array a must be at least ${\mathbf{n}}$.
The $n$ by $n$ matrix $A$.
2:     $\mathrm{p}$ – double scalar
The required power of $A$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the array a.
$n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a will be ${\mathbf{n}}$.
The second dimension of the array a will be ${\mathbf{n}}$.
If ${\mathbf{ifail}}={\mathbf{0}}$, the $n$ by $n$ matrix $p$th power, ${A}^{p}$. Alternatively, if ${\mathbf{ifail}}={\mathbf{1}}$, contains an $n$ by $n$ non-principal power of $A$.
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
$A$ has eigenvalues on the negative real line. The principal $p$th power is not defined so a non-principal power is returned.
${\mathbf{ifail}}=2$
$A$ is singular so the $p$th power cannot be computed.
${\mathbf{ifail}}=3$
${A}^{p}$ has been computed using an IEEE double precision Padé approximant, although the arithmetic precision is higher than IEEE double precision.
${\mathbf{ifail}}=4$
An unexpected internal error occurred. This failure should not occur and suggests that the function has been called incorrectly.
${\mathbf{ifail}}=-1$
Constraint: ${\mathbf{n}}\ge 0$.
${\mathbf{ifail}}=-3$
Constraint: $\mathit{lda}\ge {\mathbf{n}}$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

For positive integer $p$, the algorithm reduces to a sequence of matrix multiplications. For negative integer $p$, the algorithm consists of a combination of matrix inversion and matrix multiplications.
For a normal matrix $A$ (for which ${A}^{\mathrm{H}}A=A{A}^{\mathrm{H}}$) and non-integer $p$, the Schur decomposition is diagonal and the algorithm reduces to evaluating powers of the eigenvalues of $A$ and then constructing ${A}^{p}$ using the Schur vectors. This should give a very accurate result. In general however, no error bounds are available for the algorithm.

The cost of the algorithm is $O\left({n}^{3}\right)$. The exact cost depends on the matrix $A$ but if $p\in \left(-1,1\right)$ then the cost is independent of $p$. $O\left(4×{n}^{2}\right)$ complex allocatable memory is required by the function.
If estimates of the condition number of ${A}^{p}$ are required then nag_matop_complex_gen_matrix_cond_pow (f01ke) should be used.

## Example

This example finds ${A}^{p}$ where $p=0.2$ and
 $A = 2i+ 3i+0 2i+0 1+3i 2+i 1i+0 1i+0 2+2i 2+i 2+2i 2i 2+4i 3i+ 2+2i 3i+0 1i+0 .$
```function f01fq_example

fprintf('f01fq example results\n\n');

% Principal power p of matrix A

a = [ 2    3     2     1+3i;
2+i  1     1     2+2i;
2+i  2+2i    2i  2+4i;
3    2+2i  3     1];

p = 0.2;

[pa, ifail] = f01fq(a,p);

disp('A^p:');
disp(pa);

```
```f01fq example results

A^p:
1.1766 - 0.0758i   0.1375 + 0.2241i   0.2742 - 0.2223i  -0.1435 + 0.0816i
0.2074 - 0.0998i   1.1118 - 0.0039i  -0.1343 - 0.0404i   0.1794 + 0.3590i
-0.0859 - 0.0824i   0.5224 - 0.0530i   1.0616 + 0.3921i   0.2308 + 0.1856i
0.3313 + 0.1303i  -0.1507 + 0.0982i   0.2178 - 0.0061i   1.1710 - 0.2136i

```