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

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

real_gen_matrix_cond_usd computes an estimate of the absolute condition number of a matrix function $f$ at a real $n\times n$ matrix $A$ in the $1$-norm, using analytical derivatives of $f$ you have supplied.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f01/f01jcf.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)$.

condafloat

An estimate of the absolute condition number of $f$ at $A$.

normafloat

The $1$-norm of $A$.

normfafloat

The $1$-norm of $f\left(A\right)$.

Raises

NagValueError

(errno $-1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 0$.

(errno $1$)

An internal error occurred when estimating the norm of the Fréchet derivative of $f$ at $A$. Please contact NAG.

(errno $2$)

An internal error occurred when evaluating the matrix function $f\left(A\right)$. You can investigate further by calling real_gen_matrix_fun_usd() with the matrix $A$ and the function $f$.

Warns

NagCallbackTerminateWarning

(errno $3$)

Termination requested in $f$.

Notes

The absolute condition number of $f$ at $A$, ${cond}_{abs}(f,A)$ is given by the norm of the Fréchet derivative of $f$, $L\left(A\right)$, which is defined by

$$\parallel L\left(X\right)\parallel :={max}_{E\ne 0}\frac{\parallel L(X,E)\parallel }{\parallel E\parallel }\text{,}$$

where $L(X,E)$ is the Fréchet derivative in the direction $E$. $L(X,E)$ is linear in $E$ and can, therefore, be written as

$$vec\left(L(X,E)\right)=K\left(X\right)vec\left(E\right)\text{,}$$

where the $vec$ operator stacks the columns of a matrix into one vector, so that $K\left(X\right)$ is $n^2\times n^2$. real_gen_matrix_cond_usd computes an estimate $\gamma$ such that $\gamma \le {\parallel K\left(X\right)\parallel }_1$, where ${\parallel K\left(X\right)\parallel }_1\in [n^{-1}{\parallel L\left(X\right)\parallel }_1,n{\parallel L\left(X\right)\parallel }_1]$. The relative condition number can then be computed via

$${cond}_{rel}(f,A)=\frac{{cond}_{abs}(f,A){\parallel A\parallel }_1}{{\parallel f\left(A\right)\parallel }_1}\text{.}$$

The algorithm used to find $\gamma$ is detailed in Section 3.4 of Higham (2008).

The function $f$, and the derivatives of $f$, are returned by function $f$ which, given an integer $m$, evaluates $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_cond_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

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