PDF version (NAG web site
, 64bit version, 64bit version)
NAG Toolbox: nag_ode_sl2_reg_finite (d02ka)
Purpose
nag_ode_sl2_reg_finite (d02ka) finds a specified eigenvalue of a regular secondorder Sturm–Liouville system defined on a finite range, using a Pruefer transformation and a shooting method.
Syntax
[
bcond,
elam,
delam,
ifail] = d02ka(
xl,
xr,
coeffn,
bcond,
k,
tol,
elam,
delam,
monit)
[
bcond,
elam,
delam,
ifail] = nag_ode_sl2_reg_finite(
xl,
xr,
coeffn,
bcond,
k,
tol,
elam,
delam,
monit)
Description
nag_ode_sl2_reg_finite (d02ka) 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$a$ and
b$b$. The functions
p$p$ and
q$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(x)$p\left(x\right)$ must be nonzero and must not change sign throughout the closed interval [a,b]$[a,b]$; 
(b) 
( ∂ q)/( ∂ λ)
$\frac{\partial q}{\partial \lambda}$ must not change sign and must be nonzero throughout the open interval (a,b)$(a,b)$ and for all relevant values of λ$\lambda $, and must not be identically zero as x$x$ varies, for any relevant value λ$\lambda $; and, 
(c) 
p$p$ and q$q$ should (as functions of x$x$) have continuous derivatives, preferably up to the fourthorder, on [a,b]$[a,b]$. The differential equation code used will integrate through mild discontinuities, but probably with severely reduced efficiency. Therefore, if p$p$ and q$q$ violate this condition, nag_ode_sl2_breaks_vals (d02kd) 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.
nag_ode_sl2_reg_finite (d02ka) is a driver function for the more complicated function
nag_ode_sl2_breaks_vals (d02kd) 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).
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
Parameters
Compulsory Input Parameters
 1:
xl – double scalar
 2:
xr – double scalar
The left and righthand end points a$a$ and b$b$ respectively, of the interval of definition of the problem.
Constraint:
xl < xr${\mathbf{xl}}<{\mathbf{xr}}$.
 3:
coeffn – function handle or string containing name of mfile
coeffn must compute the values of the coefficient functions
p(x)$p\left(x\right)$ and
q(x ; λ)$q(x;\lambda )$ for given values of
x$x$ and
λ$\lambda $.
Section [Description] states the conditions which
p$p$ and
q$q$ must satisfy.
[p, q, dqdl] = coeffn(x, elam, jint)
Input Parameters
 1:
x – double scalar
The current value of x$x$.
 2:
elam – double scalar
The current trial value of the eigenvalue parameter λ$\lambda $.
 3:
jint – int64int32nag_int scalar
This parameter is included for compatibility with the more complex function
nag_ode_sl2_breaks_vals (d02kd) (which is called by
nag_ode_sl2_reg_finite (d02ka)).
Need not be set.
Output Parameters
 1:
p – double scalar
The value of p(x)$p\left(x\right)$ for the current value of x$x$.
 2:
q – double scalar
The value of q(x ; λ)$q(x;\lambda )$ for the current value of x$x$ and the current trial value of λ$\lambda $.
 3:
dqdl – double scalar
The value of
( ∂ q)/( ∂ λ) (x ; λ) $\frac{\partial q}{\partial \lambda}(x;\lambda )$ for the current value of
x$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%$20\%$) will suffice.
 4:
bcond(3$3$,2$2$) – double array
bcond(1,1)${\mathbf{bcond}}\left(1,1\right)$ and
bcond(2,1)${\mathbf{bcond}}\left(2,1\right)$ must contain the numbers
a_{1}${a}_{1}$,
a_{2}${a}_{2}$ specifying the lefthand boundary condition in the form
where
a_{2} + a_{1}p(a) ≠ 0$\left{a}_{2}\right+\left{a}_{1}p\left(a\right)\right\ne 0$.
bcond(1,2)${\mathbf{bcond}}\left(1,2\right)$ and
bcond(2,2)${\mathbf{bcond}}\left(2,2\right)$ must contain
b_{1}${b}_{1}$,
b_{2}${b}_{2}$ such that
where
b_{2} + b_{1}p(b) ≠ 0$\left{b}_{2}\right+\left{b}_{1}p\left(b\right)\right\ne 0$.
Note the occurrence of p(a)$p\left(a\right)$, p(b)$p\left(b\right)$ in these formulae.
 5:
k – int64int32nag_int scalar
k$k$, the index of the required eigenvalue when the eigenvalues are ordered
Constraint:
k ≥ 0${\mathbf{k}}\ge 0$.
 6:
tol – double scalar
The tolerance parameter 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:
tol > 0.0${\mathbf{tol}}>0.0$.
 7:
elam – double scalar
An initial estimate of the eigenvalue λ̃$\stackrel{~}{\lambda}$.
 8:
delam – double scalar
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${\mathbf{elam}}+{\mathbf{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${\mathbf{delam}}=0.0$ on entry, it is given the default value of
0.25 × max (1.0,elam)$0.25\times \mathrm{max}\phantom{\rule{0.125em}{0ex}}(1.0,\left{\mathbf{elam}}\right)$.
 9:
monit – function handle or string containing name of mfile
monit is called by
nag_ode_sl2_reg_finite (d02ka) at the end of each iteration for
λ$\lambda $ and allows you to monitor the course of the computation by printing out the parameters (see
Section [Example] for an example).
If no monitoring is required, the dummy (sub)program nag_ode_sl2_reg_finite_dummy_monit (d02kay) may be used. (nag_ode_sl2_reg_finite_dummy_monit (d02kay) is included in the NAG Toolbox.)
monit(nit, iflag, elam, finfo)
Input Parameters
 1:
nit – int64int32nag_int scalar
15 minus the number of iterations used so far in the search for λ̃$\stackrel{~}{\lambda}$. (Up to 15$15$ iterations are permitted.)
 2:
iflag – int64int32nag_int scalar
Describes what phase the computation is in.
 iflag < 0${\mathbf{iflag}}<0$
 An error occurred in the computation at this iteration; an error exit from nag_ode_sl2_reg_finite (d02ka) will follow.
 iflag = 1${\mathbf{iflag}}=1$
 The function is trying to bracket the eigenvalue λ̃$\stackrel{~}{\lambda}$.
 iflag = 2${\mathbf{iflag}}=2$
 The function is converging to the eigenvalue λ̃$\stackrel{~}{\lambda}$ (having already bracketed it).
Normally, the iteration will terminate after a sequence of iterates with
iflag = 2${\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:
elam – double scalar
The current trial value of λ̃$\stackrel{~}{\lambda}$.
 4:
finfo(15$15$) – double array
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 ≥ 0${\mathbf{iflag}}\ge 0$), though the first few components may be of interest to you. In case of an error (
iflag < 0${\mathbf{iflag}}<0$) all the components of
finfo should be printed.
The contents of
finfo are as follows:
 finfo(1)${\mathbf{finfo}}\left(1\right)$
 The current value of the ‘missdistance’ or ‘residual’ function f(λ)$f\left(\lambda \right)$ on which the shooting method is based. f(λ̃) = 0$f\left(\stackrel{~}{\lambda}\right)=0$ in theory. This is set to zero if iflag < 0${\mathbf{iflag}}<0$.
 finfo(2)${\mathbf{finfo}}\left(2\right)$
 An estimate of the quantity ∂λ$\partial \lambda $ defined as follows. Consider the perturbation in the missdistance f(λ)$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(λ)$f\left(\lambda \right)$. Thus, at the zero of f(λ),∂λ$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$q$ is independent of λ$\lambda $. If this is the case, an error exit with ifail = 5${\mathbf{ifail}}={\mathbf{5}}$ should follow. finfo(2)${\mathbf{finfo}}\left(2\right)$ is set to zero if iflag < 0${\mathbf{iflag}}<0$.
 finfo(3)${\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$1.0$, and should almost never exceed 2.0$2.0$.
 finfo(4)${\mathbf{finfo}}\left(4\right)$
 The number of calls to coeffn at this iteration.
 finfo(5)${\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.
 finfo(6)${\mathbf{finfo}}\left(6\right)$
 The number of unsuccessful steps used by the internal integrator at this iteration.
 finfo(7)${\mathbf{finfo}}\left(7\right)$
 The number of successful steps at the maximum step size taken by the internal integrator at this iteration.
 finfo(8)${\mathbf{finfo}}\left(8\right)$
 Not used.
 finfo(9)${\mathbf{finfo}}\left(9\right)$ to finfo(15)${\mathbf{finfo}}\left(15\right)$
 Set to zero, unless iflag < 0${\mathbf{iflag}}<0$ in which case they hold the following values describing the point of failure:
 finfo(9)${\mathbf{finfo}}\left(9\right)$
 1 or 2$2$ depending on whether integration was in a forward or backward direction at the time of failure.
 finfo(10)${\mathbf{finfo}}\left(10\right)$
 The value of the independent variable, x$x$, the point at which the error occurred.
 finfo(11)${\mathbf{finfo}}\left(11\right)$, finfo(12)${\mathbf{finfo}}\left(12\right)$, finfo(13)${\mathbf{finfo}}\left(13\right)$
 The current values of the Pruefer dependent variables β$\beta $, φ$\varphi $ and ρ$\rho $ respectively. See Section [Description] in (d02ke) for a description of these variables.
 finfo(14)${\mathbf{finfo}}\left(14\right)$
 The localerror tolerance being used by the internal integrator at the point of failure.
 finfo(15)${\mathbf{finfo}}\left(15\right)$
 The last integration mesh point.
Optional Input Parameters
None.
Input Parameters Omitted from the MATLAB Interface
None.
Output Parameters
 1:
bcond(3$3$,2$2$) – double array
bcond(3,1)${\mathbf{bcond}}\left(3,1\right)$ and
bcond(3,2)${\mathbf{bcond}}\left(3,2\right)$ hold values
σ_{l},σ_{r}${\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,∞]$[0,\infty ]$ but instead
xr has been given a large value and the boundary conditions at infinity applied at
xr, then the sensitivity parameter
σ_{r}${\sigma}_{r}$ may be of interest. Refer to
Section [Examples of Boundary Conditions at Singular Points] in
(d02kd), for the actual meaning of
σ_{r}${\sigma}_{r}$ and
σ_{l}${\sigma}_{l}$.
 2:
elam – double scalar
The final computed estimate, whether or not an error occurred.
 3:
delam – double scalar
If
ifail = 0${\mathbf{ifail}}={\mathbf{0}}$,
delam holds an estimate of the absolute error in the computed eigenvalue, that is
λ̃ − elam ≃ delam$\stackrel{~}{\lambda}{\mathbf{elam}}\simeq {\mathbf{delam}}$, where
λ̃$\stackrel{~}{\lambda}$ is the true eigenvalue.
If
ifail ≠ 0${\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 [Error Indicators and Warnings] for further details.
 4:
ifail – int64int32nag_int scalar
ifail = 0${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see
[Error Indicators and Warnings]).
Error Indicators and Warnings
Errors or warnings detected by the function:
Cases prefixed with W are classified as warnings and
do not generate an error of type NAG:error_n. See nag_issue_warnings.
 ifail = 1${\mathbf{ifail}}=1$
On entry,  k < 0${\mathbf{k}}<0$, 
or  tol ≤ 0.0${\mathbf{tol}}\le 0.0$. 
 ifail = 2${\mathbf{ifail}}=2$
On entry,  a_{1} = p(a)a_{2} = 0${a}_{1}=p\left(a\right){a}_{2}=0$, 
or  b_{1} = p(b)b_{2} = 0${b}_{1}=p\left(b\right){b}_{2}=0$, 
(the array
bcond has been set up incorrectly).
 ifail = 3${\mathbf{ifail}}=3$

At some point between
xl and
xr the value of
p(x)$p\left(x\right)$ computed by
coeffn became zero or changed sign. See the last call of
monit for details.
 ifail = 4${\mathbf{ifail}}=4$
After 15$15$ iterations the eigenvalue had not been found to the required accuracy.
 ifail = 5${\mathbf{ifail}}=5$
The ‘bracketing’ phase (with
iflag of the
monit equal to
1$1$) failed to bracket the eigenvalue within ten iterations. This is caused by an error in formulating the problem (for example,
q$q$ is independent of
λ$\lambda $), or by very poor initial estimates of
elam and
delam.
On exit,
elam and
elam + delam${\mathbf{elam}}+{\mathbf{delam}}$ give the end points of the interval within which no eigenvalue was located by the function.
 ifail = 6${\mathbf{ifail}}=6$

To obtain the desired accuracy the local error tolerance was set so small at the start of some subinterval that the differential equation solver could not choose an initial step size large enough to make significant progress. See the last call of
monit for diagnostics.
 ifail = 7${\mathbf{ifail}}=7$
At some point 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
ifail = 6${\mathbf{ifail}}={\mathbf{6}}$). This could be due to pathological behaviour of
p(x)$p\left(x\right)$ and
q(x ; λ)$q(x;\lambda )$ 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.
 W ifail = 8${\mathbf{ifail}}=8$
tol is too small for the problem being solved and the
machine precision being used. The local value of
elam should be a very good approximation to the eigenvalue
λ̃$\stackrel{~}{\lambda}$.
 ifail = 9${\mathbf{ifail}}=9$
nag_roots_contfn_brent_rcomm (c05az), called by
nag_ode_sl2_reg_finite (d02ka), has terminated with the error exit corresponding to a pole of the matching function. This error exit should not occur, but if it does, try solving the problem again with a smaller value for
tol.
Note: error exits with
ifail = 2${\mathbf{ifail}}={\mathbf{2}}$,
3${\mathbf{3}}$,
6${\mathbf{6}}$,
7${\mathbf{7}}$ or
9${\mathbf{9}}$ are caused by the inability to set up or solve the differential equation at some iteration and will be immediately preceded by a call of
monit giving diagnostic information.
 ifail = 10${\mathbf{ifail}}=10$
 ifail = 11${\mathbf{ifail}}=11$
 ifail = 12${\mathbf{ifail}}=12$

A serious error has occurred in an internal call to an interpolation function. Check all (sub)program calls and array dimensions. Seek expert help.
Accuracy
The absolute accuracy of the computed eigenvalue is usually within a mixed absolute/relative bound defined by
tol (as defined above).
Further Comments
The time taken by
nag_ode_sl2_reg_finite (d02ka) 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$16$. To make the most economical use of the function, one should try to obtain good initial values for
elam and
delam.
See
Section [Further Comments] in
(d02kd) for a discussion of the technique used.
Example
Open in the MATLAB editor:
nag_ode_sl2_reg_finite_example
function nag_ode_sl2_reg_finite_example
xl = 0;
xr = 3.141592653589793;
bcond = [1, 1;
0, 0;
0, 0.04564094560555453];
k = int64(4);
tol = 1e05;
elam = 15;
delam = 4;
[bcondOut, elamOut, delamOut, ifail] = ...
nag_ode_sl2_reg_finite(xl, xr, @coeffn, bcond, k, tol, elam, delam, @monit)
function [p, q, dqdl] = coeffn(x, elam, jint)
p = 1;
dqdl = 1;
q = elam  10*cos(2.0*x);
function monit(nit, iflag, elam, finfo)
if (nit == 14)
fprintf('\nOutput from Monit\n');
end
fprintf('%2d %d %6.3f %+6.3f %+6.3g %+6.3f %+6.3f\n', ...
nit, iflag, elam, finfo(1), finfo(2), finfo(3), finfo(4));
Output from Monit
14 1 15.000 0.322 0.000108 +1.000 +206.000
13 1 15.000 0.322 5.67e05 +2.000 +234.000
12 1 19.000 +0.257 6.69e05 +1.000 +226.000
11 2 17.225 +0.018 6.75e05 +1.000 +226.000
10 2 17.097 +0.000 6.43e05 +1.000 +226.000
9 2 17.097 0.000 6.41e05 +1.000 +226.000
8 2 17.097 0.000 6.41e05 +1.000 +226.000
bcondOut =
1.0000 1.0000
0 0
0.9064 0.9064
elamOut =
17.0966
delamOut =
1.4960e04
ifail =
0
Open in the MATLAB editor:
d02ka_example
function d02ka_example
xl = 0;
xr = 3.141592653589793;
bcond = [1, 1;
0, 0;
0, 0.04564094560555453];
k = int64(4);
tol = 1e05;
elam = 15;
delam = 4;
[bcondOut, elamOut, delamOut, ifail] = ...
d02ka(xl, xr, @coeffn, bcond, k, tol, elam, delam, @monit)
function [p, q, dqdl] = coeffn(x, elam, jint)
p = 1;
dqdl = 1;
q = elam  10*cos(2.0*x);
function monit(nit, iflag, elam, finfo)
if (nit == 14)
fprintf('\nOutput from Monit\n');
end
fprintf('%2d %d %6.3f %+6.3f %+6.3g %+6.3f %+6.3f\n', ...
nit, iflag, elam, finfo(1), finfo(2), finfo(3), finfo(4));
Output from Monit
14 1 15.000 0.322 0.000108 +1.000 +206.000
13 1 15.000 0.322 5.67e05 +2.000 +234.000
12 1 19.000 +0.257 6.69e05 +1.000 +226.000
11 2 17.225 +0.018 6.75e05 +1.000 +226.000
10 2 17.097 +0.000 6.43e05 +1.000 +226.000
9 2 17.097 0.000 6.41e05 +1.000 +226.000
8 2 17.097 0.000 6.41e05 +1.000 +226.000
bcondOut =
1.0000 1.0000
0 0
0.9064 0.9064
elamOut =
17.0966
delamOut =
1.4960e04
ifail =
0
PDF version (NAG web site
, 64bit version, 64bit version)
© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013