NAG Library Routine Document
D02AGF
1 Purpose
D02AGF solves a two-point boundary value problem for a system of ordinary differential equations, using initial value techniques and Newton iteration; it generalizes
D02HAF to include the case where parameters other than boundary values are to be determined.
2 Specification
| SUBROUTINE D02AGF ( | H, E, PARERR, PARAM, C, N, N1, M1, AUX, BCAUX, RAAUX, PRSOL, MAT, COPY, WSPACE, WSPAC1, WSPAC2, IFAIL) |
| INTEGER | N, N1, M1, IFAIL |
| double precision | H, E(N), PARERR(N1), PARAM(N1), C(M1,N), MAT(N1,N1), COPY(1,1), WSPACE(N,9), WSPAC1(N), WSPAC2(N) |
| EXTERNAL | AUX, BCAUX, RAAUX, PRSOL |
3 Description
D02AGF 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 (as they are in
D02HAF); 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. (There the parameters
p1,p2,…,pn1 correspond to the unknown boundary conditions.) It is assumed that we have a system of
n first-order ordinary differential equations of the form
and that derivatives
fi are evaluated by
AUX. The system, including the boundary conditions given by
BCAUX, and the range of integration and matching point,
r, given by
RAAUX, 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
AUX, the driving equations must be put last.
The estimated values of the parameters are corrected by a form of Newton iteration. The Newton correction on each iteration is calculated using a 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.
4 References
None.
5 Parameters
You are strongly recommended to read
Sections 3 and
8 in conjunction with this section.
- 1: H – double precisionInput/Output
-
On entry:
H must be set to an estimate of the step size,
h, needed for integration.
On exit: the last step length used.
- 2: E(N) – double precision arrayInput
-
On entry:
Ei must be set to a small quantity to control the
ith solution component. The element
Ei is used:
| (i) |
in the bound on the local error in the ith component of the solution yi during integration, |
| (ii) |
in the convergence test on the ith component of the solution yi at the matching point in the Newton iteration. |
The elements Ei should not be chosen too small. They should usually be several orders of magnitude larger than machine precision.
- 3: PARERR(N1) – double precision arrayInput
-
On entry:
PARERRi must be set to a small quantity to control the
ith parameter component. The element
PARERRi is used:
| (i) |
in the convergence test on the ith parameter in the Newton iteration, |
| (ii) |
in perturbing the ith parameter when approximating the derivatives of the components of the solution with respect to the ith parameter, for use in the Newton iteration. |
The elements PARERRi should not be chosen too small. They should usually be several orders of magnitude larger than machine precision.
- 4: PARAM(N1) – double precision arrayInput/Output
-
On entry: PARAMi must be set to 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 (possibly perturbed by PARERRi×1+PARAMi if the error occurred when calculating the approximate derivatives).
- 5: C(M1,N) – double precision arrayOutput
-
On exit: the solution when
M1>1 (see
M1).
If
M1=1, the elements of
C are not used.
- 6: N – INTEGERInput
-
On entry:
n, the total number of differential equations.
- 7: N1 – INTEGERInput
-
On entry:
n1, the number of parameters.
If
N1<N, the last
N-N1 differential equations (in
AUX) are driving equations (see
Section 3).
Constraint:
N1≤N.
- 8: M1 – INTEGERInput
-
On entry:
determines whether or not the final solution is computed as well as the parameter 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 C starting with the values of yi evaluated at the first end point (see RAAUX) stored in C1i.
- 9: AUX – SUBROUTINE, supplied by the user.External Procedure
-
AUX must evaluate the functions
fi (i.e., the derivatives
yi′) for given values of its arguments,
x,y1,…,yn,
p1,…,pn1.
The specification of
AUX is:
| SUBROUTINE AUX ( | F, Y, X, PARAM) |
| double precision | F(n), Y(n), X, PARAM(n1) |
where
n and
n1 are the numerical values of
N and
N1 in the call of D02AGF.
- 1: F(n) – double precision arrayOutput
On exit: the value of fi, for i=1,2,…,n.
- 2: Y(n) – double precision arrayInput
-
On entry: yi, the value of the argument, for i=1,2,…,n.
- 3: X – double precisionInput
-
On entry: x, the value of the argument.
- 4: PARAM(n1) – double precision arrayInput
-
On entry: pi, the value of the argument, for i=1,2,…,n1.
AUX must be declared as EXTERNAL in the (sub)program from which D02AGF is called. Parameters denoted as
Input must
not be changed by this procedure.
- 10: BCAUX – SUBROUTINE, supplied by the user.External Procedure
-
BCAUX must evaluate the values of
yi at the end points of the range given the values of
p1,…,pn1.
The specification of
BCAUX is:
| SUBROUTINE BCAUX ( | G0, G1, PARAM) |
| double precision | G0(n), G1(n), PARAM(n1) |
where
n and
n1 are the numerical values of
N and
N1 in the call of D02AGF.
- 1: G0(n) – double precision arrayOutput
-
On exit: the values
yi, for
i=1,2,…,n, at the boundary point
x0 (see
RAAUX).
- 2: G1(n) – double precision arrayOutput
-
On exit: the values
yi, for
i=1,2,…,n, at the boundary point
x1 (see
RAAUX).
- 3: PARAM(n1) – double precision arrayInput
-
On entry: pi, the value of the argument, for i=1,2,…,n.
BCAUX must be declared as EXTERNAL in the (sub)program from which D02AGF is called. Parameters denoted as
Input must
not be changed by this procedure.
- 11: RAAUX – SUBROUTINE, supplied by the user.External Procedure
-
RAAUX must evaluate the end points,
x0 and
x1, of the range and the matching point,
r, given the values
p1,p2,…,pn1.
The specification of
RAAUX is:
| SUBROUTINE RAAUX ( | X0, X1, R, PARAM) |
| double precision | X0, X1, R, PARAM(n1) |
where
n1 is the numerical value of
N1 in the call of D02AGF.
- 1: X0 – double precisionOutput
-
On exit: must contain the left-hand end of the range, x0.
- 2: X1 – double precisionOutput
-
On exit: must contain the right-hand end of the range x1.
- 3: R – double precisionOutput
-
On exit: must contain the matching point, r.
- 4: PARAM(n1) – double precision arrayInput
-
On entry: pi, the value of the argument, for i=1,2,…,n1.
RAAUX must be declared as EXTERNAL in the (sub)program from which D02AGF is called. Parameters denoted as
Input must
not be changed by this procedure.
- 12: PRSOL – SUBROUTINE, supplied by the user.External Procedure
-
PRSOL is called at each iteration of the Newton method and can be used to print the current values of the parameters
pi, for
i=1,2,…,n1, their errors,
ei, and the sum of squares of the errors at the matching point,
r.
The specification of
PRSOL is:
| SUBROUTINE PRSOL ( | PARAM, RES, N1, ERR) |
| INTEGER | N1 |
| double precision | PARAM(N1), RES, ERR(N1) |
- 1: PARAM(N1) – double precision arrayInput
-
On entry: pi, the current value of the parameters, for i=1,2,…,n1.
- 2: RES – double precisionInput
-
On entry: the sum of squares of the errors in the parameters, ∑i=1n1ei2.
- 3: N1 – INTEGERInput
-
On entry: n1, the number of parameters.
- 4: ERR(N1) – double precision arrayInput
-
On entry: the errors in the parameters, ei, for i=1,2,…,n1.
PRSOL must be declared as EXTERNAL in the (sub)program from which D02AGF is called. Parameters denoted as
Input must
not be changed by this procedure.
- 13: MAT(N1,N1) – double precision arrayWorkspace
- 14: COPY(1,1) – double precision arrayInput
- 15: WSPACE(N,9) – double precision arrayWorkspace
- 16: WSPAC1(N) – double precision arrayWorkspace
- 17: WSPAC2(N) – double precision arrayWorkspace
- 18: IFAIL – INTEGERInput/Output
-
On entry:
IFAIL must be set to
0,
-1 or 1. If you are unfamiliar with this parameter you should refer to
Section 3.3 in the Essential Introduction for details.
On exit:
IFAIL=0 unless the routine detects an error (see
Section 6).
For environments where it might be inappropriate to halt program execution when an error is detected, the value
-1 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 parameter, the recommended value is
0.
When the value -1 or 1 is used it is essential to test the value of IFAIL on exit.
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
-
This indicates that N1>N on entry, that is the number of parameters is greater than the number of differential equations.
- IFAIL=2
-
As for IFAIL=4 except that the integration failed while calculating the matrix for use in the Newton iteration.
- IFAIL=3
-
The current matching point
r does not lie between the current end points
x0 and
x1. If the values
x0,
x1 and
r depend on the parameters
pi, this may occur at any time in the Newton iteration if care is not taken to avoid it when coding
RAAUX.
- IFAIL=4
-
The step length for integration
H has halved more than
13 times (or too many steps were needed to reach the end of the range of integration) in attempting to control the local truncation error whilst integrating to obtain the solution corresponding to the current values
pi. If, on failure,
H has the sign of
r-x0 then failure has occurred whilst integrating from
x0 to
r, otherwise it has occurred whilst integrating from
x1 to
r.
- IFAIL=5
-
The matrix of the equations to be solved for corrections to the variable parameters in the Newton method is singular (as determined by
F03AFF).
- IFAIL=6
-
A satisfactory correction to the parameters was not obtained on the last Newton iteration employed. A Newton iteration is deemed to be unsatisfactory if the sum of the squares of the residuals (which can be printed using
PRSOL) has not been reduced after three iterations using a new Newton correction.
- IFAIL=7
-
Convergence has not been obtained after 12 satisfactory iterations of the Newton method.
A further discussion of these errors and the steps which might be taken to correct them is given in
Section 8.
7 Accuracy
If the process converges, the accuracy to which the unknown parameters are determined is usually close to that specified by you; and the solution, if requested, is usually determined to the accuracy specified.
8 Further Comments
The time taken by D02AGF 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.
There may be particular difficulty in integrating the differential equations in one direction (indicated by IFAIL=2 or 4). The value of r should be adjusted to avoid such difficulties.
If the matching point
r is at one of the end points
x0 or
x1 and some of the parameters are used
only to determine the boundary values at this point, then good initial estimates for these parameters are not required, since they are completely determined by the routine (for example, see
p2 in EX1 of
Section 9).
Wherever they occur in the procedure, the error parameters contained in the arrays
E and
PARERR are used in ‘mixed’ form; that is
Ei always occurs in expressions of the form
Ei×1+yi, and
PARERRi always occurs in expressions of the form
PARERRi×1+pi. Though not ideal for every application, it is expected that this mixture of absolute and relative error testing will be adequate for most purposes.
Note that
convergence
is
not
guaranteed. You are strongly advised to provide an output
PRSOL, as shown in EX1 of
Section 9, in order to monitor the progress of the iteration. Failure of the Newton iteration to converge (see
IFAIL=6 or
7) usually results from poor starting approximations to the parameters, though occasionally such failures occur because the elements of one or both of the arrays
PARERR or
E are too small. (It should be possible to distinguish these cases by studying the output from
PRSOL.) Poor starting approximations can also result in the failure described under
IFAIL=4 and
5 in
Section 6 (especially if these errors occur after some Newton iterations have been completed, that is, after two or more calls of
PRSOL). More frequently, a singular matrix in the Newton method (monitored as
IFAIL=5) occurs because the mathematical problem has been posed incorrectly. The case
IFAIL=4 usually occurs because
h or
r has been poorly estimated, so these values should be checked first. If
IFAIL=2 is monitored, the solution
y1,y2,…,yn is sensitive to perturbations in the parameters
pi. Reduce the size of one or more values
PARERRi to reduce the perturbations. Since only one value
pi is perturbed at any time when forming the matrix, the perturbation which is too large can be located by studying the final output from
PRSOL and the values of the parameters returned by D02AGF. If this change leads to other types of failure improve the initial values of
pi by other means.
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
ERRi (available on each call of
PRSOL) are much larger than the expected values of the solution at the matching point
r, then the coding of
AUX,
BCAUX and
RAAUX should be checked for errors. If no errors can be found, an independent attempt should be made to improve the initial estimates for
PARAMi.
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 EX1 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 EX2 in Section 9); |
| (d) |
singular problems and problems on infinite ranges of integration where the values of the solution at x0 or x1 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 EX1 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 D02AGF, 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 the truncated series expansion
near the origin (which is correct to the number of terms given in this case). Here
p1 is one of the parameters to be determined. We choose the range as
0.1,16 and setting
p2=y′16, we can determine all the boundary conditions. We take the matching point to be
16, the end of the range, and so a good initial guess for
p2 is not necessary. We write
y=Y1,
y′=Y2, and estimate
p1=PARAM1=0.2,
p2=PARAM2=0.0.
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, and we take the matching point
r=p2. We estimate
p1=PARAM1=32,
p2=PARAM2=6000 and
p3=PARAM3=0.54 (though this estimate is not important).
9.1 Program Text
Program Text (d02agfe.f)
9.2 Program Data
None.
9.3 Program Results
Program Results (d02agfe.r)
