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

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

real_gen_matrix_fun_usd computes the matrix function, , of a real matrix , using analytical derivatives of you have supplied.

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

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

Parameters
afloat, array-like, shape

The matrix .

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

Given an integer , the function evaluates at a number of points .

Parameters
mint

The order, , of the derivative required.

If , should be returned.

For , should be returned.

zcomplex, ndarray, shape

The points at which the function is to be evaluated.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
fzcomplex, array-like, shape

The function or derivative values. should return the value , for . If lies on the real line, then so must .

dataarbitrary, optional

User-communication data for callback functions.

Returns
afloat, ndarray, shape

The matrix, .

imnormfloat

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

If has real eigenvalues, real_gen_matrix_fun_usd uses real arithmetic and .

Raises
NagValueError
(errno )

On entry, .

Constraint: .

(errno )

A Taylor series failed to converge.

(errno )

There was an error whilst reordering the Schur form of .

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

(errno )

The routine was unable to compute the Schur decomposition of .

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

(errno )

An unexpected internal error occurred. Please contact NAG.

Warns
NagCallbackTerminateWarning
(errno )

Termination requested in .

Notes

is computed using the Schur–Parlett algorithm described in Higham (2008) and Davies and Higham (2003).

The scalar function , and the derivatives of , are returned by the function which, given an integer , should evaluate at a number of (generally complex) points , for . For any on the real line, 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