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

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

real_gen_matrix_fun_num computes the matrix function, $f\left(A\right)$, of a real $n\times n$ matrix $A$. Numerical differentiation is used to evaluate the derivatives of $f$ when they are required.

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

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

Parameters

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

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

fcallable fz = f(z, data=None)

The function $f$ evaluates $f\left(z_i\right)$ at a number of points $z_i$.

Parameters

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 values. $fz[\text{i}-1]$ should return the value $f\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(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_num 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 routine has given a reliable answer.

If $a$ has real eigenvalues, real_gen_matrix_fun_num 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 after $40$ terms. Further Taylor series coefficients can no longer reliably be obtained by numerical differentiation.

(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 coefficients of the Taylor series used in the algorithm are evaluated using the numerical differentiation algorithm of Lyness and Moler (1967).

The scalar function $f$ is supplied via function $f$ which evaluates $f\left(z_i\right)$ at a number of points $z_i$.

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

Lyness, J N and Moler, C B, 1967, Numerical differentiation of analytic functions, SIAM J. Numer. Anal. (4(2)), 202–210