NAG Library Routine Document
D02HBF
1 Purpose
D02HBF solves a two-point boundary value problem for a system of ordinary differential equations, using initial value techniques and Newton iteration; it generalizes subroutine
D02HAF to include the case where parameters other than boundary values are to be determined.
2 Specification
| SUBROUTINE D02HBF ( | P, N1, PE, E, N, SOLN, M1, FCN, BC, RANGE, W, SDW, IFAIL) |
| INTEGER | N1, N, M1, SDW, IFAIL |
| double precision | P(N1), PE(N1), E(N), SOLN(N,M1), W(N,SDW) |
| EXTERNAL | FCN, BC, RANGE |
3 Description
D02HBF solves a two-point boundary value problem by determining the unknown parameters
p1,p2,…,pn1 of the problem. These parameters may be, but need not be, boundary values; they may include eigenvalue parameters in the coefficients of the differential equations, length of the range of integration, etc. The notation and methods used are similar to those of
D02HAF and you are advised to study this first. (The parameters
p1,p2,…,pn1 correspond precisely to the unknown boundary conditions in
D02HAF.) It is assumed that we have a system of
n first-order ordinary differential equations of the form:
and that the derivatives
fi are evaluated by
FCN. The system, including the boundary conditions given by
BC and the range of integration given by
RANGE, involves the
n1 unknown parameters
p1,p2,…,pn1 which are to be determined, and for which initial estimates must be supplied. The number of unknown parameters
n1 must not exceed the number of equations
n. If
n1<n, we assume that
n-n1 equations of the system are not involved in the matching process. These are usually referred to as ‘driving equations’; they are independent of the parameters and of the solutions of the other
n1 equations. In numbering the equations for
FCN, the driving equations must be put
first.
The estimated values of the parameters are corrected by a form of Newton iteration. The Newton correction on each iteration is calculated using a Jacobian matrix whose i,jth element depends on the derivative of the ith component of the solution, yi, with respect to the jth parameter, pj. This matrix is calculated by a simple numerical differentiation technique which requires n1 evaluations of the differential system.
If the parameter
IFAIL is set appropriately, the routine automatically prints messages to inform you of the flow of the calculation. These messages are discussed in detail in
Section 8.
D02HBF is a simplified version of
D02SAF which is described in detail in
Gladwell (1979).
4 References
Gladwell I (1979) The development of the boundary value codes in the ordinary differential equations chapter of the NAG Library
Codes for Boundary Value Problems in Ordinary Differential Equations. Lecture Notes in Computer Science (eds B Childs, M Scott, J W Daniel, E Denman and P Nelson)
76 Springer–Verlag
5 Parameters
You are strongly recommended to read
Sections 3 and
8 in conjunction with this section.
- 1: P(N1) – double precision arrayInput/Output
-
On entry: an estimate for the ith parameter, pi, for i=1,2,…,n1.
On exit: the corrected value for the ith parameter, unless an error has occurred, when it contains the last calculated value of the parameter.
- 2: N1 – INTEGERInput
-
On entry:
n1, the number of parameters.
Constraint:
1≤N1≤N.
- 3: PE(N1) – double precision arrayInput
-
On entry: the elements of
PE must be given small positive values. The element
PEi is used
| (i) |
in the convergence test on the ith parameter in the Newton iteration, and |
| (ii) |
in perturbing the ith parameter when approximating the derivatives of the components of the solution with respect to this parameter for use in the Newton iteration. |
The elements PEi should not be chosen too small. They should usually be several orders of magnitude larger than machine precision.
Constraint:
PEi>0.0, for i=1,2,…,N1.
- 4: E(N) – double precision arrayInput
-
On entry: the elements of
E must be given positive values. The element
Ei is used in the bound on the local error in the
ith component of the solution
yi during integration.
The elements Ei should not be chosen too small. They should usually be several orders of magnitude larger than machine precision.
Constraint:
Ei>0.0, for i=1,2,…,N.
- 5: N – INTEGERInput
-
On entry:
n, the total number of differential equations.
Constraint:
N≥2.
- 6: SOLN(N,M1) – double precision arrayOutput
-
On exit: the solution when M1>1.
- 7: M1 – INTEGERInput
-
On entry:
a value which controls exit values.
- M1=1
- The final solution is not calculated.
- M1>1
- The final values of the solution at interval (length of range)/M1-1 are calculated and stored sequentially in the array SOLN starting with the values of the solutions evaluated at the first end point (see RANGE) stored in the first column of SOLN.
Constraint:
M1≥1.
- 8: FCN – SUBROUTINE, supplied by the user.External Procedure
-
FCN must evaluate the functions
fi (i.e., the derivatives
yi′), for
i=1,2,…,n, at a general point
x.
The specification of
FCN is:
| SUBROUTINE FCN ( | X, Y, F, P) |
| double precision | X, Y(n), F(n), P(n1) |
where
n and
n1 are the numerical values of
N and
N1 in the call of D02HBF.
- 1: X – double precisionInput
-
On entry: x, the value of the argument.
- 2: Y(n) – double precision arrayInput
On entry: yi, the value of the argument, for i=1,2,…,n.
- 3: F(n) – double precision arrayOutput
-
On exit: the value of
fi, for
i=1,2,…,n. The
fi may depend upon the parameters
pj, for
j=1,2,…,n1. If there are any driving equations (see
Section 3) then these must be numbered first in the ordering of the components of
F in
FCN.
- 4: P(n1) – double precision arrayInput
-
On entry: the current estimate of the parameter pi, for i=1,2,…,n1.
FCN must be declared as EXTERNAL in the (sub)program from which D02HBF is called. Parameters denoted as
Input must
not be changed by this procedure.
- 9: BC – SUBROUTINE, supplied by the user.External Procedure
-
BC must place in
G1 and
G2 the boundary conditions at
a and
b respectively (see
RANGE).
The specification of
BC is:
| SUBROUTINE BC ( | G1, G2, P) |
| double precision | G1(n), G2(n), P(n1) |
where
n and
n1 are the numerical values of
N and
N1 in the call of D02HBF.
- 1: G1(n) – double precision arrayOutput
-
On exit: the value of yia, (where this may be a known value or a function of the parameters pj, for j=1,2,…,n1 and i=1,2,…,n).
- 2: G2(n) – double precision arrayOutput
-
On exit: the value of
yib, for
i=1,2,…,n, (where these may be known values or functions of the parameters
pj, for
j=1,2,…,n1). If
n>n1, so that there are some driving equations, then the first
n-n1 values of
G2 need not be set since they are never used.
- 3: P(n1) – double precision arrayInput
-
On entry: an estimate of the parameter pi, for i=1,2,…,n1.
BC must be declared as EXTERNAL in the (sub)program from which D02HBF is called. Parameters denoted as
Input must
not be changed by this procedure.
- 10: RANGE – SUBROUTINE, supplied by the user.External Procedure
-
RANGE must evaluate the boundary points
a and
b, each of which may depend on the parameters
p1,p2,…,pn1. The integrations in the shooting method are always from
a to
b.
The specification of
RANGE is:
| SUBROUTINE RANGE ( | A, B, P) |
| double precision | A, B, P(n1) |
where
n1 is the actual value of
N1 in the call of D02HBF.
- 1: A – double precisionOutput
-
On exit: a, one of the boundary points.
- 2: B – double precisionOutput
-
On exit: the second boundary point,
b. Note that
B>A forces the direction of integration to be that of increasing
x. If
A and
B are interchanged the direction of integration is reversed.
- 3: P(n1) – double precision arrayInput
On entry: the current estimate of the ith parameter, pi, for i=1,2,…,n1.
RANGE must be declared as EXTERNAL in the (sub)program from which D02HBF is called. Parameters denoted as
Input must
not be changed by this procedure.
- 11: W(N,SDW) – double precision arrayOutput
-
Used mainly for workspace.
On exit: with
IFAIL=2,
3,
4 or
5 (see
Section 6),
Wi1, for
i=1,2,…,n, contains the solution at the point
x when the error occurred.
W12 contains
x.
- 12: SDW – INTEGERInput
-
On entry: the second dimension of the array
W as declared in the (sub)program from which D02HBF is called.
Constraint:
SDW≥3N+14+max11,N.
- 13: IFAIL – INTEGERInput/Output
-
For this routine, the normal use of
IFAIL is extended to control the printing of error and warning messages as well as specifying hard or soft failure (see
Section 3.3 in the Essential Introduction).
On entry:
IFAIL must be set to a value with the decimal expansion
cba, where each of the decimal digits
c,
b and
a must have a value of
0 or
1.
| a=0 |
specifies hard failure, otherwise soft failure; |
| b=0 |
suppresses error messages, otherwise error messages will be printed (see Section 6); |
| c=0 |
suppresses warning messages, otherwise warning messages will be printed (see Section 6). |
The recommended value for inexperienced users is 110 (i.e., hard failure with all messages printed).
On exit:
IFAIL=0 unless the routine detects an error (see
Section 6).
6 Error Indicators and Warnings
If on entry
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:
- IFAIL=1
-
One or more of the parameters
N,
N1,
M1,
SDW,
E or
PE is incorrectly set.
- IFAIL=2
-
The step length for the integration became too short whilst calculating the residual (see
Section 8).
- IFAIL=3
-
No initial step length could be chosen for the integration whilst calculating the residual.
Note: IFAIL=2 or
3 can occur due to choosing too small a value for
E or due to choosing the wrong direction of integration. Try varying
E and interchanging
a and
b. These error exits can also occur for very poor initial choices of the parameters in the array
P and, in extreme cases, because D02HBF cannot be used to solve the problem posed.
- IFAIL=4
-
As for IFAIL=2 but the error occurred when calculating the Jacobian.
- IFAIL=5
-
As for IFAIL=3 but the error occurred when calculating the Jacobian.
- IFAIL=6
-
The calculated Jacobian has an insignificant column. This can occur because a parameter pi is incorrectly entered when posing the problem.
Note: IFAIL=4,
5 or
6 usually indicate a badly scaled problem. You may vary the size of
PE. Otherwise the use of the more general
D02SAF which affords more control over the calculations is advised.
- IFAIL=7
-
The linear algebra routine used (
F08KBF (DGESVD)) has failed. This error exit should not occur and can be avoided by changing the initial estimates
pi.
- IFAIL=8
-
The Newton iteration has failed to converge. This can indicate a poor initial choice of parameters pi or a very difficult problem. Consider varying the elements PEi if the residuals are small in the monitoring output. If the residuals are large, try varying the initial parameters pi.
- IFAIL=9
- IFAIL=10
- IFAIL=11
- IFAIL=12
- IFAIL=13
-
Indicates that a serious error has occurred in an internal call. Check all array subscripts and subroutine parameter lists in the call to D02HBF. Seek expert help.
7 Accuracy
If the process converges, the accuracy to which the unknown parameters are determined is usually close to that specified by you; the solution, if requested, may be determined to a required accuracy by varying
E.
8 Further Comments
The time taken by D02HBF depends on the complexity of the system, and on the number of iterations required. In practice, integration of the differential equations is by far the most costly process involved.
Wherever they occur in the routine, the error parameters contained in the arrays
E and
PE are used in ‘mixed’ form; that is
Ei always occurs in expressions of the form
and
PEi always occurs in expressions of the form
Though not ideal for every application, it is expected that this mixture of absolute and relative error testing will be adequate for most purposes.
You may determine a suitable direction of integration
a to
b and suitable values for
Ei by integrations with
D02PCF. The best direction of integration is usually the direction of decreasing solutions. You are strongly recommended to set
IFAIL to obtain self-explanatory error messages, and also monitoring information about the course of the computation. You may select the channel numbers on which this output is to appear by calls of
X04AAF (for error messages) or
X04ABF (for monitoring information) – see
Section 9 for an example. Otherwise the default channel numbers will be used, as specified in the
Users' Note. The monitoring information produced at each iteration includes the current parameter values, the residuals and two norms: a basic norm and a current norm. At each iteration the aim is to find parameter values which make the current norm less than the basic norm. Both these norms should tend to zero as should the residuals. (They would all be zero if the exact parameters were used as input.) For more details, in particular about the other monitoring information printed, you are advised to consult the specification of
D02SAF, and especially the description of the parameter
MONIT there.
The computing time for integrating the differential equations can sometimes depend critically on the quality of the initial estimates for the parameters
pi. If it seems that too much computing time is required and, in particular, if the values of the residuals printed by the monitoring routine are much larger than the expected values of the solution at
b, then the coding of
FCN,
BC and
RANGE should be checked for errors. If no errors can be found, an independent attempt should be made to improve the initial estimates for
pi.
The subroutine can be used to solve a very wide range of problems, for example:
| (a) |
eigenvalue problems, including problems where the eigenvalue occurs in the boundary conditions; |
| (b) |
problems where the differential equations depend on some parameters which are to be determined so as to satisfy certain boundary conditions (see Example 2 in Section 9); |
| (c) |
problems where one of the end points of the range of integration is to be determined as the point where a variable yi takes a particular value (see Example 2 in Section 9); |
| (d) |
singular problems and problems on infinite ranges of integration where the values of the solution at a or b or both are determined by a power series or an asymptotic expansion (or a more complicated expression) and where some of the coefficients in the expression are to be determined (see Example 1 in Section 9); and |
| (e) |
differential equations with certain terms defined by other independent (driving) differential equations. |
9 Example
For this routine two examples are presented. There is a single example program for D02HBF, with a main program and the code to solve the two example problems given in Example 1 (EX1) and Example 2 (EX2).
Example 1 (EX1)
This example finds the solution of the differential equation
on the range
0≤x≤16, with boundary conditions
y0=0.1 and
y16=1/6. We cannot use the differential equation at
x=0 because it is singular, so we take a truncated power series expansion
near the origin where
p1 is one of the parameters to be determined. We choose the interval as
0.1,16 and setting
p2=y′16, we can determine all the boundary conditions. We take
X1=16. We write
y=Y1,
y′=Y2, and estimate
PARAM1=0.2,
PARAM2=0.0. Note the call to
X04ABF before the call to D02HBF.
Example 2 (EX2)
This example finds the gravitational constant p1 and the range p2 over which a projectile must be fired to hit the target with a given velocity.
The differential equations are
on the range
0<x<p2, with boundary conditions
We write
y=Y1,
v=Y2,
ϕ=Y3. We estimate
p1=PARAM1=32,
p2=PARAM2=6000 and
p3=PARAM3=0.54 (though this last estimate is not important).
9.1 Program Text
Program Text (d02hbfe.f)
9.2 Program Data
None.
9.3 Program Results
Program Results (d02hbfe.r)
