NAG Library Routine Document

d02agf (bvp_shoot_genpar_intern)

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

Fortran Interface
Subroutine d02agf ( h, e, parerr, param, c, n, n1, m1, aux, bcaux, raaux, prsol, mat, copy, wspace, wspac1, wspac2, ifail)
Integer, Intent (In):: n, n1, m1
Integer, Intent (Inout):: ifail
Real (Kind=nag_wp), Intent (In):: e(n), parerr(n1), copy(1,1)
Real (Kind=nag_wp), Intent (Inout):: h, param(n1)
Real (Kind=nag_wp), Intent (Out):: c(m1,n), mat(n1,n1), wspace(n,9), wspac1(n), wspac2(n)
External:: aux, bcaux, raaux, prsol
C Header Interface
#include <nagmk26.h>
void  d02agf_ (double *h, const double e[], const double parerr[], double param[], double c[], const Integer *n, const Integer *n1, const Integer *m1,
void (NAG_CALL *aux)(double f[], const double y[], const double *x, const double param[]),
void (NAG_CALL *bcaux)(double g0[], double g1[], const double param[]),
void (NAG_CALL *raaux)(double *x0, double *x1, double *r, const double param[]),
void (NAG_CALL *prsol)(const double param[], const double *res, const Integer *n1, const double err[]),
double mat[], const double copy[], double wspace[], double wspac1[], double wspac2[], Integer *ifail)

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
dyi dx =fix,y1,y2,,yn,  i=1,2,,n,  
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
Arguments

You are strongly recommended to read Sections 3 and 9 in conjunction with this section.
1:     h – Real (Kind=nag_wp)Input/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:     en – Real (Kind=nag_wp) 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:     parerrn1 – Real (Kind=nag_wp) 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:     paramn1 – Real (Kind=nag_wp) 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:     cm1n – Real (Kind=nag_wp) 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: n1n.
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:
Fortran Interface
Subroutine aux ( f, y, x, param)
Real (Kind=nag_wp), Intent (In):: y(*), x, param(*)
Real (Kind=nag_wp), Intent (Out):: f(*)
C Header Interface
#include <nagmk26.h>
void  aux (double f[], const double y[], const double *x, const double param[])
In the description of the arguments of d02agf below, n and n1 denote the numerical values of n and n1 in the call of d02agf.
1:     f* – Real (Kind=nag_wp) arrayOutput
On exit: the value of fi, for i=1,2,,n.
2:     y* – Real (Kind=nag_wp) arrayInput
On entry: yi, for i=1,2,,n, the value of the argument.
3:     x – Real (Kind=nag_wp)Input
On entry: x, the value of the argument.
4:     param* – Real (Kind=nag_wp) arrayInput
On entry: pi, for i=1,2,,n1, the value of the parameters.
aux must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02agf is called. Arguments denoted as Input must not be changed by this procedure.
Note: aux should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02agf. If your code inadvertently does return any NaNs or infinities, d02agf is likely to produce unexpected results.
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:
Fortran Interface
Subroutine bcaux ( g0, g1, param)
Real (Kind=nag_wp), Intent (In):: param(*)
Real (Kind=nag_wp), Intent (Out):: g0(*), g1(*)
C Header Interface
#include <nagmk26.h>
void  bcaux (double g0[], double g1[], const double param[])
In the description of the arguments of d02agf below, n and n1 denote the numerical values of n and n1 in the call of d02agf.
1:     g0* – Real (Kind=nag_wp) arrayOutput
On exit: the values yi, for i=1,2,,n, at the boundary point x0 (see raaux).
2:     g1* – Real (Kind=nag_wp) arrayOutput
On exit: the values yi, for i=1,2,,n, at the boundary point x1 (see raaux).
3:     param* – Real (Kind=nag_wp) arrayInput
On entry: pi, for i=1,2,,n, the value of the parameters.
bcaux must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02agf is called. Arguments denoted as Input must not be changed by this procedure.
Note: bcaux should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02agf. If your code inadvertently does return any NaNs or infinities, d02agf is likely to produce unexpected results.
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:
Fortran Interface
Subroutine raaux ( x0, x1, r, param)
Real (Kind=nag_wp), Intent (In):: param(*)
Real (Kind=nag_wp), Intent (Out):: x0, x1, r
C Header Interface
#include <nagmk26.h>
void  raaux (double *x0, double *x1, double *r, const double param[])
In the description of the arguments of d02agf below, n1 denotes the numerical value of n1 in the call of d02agf.
1:     x0 – Real (Kind=nag_wp)Output
On exit: must contain the left-hand end of the range, x0.
2:     x1 – Real (Kind=nag_wp)Output
On exit: must contain the right-hand end of the range x1.
3:     r – Real (Kind=nag_wp)Output
On exit: must contain the matching point, r.
4:     param* – Real (Kind=nag_wp) arrayInput
On entry: pi, for i=1,2,,n1, the value of the parameters.
raaux must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02agf is called. Arguments denoted as Input must not be changed by this procedure.
Note: raaux should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02agf. If your code inadvertently does return any NaNs or infinities, d02agf is likely to produce unexpected results.
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:
Fortran Interface
Subroutine prsol ( param, res, n1, err)
Integer, Intent (In):: n1
Real (Kind=nag_wp), Intent (In):: param(n1), res, err(n1)
C Header Interface
#include <nagmk26.h>
void  prsol (const double param[], const double *res, const Integer *n1, const double err[])
1:     paramn1 – Real (Kind=nag_wp) arrayInput
On entry: pi, for i=1,2,,n1, the current value of the parameters.
2:     res – Real (Kind=nag_wp)Input
On entry: the sum of squares of the errors in the arguments, i=1n1ei2.
3:     n1 – IntegerInput
On entry: n1, the number of parameters.
4:     errn1 – Real (Kind=nag_wp) arrayInput
On entry: the errors in the parameters, ei, for i=1,2,,n1.
prsol must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02agf is called. Arguments denoted as Input must not be changed by this procedure.
13:   matn1n1 – Real (Kind=nag_wp) arrayWorkspace
14:   copy11 – Real (Kind=nag_wp) arrayInput
15:   wspacen9 – Real (Kind=nag_wp) arrayWorkspace
16:   wspac1n – Real (Kind=nag_wp) arrayWorkspace
17:   wspac2n – Real (Kind=nag_wp) arrayWorkspace
18:   ifail – IntegerInput/Output
On entry: ifail must be set to 0, -1 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 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 -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (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
On entry, n1=value and n=value.
Constraint: n1n.
ifail=2
No further progress can be made when stepping to obtain a Jacobian update for the current parameter values. Step length h=value.
ifail=3
Currently the matching point r does not lie in range x0,x1.
If x0, x1 or r depend on the parameters then this may occur when care is not taken to avoid it.
r=value, x0=value and x1=value.
ifail=4
No further progress can be made when stepping to a solution corresponding to the current parameter values.
Step length h=value.
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 Jacobian for parameter corrections is singular.
ifail=6
The Newton method failed to converge while updating parameter values.
ifail=7
The Newton method has not converged after 12 iterations while updating parameter values.
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.
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.
ifail=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.
A further discussion of these errors and the steps which might be taken to correct them is given in Section 9.

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
Parallelism and Performance

d02agf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
d02agf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9
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 10).
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 10, 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 10);
(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 10);
(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 10); and
(e) differential equations with certain terms defined by other independent (driving) differential equations.

10
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
y=y3-y 2x  
on the range 0x16, 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
yx=110+p1x10+x100  
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=y16, 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
y=tanϕ v= -p1sinϕ+0.00002v2 vcosϕ ϕ=-p1v2k  
on the range 0<x<p2 with boundary conditions
y=0, v=500, ϕ=0.5 at x=0 y=0, v=450, ϕ=p3 at x=p2.  
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).

10.1
Program Text

Program Text (d02agfe.f90)

10.2
Program Data

Program Data (d02agfe.d)

10.3
Program Results

Program Results (d02agfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 0.02 0.04 0.06 0.08 0.1 0.12 0.14 0.16 0.18 0 2 4 6 8 10 12 14 16 Solution and Derivative x Example Program 1 Parameterized Two-point Boundary-value Problem solution y(x) derivative y'(x) param(2) gnuplot_plot_1 gnuplot_plot_2
GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 100 200 300 400 500 600 700 800 900 0 1000 2000 3000 4000 5000 6000 −0.6 −0.4 −0.2 0 0.2 0.4 0.6 Height and Velocity Angle x Example Program 2 Find Gravitational Constant and Range given Projectile Terminal Velocity height velocity angle gnuplot_plot_1 gnuplot_plot_2 gnuplot_plot_3