naginterfaces.library.sum.invlaplace_​weeks

naginterfaces.library.sum.invlaplace_weeks(f, sigma0, sigma, b, epstol, mmax=1024, data=None)

invlaplace_weeks computes the inverse Laplace transform $f\left(t\right)$ of a user-supplied function $F\left(s\right)$, defined for complex $s$. The function uses a modification of Weeks’ method which is suitable when $f\left(t\right)$ has continuous derivatives of all orders. The function returns the coefficients of an expansion which approximates $f\left(t\right)$ and can be evaluated for given values of $t$ by subsequent calls of invlaplace_weeks_eval().

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

https://www.nag.com/numeric/nl/nagdoc_30/flhtml/c06/c06lbf.html

Parameters

fcallable retval = f(s, data=None)

$f$ must return the value of the Laplace transform function $F\left(s\right)$ for a given complex value of $s$.

Parameters

scomplex

The value of $s$ for which $F\left(s\right)$ must be evaluated. The real part of $s$ is greater than ${\sigma }_0$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

retvalcomplex

The value of the Laplace transform function $F\left(s\right)$ for the given complex value, $s$.

sigma0float

The abscissa of convergence of the Laplace transform, ${\sigma }_0$.

sigmafloat

The parameter $\sigma$ of the Laguerre expansion. If on entry $sigma\le {\sigma }_0$, $sigma$ is reset to ${\sigma }_0+0.7$.

bfloat

The parameter $b$ of the Laguerre expansion. If on entry $b<2(\sigma -{\sigma }_0)$, $b$ is reset to $2.5(\sigma -{\sigma }_0)$.

epstolfloat

The required relative pseudo-accuracy, that is, an upper bound on $|f\left(t\right)-\tilde{f}\left(t\right)|e^{-\sigma t}$.

mmaxint, optional

An upper bound on the number of Laguerre expansion coefficients to be computed. The number of coefficients actually computed is always a power of $2$, so $mmax$ should be a power of $2$; if $mmax$ is not a power of $2$ then the maximum number of coefficients calculated will be the largest power of $2$ less than $mmax$.

dataarbitrary, optional

User-communication data for callback functions.

Returns

sigmafloat

The value actually used for $\sigma$, as just described.

bfloat

The value actually used for $b$, as just described.

mint

The number of Laguerre expansion coefficients actually computed. The number of calls to $f$ is $m/2+2$.

acoeffloat, ndarray, shape $\left(mmax\right)$

The first $m$ elements contain the computed Laguerre expansion coefficients, $a_i$.

errvecfloat, ndarray, shape $\left(8\right)$

An $8$-component vector of diagnostic information.

$errvec\left[0\right]$

Overall estimate of the pseudo-error $|f\left(t\right)-\tilde{f}\left(t\right)|e^{-\sigma t}=errvec\left[1\right]+errvec\left[2\right]+errvec\left[3\right]$.

$errvec\left[1\right]$

Estimate of the discretization pseudo-error.

$errvec\left[2\right]$

Estimate of the truncation pseudo-error.

$errvec\left[3\right]$

Estimate of the condition pseudo-error on the basis of minimal noise levels in function values.

$errvec\left[4\right]$

$K$, coefficient of a heuristic decay function for the expansion coefficients.

$errvec\left[5\right]$

$R$, base of the decay function for the expansion coefficients.

$errvec\left[6\right]$

Logarithm of the largest expansion coefficient.

$errvec\left[7\right]$

Logarithm of the smallest nonzero expansion coefficient.

The values $K$ and $R$ returned in $errvec\left[4\right]$ and $errvec\left[5\right]$ define a decay function $K{R}^{-i}$ constructed by the function for the purposes of error estimation.

It satisfies

$$\left|a_i\right|<K{R}^{-i}\text{,}i=1,2,\dots ,m\text{.}$$

Raises

NagValueError

(errno $1$)

On entry, $mmax=⟨value⟩$.

Constraint: $mmax\ge 8$.

(errno $4$)

The decay rate of the coefficients is too small. Increasing $mmax$ may help. $mmax=⟨value⟩$. Pseudo-error estimate $errvec\left[0\right]=⟨value⟩$ and $epstol=⟨value⟩$.

(errno $5$)

The decay rate of the coefficients is too small and round-off error is such that the required accuracy cannot be obtained. Increasing $mmax$ or $epstol$ may help. $mmax=⟨value⟩$. Pseudo-error estimate $errvec\left[0\right]=⟨value⟩$ and $epstol=⟨value⟩$.

Warns

NagAlgorithmicWarning

(errno $2$)

The estimate of the pseudo-error is slightly larger than $epstol$. Pseudo-error estimate $errvec\left[0\right]=⟨value⟩$ and $epstol=⟨value⟩$.

(errno $3$)

The round-off error level is larger than $epstol$. Increasing $epstol$ may help. Pseudo-error estimate $errvec\left[0\right]=⟨value⟩$ and $epstol=⟨value⟩$.

(errno $6$)

Error bounds cannot be predicted. Check $sigma0$. $sigma0=⟨value⟩$.

Notes

No equivalent traditional C interface for this routine exists in the NAG Library.

Given a function $f\left(t\right)$ of a real variable $t$, its Laplace transform $F\left(s\right)$ is a function of a complex variable $s$, defined by

$$F\left(s\right)={\int }_0^{\infty }{e}^{-st}f\left(t\right)dt\text{,}Re\left(s\right)>{\sigma }_0\text{.}$$

Then $f\left(t\right)$ is the inverse Laplace transform of $F\left(s\right)$. The value ${\sigma }_0$ is referred to as the abscissa of convergence of the Laplace transform; it is the rightmost real part of the singularities of $F\left(s\right)$.

invlaplace_weeks, along with its companion invlaplace_weeks_eval(), attempts to solve the following problem:

given a function $F\left(s\right)$, compute values of its inverse Laplace transform $f\left(t\right)$ for specified values of $t$.

The method is a modification of Weeks’ method (see Garbow et al. (1988a)), which approximates $f\left(t\right)$ by a truncated Laguerre expansion:

$$\tilde{f}\left(t\right)=e^{\sigma t}\sum _{i=0}^{m-1}{a}_i{e}^{-bt/2}{L}_i\left(bt\right)\text{,}\sigma >{\sigma }_0\text{,}b>0$$

where $L_i\left(x\right)$ is the Laguerre polynomial of degree $i$. This function computes the coefficients $a_i$ of the above Laguerre expansion; the expansion can then be evaluated for specified $t$ by calling invlaplace_weeks_eval(). You must supply the value of ${\sigma }_0$, and also suitable values for $\sigma$ and $b$: see Further Comments for guidance.

The method is only suitable when $f\left(t\right)$ has continuous derivatives of all orders. For such functions the approximation $\tilde{f}\left(t\right)$ is usually good and inexpensive. The function will fail with an error exit if the method is not suitable for the supplied function $F\left(s\right)$.

The function is designed to satisfy an accuracy criterion of the form:

$$\left|\frac{f\left(t\right)-\tilde{f}\left(t\right)}{e^{\sigma t}}\right|<{ϵ}_{\text{tol}}\text{, for all}t$$

where ${ϵ}_{\text{tol}}$ is a user-supplied bound. The error measure on the left-hand side is referred to as the pseudo-relative error, or pseudo-error for short. Note that if $\sigma >0$ and $t$ is large, the absolute error in $\tilde{f}\left(t\right)$ may be very large.

invlaplace_weeks is derived from the function MODUL1 in Garbow et al. (1988a).

References

Garbow, B S, Giunta, G, Lyness, J N and Murli, A, 1988, Software for an implementation of Weeks’ method for the inverse laplace transform problem, ACM Trans. Math. Software (14), 163–170

Garbow, B S, Giunta, G, Lyness, J N and Murli, A, 1988, Algorithm 662: A Fortran software package for the numerical inversion of the Laplace transform based on Weeks’ method, ACM Trans. Math. Software (14), 171–176