NAG Library Routine Document
d02kaf (sl2_reg_finite)
1
Purpose
d02kaf finds a specified eigenvalue of a regular secondorder Sturm–Liouville system defined on a finite range, using a Pruefer transformation and a shooting method.
2
Specification
Fortran Interface
Integer, Intent (In)  ::  k  Integer, Intent (Inout)  ::  ifail  Real (Kind=nag_wp), Intent (In)  ::  xl, xr, tol  Real (Kind=nag_wp), Intent (Inout)  ::  bcond(3,2), elam, delam  External  ::  coeffn, monit 

C Header Interface
#include <nagmk26.h>
void 
d02kaf_ (const double *xl, const double *xr, void (NAG_CALL *coeffn)(double *p, double *q, double *dqdl, const double *x, const double *elam, const Integer *jint), double bcond[], const Integer *k, const double *tol, double *elam, double *delam, void (NAG_CALL *monit)(const Integer *nit, const Integer *iflag, const double *elam, const double finfo[]), Integer *ifail) 

3
Description
d02kaf finds a specified eigenvalue
$\stackrel{~}{\lambda}$ of a Sturm–Liouville system defined by a selfadjoint differential equation of the secondorder
together with boundary conditions of the form
at the two, finite, end points
$a$ and
$b$. The functions
$p$ and
$q$, which are realvalued, are defined by
coeffn.
For the theoretical basis of the numerical method to be valid, the following conditions should hold on the coefficient functions:
(a) 
$p\left(x\right)$ must be nonzero and must not change sign throughout the closed interval $\left[a,b\right]$; 
(b) 
$\frac{\partial q}{\partial \lambda}$ must not change sign and must be nonzero throughout the open interval $\left(a,b\right)$ and for all relevant values of $\lambda $, and must not be identically zero as $x$ varies, for any relevant value $\lambda $; and, 
(c) 
$p$ and $q$ should (as functions of $x$) have continuous derivatives, preferably up to the fourthorder, on $\left[a,b\right]$. The differential equation code used will integrate through mild discontinuities, but probably with severely reduced efficiency. Therefore, if $p$ and $q$ violate this condition, d02kdf should be used. 
The eigenvalue
$\stackrel{~}{\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
$\stackrel{~}{\lambda}$ will be correct to within a mixed absolute/relative error specified by
tol.
d02kaf is a driver routine for the more complicated routine
d02kdf 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 Chapter 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).
4
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
5
Arguments
 1: $\mathbf{xl}$ – Real (Kind=nag_wp)Input
 2: $\mathbf{xr}$ – Real (Kind=nag_wp)Input

On entry: the left and righthand end points $a$ and $b$ respectively, of the interval of definition of the problem.
Constraint:
${\mathbf{xl}}<{\mathbf{xr}}$.
 3: $\mathbf{coeffn}$ – Subroutine, supplied by the user.External Procedure

coeffn must compute the values of the coefficient functions
$p\left(x\right)$ and
$q\left(x;\lambda \right)$ for given values of
$x$ and
$\lambda $.
Section 3 states the conditions which
$p$ and
$q$ must satisfy.
The specification of
coeffn is:
Fortran Interface
Integer, Intent (In)  ::  jint  Real (Kind=nag_wp), Intent (In)  ::  x, elam  Real (Kind=nag_wp), Intent (Out)  ::  p, q, dqdl 

C Header Interface
#include <nagmk26.h>
void 
coeffn (double *p, double *q, double *dqdl, const double *x, const double *elam, const Integer *jint) 

 1: $\mathbf{p}$ – Real (Kind=nag_wp)Output

On exit: the value of $p\left(x\right)$ for the current value of $x$.
 2: $\mathbf{q}$ – Real (Kind=nag_wp)Output

On exit: the value of $q\left(x;\lambda \right)$ for the current value of $x$ and the current trial value of $\lambda $.
 3: $\mathbf{dqdl}$ – Real (Kind=nag_wp)Output

On exit: the value of
$\frac{\partial q}{\partial \lambda}\left(x;\lambda \right)$ 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.
 4: $\mathbf{x}$ – Real (Kind=nag_wp)Input

On entry: the current value of $x$.
 5: $\mathbf{elam}$ – Real (Kind=nag_wp)Input

On entry: the current trial value of the eigenvalue argument $\lambda $.
 6: $\mathbf{jint}$ – IntegerInput

This argument is included for compatibility with the more complex routine
d02kdf (which is called by
d02kaf).
On entry: need not be set.
coeffn must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which
d02kaf is called. Arguments denoted as
Input must
not be changed by this procedure.
Note: coeffn should not return floatingpoint NaN (Not a Number) or infinity values, since these are not handled by
d02kaf. If your code inadvertently
does return any NaNs or infinities,
d02kaf is likely to produce unexpected results.
 4: $\mathbf{bcond}\left(3,2\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry:
${\mathbf{bcond}}\left(1,1\right)$ and
${\mathbf{bcond}}\left(2,1\right)$ must contain the numbers
${a}_{1}$,
${a}_{2}$ specifying the lefthand boundary condition in the form
where
$\left{a}_{2}\right+\left{a}_{1}p\left(a\right)\right\ne 0$.
${\mathbf{bcond}}\left(1,2\right)$ and
${\mathbf{bcond}}\left(2,2\right)$ must contain
${b}_{1}$,
${b}_{2}$ such that
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.
On exit:
${\mathbf{bcond}}\left(3,1\right)$ and
${\mathbf{bcond}}\left(3,2\right)$ 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
$\left[0,\infty \right]$ 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
Section 9.5 in
d02kdf, for the actual meaning of
${\sigma}_{r}$ and
${\sigma}_{l}$.
 5: $\mathbf{k}$ – IntegerInput

On entry:
$k$, the index of the required eigenvalue when the eigenvalues are ordered
Constraint:
${\mathbf{k}}\ge 0$.
 6: $\mathbf{tol}$ – Real (Kind=nag_wp)Input

On entry: 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
where
elam is the final estimate of the eigenvalue.
delam is usually somewhat smaller than the righthand side of
(1) but not several orders of magnitude smaller.
Constraint:
${\mathbf{tol}}>0.0$.
 7: $\mathbf{elam}$ – Real (Kind=nag_wp)Input/Output

On entry: an initial estimate of the eigenvalue $\stackrel{~}{\lambda}$.
On exit: the final computed estimate, whether or not an error occurred.
 8: $\mathbf{delam}$ – Real (Kind=nag_wp)Input/Output

On entry: 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
${\mathbf{elam}}+{\mathbf{delam}}$, so the routine 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 ${\mathbf{delam}}=0.0$ on entry, it is given the default value of $0.25\times \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1.0,\left{\mathbf{elam}}\right\right)$.
On exit: if
${\mathbf{ifail}}={\mathbf{0}}$,
delam holds an estimate of the absolute error in the computed eigenvalue, that is
$\left\stackrel{~}{\lambda}{\mathbf{elam}}\right\simeq {\mathbf{delam}}$, where
$\stackrel{~}{\lambda}$ is the true eigenvalue.
If
${\mathbf{ifail}}\ne {\mathbf{0}}$,
delam may hold an estimate of the error, or its initial value, depending on the value of
ifail. See
Section 6 for further details.
 9: $\mathbf{monit}$ – Subroutine, supplied by the NAG Library or the user.External Procedure

monit is called by
d02kaf at the end of each iteration for
$\lambda $ and allows you to monitor the course of the computation by printing out the arguments (see
Section 10 for an example).
If no monitoring is required, the dummy (sub)program d02kay may be used. (d02kay is included in the NAG Library.)
The specification of
monit is:
Fortran Interface
Integer, Intent (In)  ::  nit, iflag  Real (Kind=nag_wp), Intent (In)  ::  elam, finfo(15) 

C Header Interface
#include <nagmk26.h>
void 
monit (const Integer *nit, const Integer *iflag, const double *elam, const double finfo[]) 

 1: $\mathbf{nit}$ – IntegerInput

On entry: 15 minus the number of iterations used so far in the search for $\stackrel{~}{\lambda}$. (Up to $15$ iterations are permitted.)
 2: $\mathbf{iflag}$ – IntegerInput

On entry: describes what phase the computation is in.
 ${\mathbf{iflag}}<0$
 An error occurred in the computation at this iteration; an error exit from d02kaf will follow.
 ${\mathbf{iflag}}=1$
 The routine is trying to bracket the eigenvalue $\stackrel{~}{\lambda}$.
 ${\mathbf{iflag}}=2$
 The routine is converging to the eigenvalue $\stackrel{~}{\lambda}$ (having already bracketed it).
Normally, the iteration will terminate after a sequence of iterates with ${\mathbf{iflag}}=2$, but occasionally the bracket on $\stackrel{~}{\lambda}$ thus determined will not be sufficiently small and the iteration will be repeated with tighter accuracy control.
 3: $\mathbf{elam}$ – Real (Kind=nag_wp)Input

On entry: the current trial value of $\stackrel{~}{\lambda}$.
 4: $\mathbf{finfo}\left(15\right)$ – Real (Kind=nag_wp) arrayInput

On entry: 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
${\mathbf{iflag}}\ge 0$), though the first few components may be of interest to you. In case of an error (
${\mathbf{iflag}}<0$) all the components of
finfo should be printed.
The contents of
finfo are as follows:
 ${\mathbf{finfo}}\left(1\right)$
 The current value of the ‘missdistance’ or ‘residual’ function $f\left(\lambda \right)$ on which the shooting method is based. $f\left(\stackrel{~}{\lambda}\right)=0$ in theory. This is set to zero if ${\mathbf{iflag}}<0$.
 ${\mathbf{finfo}}\left(2\right)$
 An estimate of the quantity $\partial \lambda $ defined as follows. Consider the perturbation in the missdistance $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 ${\mathbf{ifail}}={\mathbf{5}}$ should follow. ${\mathbf{finfo}}\left(2\right)$ is set to zero if ${\mathbf{iflag}}<0$.
 ${\mathbf{finfo}}\left(3\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$.
 ${\mathbf{finfo}}\left(4\right)$
 The number of calls to coeffn at this iteration.
 ${\mathbf{finfo}}\left(5\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.
 ${\mathbf{finfo}}\left(6\right)$
 The number of unsuccessful steps used by the internal integrator at this iteration.
 ${\mathbf{finfo}}\left(7\right)$
 The number of successful steps at the maximum step size taken by the internal integrator at this iteration.
 ${\mathbf{finfo}}\left(8\right)$
 Not used.
 ${\mathbf{finfo}}\left(9\right)$ to ${\mathbf{finfo}}\left(15\right)$
 Set to zero, unless ${\mathbf{iflag}}<0$ in which case they hold the following values describing the point of failure:
 ${\mathbf{finfo}}\left(9\right)$
 1 or $2$ depending on whether integration was in a forward or backward direction at the time of failure.
 ${\mathbf{finfo}}\left(10\right)$
 The value of the independent variable, $x$, the point at which the error occurred.
 ${\mathbf{finfo}}\left(11\right)$, ${\mathbf{finfo}}\left(12\right)$, ${\mathbf{finfo}}\left(13\right)$
 The current values of the Pruefer dependent variables $\beta $, $\varphi $ and $\rho $ respectively. See Section 3 in d02kef for a description of these variables.
 ${\mathbf{finfo}}\left(14\right)$
 The localerror tolerance being used by the internal integrator at the point of failure.
 ${\mathbf{finfo}}\left(15\right)$
 The last integration mesh point.
monit must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which
d02kaf is called. Arguments denoted as
Input must
not be changed by this procedure.
 10: $\mathbf{ifail}$ – IntegerInput/Output

On entry:
ifail must be set to
$0$,
$1\text{or}1$. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is
$0$.
When the value $\mathbf{1}\text{or}\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

On entry, ${\mathbf{k}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{k}}\ge 0$.
On entry, ${\mathbf{tol}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{tol}}>0.0$.
 ${\mathbf{ifail}}=2$

The constraint on the left or righthand boundary condition has been violated.
 ${\mathbf{ifail}}=3$

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

After $15$ iterations the eigenvalue had not been found to the required accuracy.
 ${\mathbf{ifail}}=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.
On exit, ${\mathbf{elam}}$ and ${\mathbf{elam}}+{\mathbf{delam}}$ give the end points of the interval within which no eigenvalue was located by the routine.
 ${\mathbf{ifail}}=6$

Too small a step size was required at the start of a subinterval to obtain the desired accuracy.
 ${\mathbf{ifail}}=7$

Too small a step size was required during solution in a subinterval to obtain the desired accuracy.
At some point inside a subinterval the step size in the differential equation solver was reduced to a value too small to make significant progress (for the same reasons as with
${\mathbf{ifail}}={\mathbf{7}}$). This could be due to pathological behaviour of
$p\left(x\right)$ and
$q\left(x;\lambda \right)$ or to an unreasonable accuracy requirement or to the current value of
$\lambda $ making the equations ‘stiff’. See the last call of
monit for details.
 ${\mathbf{ifail}}=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.
 ${\mathbf{ifail}}=9$

An internal error has occurred corresponding to a pole of the matching function. Try solving the problem again with a smaller tolerance.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
The absolute accuracy of the computed eigenvalue is usually within a mixed absolute/relative bound defined by
tol (as defined above).
8
Parallelism and Performance
d02kaf is not threaded in any implementation.
The time taken by
d02kaf depends on the complexity of the coefficient functions, whether they or their derivatives are rapidly changing, the tolerance demanded, and how many iterations are needed to obtain convergence. The amount of work per iteration is roughly doubled when
tol is divided by
$16$. To make the most economical use of the routine, one should try to obtain good initial values for
elam and
delam.
See
Section 9 in
d02kdf for a discussion of the technique used.
10
Example
This example finds the fourth eigenvalue of Mathieu's equations
with boundary conditions
and
$q=5$. We use a starting value
${\mathbf{elam}}=15.0$ and a step
${\mathbf{delam}}=4.0$. We illustrate the effect of varying
tol by choosing
${\mathbf{tol}}=\text{1.0E\u22125}$ and
$\text{1.0E\u22126}$ (note the change in the output value of the error estimate
delam). The range of integration and initial estimates are read from a data file.
10.1
Program Text
Program Text (d02kafe.f90)
10.2
Program Data
Program Data (d02kafe.d)
10.3
Program Results
Program Results (d02kafe.r)