naginterfaces.library.matop.complex_​gen_​matrix_​fun_​usd

naginterfaces.library.matop.complex_gen_matrix_fun_usd(a, f, data=None)

complex_gen_matrix_fun_usd computes the matrix function, $f\left(A\right)$, of a complex $n\times n$ matrix $A$, using analytical derivatives of $f$ you have supplied.

For full information please refer to the NAG Library document for f01fm

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01fmf.html

Parameters

acomplex, array-like, shape $(n,n)$

The $n\times n$ matrix $A$.

fcallable fz = f(m, z, data=None)

Given an integer $m$, the function $f$ evaluates $f^{\left(m\right)}\left(z_i\right)$ at a number of points $z_i$.

Parameters

mint

The order, $m$, of the derivative required.

If $m=0$, $f\left(z_i\right)$ should be returned.

For $m>0$, $f^{\left(m\right)}\left(z_i\right)$ should be returned.

zcomplex, ndarray, shape $\left(\text{nz}\right)$

The $n_z$ points $z_1,z_2,\dots ,z_{n_z}$ at which the function $f$ is to be evaluated.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

fzcomplex, array-like, shape $\left(\text{nz}\right)$

The $n_z$ function or derivative values. $fz[\text{i}-1]$ should return the value $f^{\left(m\right)}\left(z_{\text{i}}\right)$, for $\text{i}=1,2,\dots ,n_z$.

dataarbitrary, optional

User-communication data for callback functions.

Returns

acomplex, ndarray, shape $(n,n)$

The $n\times n$ matrix, $f\left(A\right)$.

Raises

NagValueError

(errno $-1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 0$.

(errno $1$)

A Taylor series failed to converge.

(errno $3$)

There was an error whilst reordering the Schur form of $A$.

Note: this failure should not occur and suggests that the function has been called incorrectly.

(errno $4$)

The function was unable to compute the Schur decomposition of $A$.

Note: this failure should not occur and suggests that the function has been called incorrectly.

(errno $5$)

An unexpected internal error occurred. Please contact NAG.

Warns

NagCallbackTerminateWarning

(errno $2$)

Termination requested in $f$.

Notes

$f\left(A\right)$ is computed using the Schur–Parlett algorithm described in Higham (2008) and Davies and Higham (2003).

The scalar function $f$, and the derivatives of $f$, are returned by the function $f$ which, given an integer $m$, should evaluate $f^{\left(m\right)}\left(z_{\text{i}}\right)$ at a number of points $z_{\text{i}}$, for $\text{i}=1,2,\dots ,n_z$, on the complex plane. complex_gen_matrix_fun_usd is, therefore, appropriate for functions that can be evaluated on the complex plane and whose derivatives, of arbitrary order, can also be evaluated on the complex plane.

References

Davies, P I and Higham, N J, 2003, A Schur–Parlett algorithm for computing matrix functions, SIAM J. Matrix Anal. Appl. (25(2)), 464–485

Higham, N J, 2008, Functions of Matrices: Theory and Computation, SIAM, Philadelphia, PA, USA