naginterfaces.library.matop.real_​gen_​matrix_​actexp_​rcomm

naginterfaces.library.matop.real_gen_matrix_actexp_rcomm(irevcm, b, t, b2, x, y, p, r, z, comm, tr=0.0)

real_gen_matrix_actexp_rcomm computes the action of the matrix exponential $e^{tA}$, on the matrix $B$, where $A$ is a real $n\times n$ matrix, $B$ is a real $n\times m$ matrix and $t$ is a real scalar. It uses reverse communication for evaluating matrix products, so that the matrix $A$ is not accessed explicitly.

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

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

Parameters

irevcmint

On initial entry: must be set to $0$.

bfloat, ndarray, shape $(n,m)$, modified in place

On initial entry: the $n\times m$ matrix $B$.

On intermediate exit: if $irevcm=1$, contains the $n\times m$ matrix $B$.

On intermediate entry: must not be changed.

On final exit: the $n\times m$ matrix $e^{tA}B$.

tfloat

The scalar $t$.

b2float, ndarray, shape $(n,m)$, modified in place

On initial entry: need not be set.

On intermediate entry: if $irevcm=1$, must contain $AB$.

On final exit: the array is undefined.

xfloat, ndarray, shape $(n,2)$, modified in place

On initial entry: need not be set.

On intermediate exit: if $irevcm=2$, contains the current $n\times 2$ matrix $X$.

On intermediate entry: if $irevcm=3$, must contain $A^{T}Y$.

On final exit: the array is undefined.

yfloat, ndarray, shape $(n,2)$, modified in place

On initial entry: need not be set.

On intermediate exit: if $irevcm=3$, contains the current $n\times 2$ matrix $Y$.

On intermediate entry: if $irevcm=2$, must contain $AX$.

On final exit: the array is undefined.

pfloat, ndarray, shape $\left(n\right)$, modified in place

On initial entry: need not be set.

On intermediate entry: if $irevcm=4$, must contain $Az$.

On final exit: the array is undefined.

rfloat, ndarray, shape $\left(n\right)$, modified in place

On initial entry: need not be set.

On intermediate entry: if $irevcm=5$, must contain $A^{T}z$.

On final exit: the array is undefined.

zfloat, ndarray, shape $\left(n\right)$, modified in place

On initial entry: need not be set.

On intermediate exit: if $irevcm=4$ or $5$, contains the vector $z$.

On intermediate entry: must not be changed.

On final exit: the array is undefined.

commdict, communication object, modified in place

Communication structure.

On initial entry: need not be set.

trfloat, optional

The trace of $A$. If this is not available then any number can be supplied ($0.0$ is a reasonable default); however, in the trivial case, $n=1$, the result $e^{trt}B$ is immediately returned in the first row of $B$. See Further Comments.

Returns

irevcmint

On intermediate exit: $irevcm=1$, $2$, $3$, $4$ or $5$. The calling program must:

1. if $irevcm=1$: evaluate $B_2=AB$, where $B_2$ is an $n\times m$ matrix, and store the result in $b2$;

   if $irevcm=2$: evaluate $Y=AX$, where $X$ and $Y$ are $n\times 2$ matrices, and store the result in $y$;

   if $irevcm=3$: evaluate $X=A^{T}Y$ and store the result in $x$;

   if $irevcm=4$: evaluate $p=Az$ and store the result in $p$;

   if $irevcm=5$: evaluate $r=A^{T}z$ and store the result in $r$.

2. call real_gen_matrix_actexp_rcomm again with all other parameters unchanged.

On final exit: $irevcm=0$.

Raises

NagValueError

(errno $-3$)

On initial entry, $m=⟨value⟩$.

Constraint: $m\ge 0$.

(errno $-2$)

On initial entry, $n=⟨value⟩$.

Constraint: $n\ge 0$.

(errno $-1$)

On intermediate re-entry, $irevcm=⟨value⟩$.

Constraint: $irevcm=1$, $2$, $3$, $4$ or $5$.

(errno $-1$)

On initial entry, $irevcm=⟨value⟩$.

Constraint: $irevcm=0$.

Warns

NagAlgorithmicWarning

(errno $2$)

$e^{tA}B$ has been computed using an IEEE double precision Taylor series, although the arithmetic precision is higher than IEEE double precision.

Notes

$e^{tA}B$ is computed using the algorithm described in Al–Mohy and Higham (2011) which uses a truncated Taylor series to compute the $e^{tA}B$ without explicitly forming $e^{tA}$.

The algorithm does not explicity need to access the elements of $A$; it only requires the result of matrix multiplications of the form $AX$ or $A^{T}Y$. A reverse communication interface is used, in which control is returned to the calling program whenever a matrix product is required.

References

Al–Mohy, A H and Higham, N J, 2011, Computing the action of the matrix exponential, with an application to exponential integrators, SIAM J. Sci. Statist. Comput. (33(2)), 488-511

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