naginterfaces.library.ode.sl2_​reg_​finite

naginterfaces.library.ode.sl2_reg_finite(xl, xr, coeffn, bcond, k, tol, elam, delam, monit=None, data=None)

sl2_reg_finite finds a specified eigenvalue of a regular second-order Sturm–Liouville system defined on a finite range, using a Pruefer transformation and a shooting method.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d02/d02kaf.html

Parameters

xlfloat

The left- and right-hand end points $a$ and $b$ respectively, of the interval of definition of the problem.

xrfloat

The left- and right-hand end points $a$ and $b$ respectively, of the interval of definition of the problem.

coeffncallable (p, q, dqdl) = coeffn(x, elam, jint, data=None)

$coeffn$ must compute the values of the coefficient functions $p\left(x\right)$ and $q(x;\lambda )$ for given values of $x$ and $\lambda$. Notes states the conditions which $p$ and $q$ must satisfy.

Parameters

xfloat

The current value of $x$.

elamfloat

The current trial value of the eigenvalue argument $\lambda$.

jintint

This argument is included for compatibility with the more complex function sl2_breaks_vals() (which is called by sl2_reg_finite).

Need not be set.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

pfloat

The value of $p\left(x\right)$ for the current value of $x$.

qfloat

The value of $q(x;\lambda )$ for the current value of $x$ and the current trial value of $\lambda$.

dqdlfloat

The value of $\frac{\partial q}{\partial \lambda }(x;\lambda )$ for the current value of $x$ and the current trial value of $\lambda$. However $dqdl$ is only used in error estimation and, in the rare cases where it may be difficult to evaluate, an approximation (say to within $20\%$) will suffice.

bcondfloat, array-like, shape $(3,2)$

$bcond[0,0]$ and $bcond[1,0]$ must contain the numbers $a_1$, $a_2$ specifying the left-hand boundary condition in the form

$$a_{2}y\left(a\right)=a_{1}p\left(a\right)y^{\prime }\left(a\right)$$

where $\left|a_2\right|+\left|a_{1}p\left(a\right)\right|\ne 0$.

$bcond[0,1]$ and $bcond[1,1]$ must contain $b_1$, $b_2$ such that

$$b_{2}y\left(b\right)=b_{1}p\left(b\right)y^{\prime }\left(b\right)$$

where $\left|b_2\right|+\left|b_{1}p\left(b\right)\right|\ne 0$.

Note the occurrence of $p\left(a\right)$, $p\left(b\right)$ in these formulae.

kint

$k$, the index of the required eigenvalue when the eigenvalues are ordered

$${\lambda }_0<{\lambda }_1<{\lambda }_2<\cdots <{\lambda }_k<\cdots \text{.}$$

tolfloat

The tolerance argument which determines the accuracy of the computed eigenvalue. The error estimate held in $delam$ on exit satisfies the mixed absolute/relative error test

$$delam\le tol\times max(1.0,\left|elam\right|)\text{,}$$

where $elam$ is the final estimate of the eigenvalue. $delam$ is usually somewhat smaller than the right-hand side of (1) but not several orders of magnitude smaller.

elamfloat

An initial estimate of the eigenvalue $\tilde{\lambda }$.

delamfloat

An indication of the scale of the problem in the $\lambda$-direction. $delam$ holds the initial ‘search step’ (positive or negative). Its value is not critical, but the first two trial evaluations are made at $elam$ and $elam+delam$, so the function will work most efficiently if the eigenvalue lies between these values. A reasonable choice (if a closer bound is not known) is about half the distance between adjacent eigenvalues in the neighbourhood of the one sought. In practice, there will often be a problem, similar to the one in hand but with known eigenvalues, which will help one to choose initial values for $elam$ and $delam$.

If $delam=0.0$ on entry, it is given the default value of $0.25\times max(1.0,\left|elam\right|)$.

monitNone or callable monit(nit, iflag, elam, finfo, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

$monit$ is called by sl2_reg_finite at the end of each iteration for $\lambda$ and allows you to monitor the course of the computation by printing out the arguments.

Parameters

nitint

15 minus the number of iterations used so far in the search for $\tilde{\lambda }$. (Up to $15$ iterations are permitted.)

iflagint

Describes what phase the computation is in.

$iflag<0$

An error occurred in the computation at this iteration; an error exit from sl2_reg_finite will follow.

$iflag=1$

The function is trying to bracket the eigenvalue $\tilde{\lambda }$.

$iflag=2$

The function is converging to the eigenvalue $\tilde{\lambda }$ (having already bracketed it).

Normally, the iteration will terminate after a sequence of iterates with $iflag=2$, but occasionally the bracket on $\tilde{\lambda }$ thus determined will not be sufficiently small and the iteration will be repeated with tighter accuracy control.

elamfloat

The current trial value of $\tilde{\lambda }$.

finfofloat, ndarray, shape $\left(15\right)$

Information about the behaviour of the shooting method, and diagnostic information in the case of errors. It should not normally be printed in full if no error has occurred (that is, if $iflag\ge 0$), though the first few components may be of interest to you. In case of an error ($iflag<0$) all the components of $finfo$ should be printed.

The contents of $finfo$ are as follows:

$finfo\left[0\right]$

The current value of the ‘miss-distance’ or ‘residual’ function $f\left(\lambda \right)$ on which the shooting method is based. $f\left(\tilde{\lambda }\right)=0$ in theory. This is set to zero if $iflag<0$.

$finfo\left[1\right]$

An estimate of the quantity $\partial \lambda$ defined as follows. Consider the perturbation in the miss-distance $f\left(\lambda \right)$ that would result if the local error in the solution of the differential equation were always positive and equal to its maximum permitted value. Then $\partial \lambda$ is the perturbation in $\lambda$ that would have the same effect on $f\left(\lambda \right)$. Thus, at the zero of $f\left(\lambda \right),\left|\partial \lambda \right|$ is an approximate bound on the perturbation of the zero (that is the eigenvalue) caused by errors in numerical solution. If $\partial \lambda$ is very large then it is possible that there has been a programming error in $coeffn$ such that $q$ is independent of $\lambda$. If this is the case, an error exit with $errno$ = 5 should follow. $finfo\left[1\right]$ is set to zero if $iflag<0$.

$finfo\left[2\right]$

The number of internal iterations, using the same value of $\lambda$ and tighter accuracy tolerances, needed to bring the accuracy (that is, the value of $\partial \lambda$) to an acceptable value. Its value should normally be $1.0$, and should almost never exceed $2.0$.

$finfo\left[3\right]$

The number of calls to $coeffn$ at this iteration.

$finfo\left[4\right]$

The number of successful steps taken by the internal differential equation solver at this iteration. A step is successful if it is used to advance the integration.

$finfo\left[5\right]$

The number of unsuccessful steps used by the internal integrator at this iteration.

$finfo\left[6\right]$

The number of successful steps at the maximum step size taken by the internal integrator at this iteration.

$finfo\left[7\right]$

Not used.

$finfo\left[8\right]$ to $finfo\left[14\right]$

Set to zero, unless $iflag<0$ in which case they hold the following values describing the point of failure:

$finfo\left[8\right]$

1 or $2$ depending on whether integration was in a forward or backward direction at the time of failure.

$finfo\left[9\right]$

The value of the independent variable, $x$, the point at which the error occurred.

$finfo\left[10\right]$, $finfo\left[11\right]$, $finfo\left[12\right]$

The current values of the Pruefer dependent variables $\beta$, $\varphi$ and $\rho$ respectively. See Notes for sl2_breaks_funs for a description of these variables.

$finfo\left[13\right]$

The local-error tolerance being used by the internal integrator at the point of failure.

$finfo\left[14\right]$

The last integration mesh point.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

dataarbitrary, optional

User-communication data for callback functions.

Returns

bcondfloat, ndarray, shape $(3,2)$

$bcond[2,0]$ and $bcond[2,1]$ hold values ${\sigma }_l,{\sigma }_r$ estimating the sensitivity of the computed eigenvalue to changes in the boundary conditions. These values should only be of interest if the boundary conditions are, in some sense, an approximation to some ‘true’ boundary conditions. For example, if the range [$xl$, $xr$] should really be $[0,\infty ]$ but instead $xr$ has been given a large value and the boundary conditions at infinity applied at $xr$, the sensitivity argument ${\sigma }_r$ may be of interest. Refer to Further Comments, for the actual meaning of ${\sigma }_r$ and ${\sigma }_l$.

elamfloat

The final computed estimate, whether or not an error occurred.

delamfloat

If no exception or warning is raised, $delam$ holds an estimate of the absolute error in the computed eigenvalue, that is $|\tilde{\lambda }-elam|\simeq delam$, where $\tilde{\lambda }$ is the true eigenvalue.

If an exception is raised, $delam$ may hold an estimate of the error, or its initial value, depending on the value of $\text{errno}$.

See Exceptions for further details.

Raises

NagValueError

(errno $1$)

On entry, $tol=⟨value⟩$.

Constraint: $tol>0.0$.

(errno $1$)

On entry, $k=⟨value⟩$.

Constraint: $k\ge 0$.

(errno $2$)

The constraint on the left- or right-hand boundary condition has been violated.

(errno $3$)

The function $p\left(x\right)$ became zero or changed sign in the interval $[a,b]$.

(errno $4$)

After $15$ iterations the eigenvalue had not been found to the required accuracy.

(errno $5$)

The bracketing phase failed to bracket the eigenvalue within ten iterations. This may be due to an error in formulating the problem (for example, $q$ is independent of $\lambda$), or by very poor initial estimates for the eigenvalue and search step.

(errno $6$)

Too small a step size was required at the start of a sub-interval to obtain the desired accuracy.

(errno $7$)

Too small a step size was required during solution in a sub-interval to obtain the desired accuracy.

(errno $9$)

An internal error has occurred corresponding to a pole of the matching function. Try solving the problem again with a smaller tolerance.

Warns

NagAlgorithmicWarning

(errno $8$)

The tolerance set is too small for the problem being solved and the machine precision being used. The local eigenvalue estimate returned is likely to be a very good approximation.

Notes

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

sl2_reg_finite finds a specified eigenvalue $\tilde{\lambda }$ of a Sturm–Liouville system defined by a self-adjoint differential equation of the second-order

$${\left(p\left(x\right)y^{\prime }\right)}^{\prime }+q(x;\lambda )y=0\text{,}a<x<b\text{,}$$

together with boundary conditions of the form

$$a_{2}y\left(a\right)=a_{1}p\left(a\right)y^{\prime }\left(a\right)$$

$$b_{2}y\left(b\right)=b_{1}p\left(b\right)y^{\prime }\left(b\right)$$

at the two, finite, end points $a$ and $b$. The functions $p$ and $q$, which are real-valued, are defined by $coeffn$.

For the theoretical basis of the numerical method to be valid, the following conditions should hold on the coefficient functions:

1. $p\left(x\right)$ must be nonzero and must not change sign throughout the closed interval $[a,b]$;

2. $\frac{\partial q}{\partial \lambda }$ must not change sign and must be nonzero throughout the open interval $(a,b)$ and for all relevant values of $\lambda$, and must not be identically zero as $x$ varies, for any relevant value $\lambda$; and,

3. $p$ and $q$ should (as functions of $x$) have continuous derivatives, preferably up to the fourth-order, on $[a,b]$. The differential equation code used will integrate through mild discontinuities, but probably with severely reduced efficiency. Therefore, if $p$ and $q$ violate this condition, sl2_breaks_vals() should be used.

The eigenvalue $\tilde{\lambda }$ is determined by a shooting method based on a Pruefer transformation of the differential equations. Providing certain assumptions are met, the computed value of $\tilde{\lambda }$ will be correct to within a mixed absolute/relative error specified by $tol$. sl2_reg_finite is a driver function for the more complicated function sl2_breaks_vals() whose specification provides more details of the techniques used.

A good account of the theory of Sturm–Liouville systems, with some description of Pruefer transformations, is given in Module X of Birkhoff and Rota (1962). An introduction to the use of Pruefer transformations for the numerical solution of eigenvalue problems arising from physics and chemistry is given in Bailey (1966).

References

Bailey, P B, 1966, Sturm–Liouville eigenvalues via a phase function, SIAM J. Appl. Math. (14), 242–249

Birkhoff, G and Rota, G C, 1962, Ordinary Differential Equations, Ginn & Co., Boston and New York