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

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

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

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

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

Parameters

afloat, 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$. If $z_i$ lies on the real line, then so must $f^{\left(m\right)}\left(z_i\right)$.

dataarbitrary, optional

User-communication data for callback functions.

Returns

afloat, ndarray, shape $(n,n)$

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

imnormfloat

If $A$ has complex eigenvalues, real_gen_matrix_fun_usd will use complex arithmetic to compute $f\left(A\right)$. The imaginary part is discarded at the end of the computation, because it will theoretically vanish. $imnorm$ contains the $1$-norm of the imaginary part, which should be used to check that the function has given a reliable answer.

If $A$ has real eigenvalues, real_gen_matrix_fun_usd uses real arithmetic and $imnorm=0$.

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 routine 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 (generally complex) points $z_{\text{i}}$, for $\text{i}=1,2,\dots ,n_z$. For any $z$ on the real line, $f\left(z\right)$ must also be real. real_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

See also

naginterfaces.library.examples.matop.real_gen_matrix_fun_usd_ex.main()