NAG FL Interface
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 <nag.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) |
|
C++ Header Interface
#include <nag.h> extern "C" {
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) |
}
|
The routine may be called by the names d02agf or nagf_ode_bvp_shoot_genpar_intern.
3
Description
d02agf solves a two-point boundary value problem by determining the unknown parameters
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
correspond to the unknown boundary conditions.) It is assumed that we have a system of
first-order ordinary differential equations of the form
and that derivatives
are evaluated by
aux. The system, including the boundary conditions given by
bcaux, and the range of integration and matching point,
, given by
raaux, involves the
unknown parameters
which are to be determined, and for which initial estimates must be supplied. The number of unknown parameters
must not exceed the number of equations
. If
, we assume that
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
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 th element depends on the derivative of the th component of the solution, , with respect to the th parameter, . This matrix is calculated by a simple numerical differentiation technique which requires 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:
– Real (Kind=nag_wp)
Input/Output
-
On entry:
h must be set to an estimate of the step size,
, needed for integration.
On exit: the last step length used.
-
2:
– Real (Kind=nag_wp) array
Input
-
On entry:
must be set to a small quantity to control the
th solution component. The element
is used:
-
(i)in the bound on the local error in the th component of the solution during integration,
-
(ii)in the convergence test on the th component of the solution at the matching point in the Newton iteration.
The elements should not be chosen too small. They should usually be several orders of magnitude larger than machine precision.
-
3:
– Real (Kind=nag_wp) array
Input
-
On entry:
must be set to a small quantity to control the
th parameter component. The element
is used:
-
(i)in the convergence test on the th parameter in the Newton iteration,
-
(ii)in perturbing the th parameter when approximating the derivatives of the components of the solution with respect to the th parameter, for use in the Newton iteration.
The elements should not be chosen too small. They should usually be several orders of magnitude larger than machine precision.
-
4:
– Real (Kind=nag_wp) array
Input/Output
-
On entry: must be set to an estimate for the th parameter, , for .
On exit: the corrected value for the th parameter, unless an error has occurred, when it contains the last calculated value of the parameter (possibly perturbed by if the error occurred when calculating the approximate derivatives).
-
5:
– Real (Kind=nag_wp) array
Output
-
On exit: the solution when
(see
m1).
If
, the elements of
c are not used.
-
6:
– Integer
Input
-
On entry: , the total number of differential equations.
-
7:
– Integer
Input
-
On entry:
, the number of parameters.
If
, the last
differential equations (in
aux) are driving equations (see
Section 3).
Constraint:
.
-
8:
– Integer
Input
-
On entry: determines whether or not the final solution is computed as well as the parameter values.
- The final solution is not calculated;
- The final values of the solution at interval (length of range)/ are calculated and stored sequentially in the array c starting with the values of evaluated at the first end point (see raaux) stored in .
-
9:
– Subroutine, supplied by the user.
External Procedure
-
aux must evaluate the functions
(i.e., the derivatives
) for given values of its arguments,
,
The specification of
aux is:
Fortran Interface
Real (Kind=nag_wp), Intent (In) |
:: |
y(*), x, param(*) |
Real (Kind=nag_wp), Intent (Out) |
:: |
f(*) |
|
C Header Interface
void |
aux_ (double f[], const double y[], const double *x, const double param[]) |
|
C++ Header Interface
#include <nag.h> extern "C" {
void |
aux_ (double f[], const double y[], const double &x, const double param[]) |
}
|
In the description of the arguments of
d02agf below,
and
denote the numerical values of
n and
n1 in the call of
d02agf.
-
1:
– Real (Kind=nag_wp) array
Output
-
On exit: the value of
, for .
-
2:
– Real (Kind=nag_wp) array
Input
-
On entry: , for , the value of the argument.
-
3:
– Real (Kind=nag_wp)
Input
-
On entry: , the value of the argument.
-
4:
– Real (Kind=nag_wp) array
Input
-
On entry: , for , 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:
– Subroutine, supplied by the user.
External Procedure
-
bcaux must evaluate the values of
at the end points of the range given the values of
.
The specification of
bcaux is:
Fortran Interface
Real (Kind=nag_wp), Intent (In) |
:: |
param(*) |
Real (Kind=nag_wp), Intent (Out) |
:: |
g0(*), g1(*) |
|
C Header Interface
void |
bcaux_ (double g0[], double g1[], const double param[]) |
|
C++ Header Interface
#include <nag.h> extern "C" {
void |
bcaux_ (double g0[], double g1[], const double param[]) |
}
|
In the description of the arguments of
d02agf below,
and
denote the numerical values of
n and
n1 in the call of
d02agf.
-
1:
– Real (Kind=nag_wp) array
Output
-
On exit: the values
, for
, at the boundary point
(see
raaux).
-
2:
– Real (Kind=nag_wp) array
Output
-
On exit: the values
, for
, at the boundary point
(see
raaux).
-
3:
– Real (Kind=nag_wp) array
Input
-
On entry: , for , 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:
– Subroutine, supplied by the user.
External Procedure
-
raaux must evaluate the end points,
and
, of the range and the matching point,
, given the values
.
The specification of
raaux is:
Fortran Interface
Real (Kind=nag_wp), Intent (In) |
:: |
param(*) |
Real (Kind=nag_wp), Intent (Out) |
:: |
x0, x1, r |
|
C Header Interface
void |
raaux_ (double *x0, double *x1, double *r, const double param[]) |
|
C++ Header Interface
#include <nag.h> extern "C" {
void |
raaux_ (double &x0, double &x1, double &r, const double param[]) |
}
|
In the description of the arguments of
d02agf below,
denotes the numerical value of
n1 in the call of
d02agf.
-
1:
– Real (Kind=nag_wp)
Output
-
On exit: must contain the left-hand end of the range, .
-
2:
– Real (Kind=nag_wp)
Output
-
On exit: must contain the right-hand end of the range .
-
3:
– Real (Kind=nag_wp)
Output
-
On exit: must contain the matching point, .
-
4:
– Real (Kind=nag_wp) array
Input
-
On entry: , for , 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:
– 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
, for
, their errors,
, and the sum of squares of the errors at the matching point,
.
The specification of
prsol is:
Fortran Interface
Integer, Intent (In) |
:: |
n1 |
Real (Kind=nag_wp), Intent (In) |
:: |
param(n1), res, err(n1) |
|
C Header Interface
void |
prsol_ (const double param[], const double *res, const Integer *n1, const double err[]) |
|
C++ Header Interface
#include <nag.h> extern "C" {
void |
prsol_ (const double param[], const double &res, const Integer &n1, const double err[]) |
}
|
-
1:
– Real (Kind=nag_wp) array
Input
-
On entry: , for , the current value of the parameters.
-
2:
– Real (Kind=nag_wp)
Input
-
On entry: the sum of squares of the errors in the arguments, .
-
3:
– Integer
Input
-
On entry: , the number of parameters.
-
4:
– Real (Kind=nag_wp) array
Input
-
On entry: the errors in the parameters,
, for .
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:
– Real (Kind=nag_wp) array
Workspace
-
14:
– Real (Kind=nag_wp) array
Input
-
15:
– Real (Kind=nag_wp) array
Workspace
-
16:
– Real (Kind=nag_wp) array
Workspace
-
17:
– Real (Kind=nag_wp) array
Workspace
-
-
18:
– Integer
Input/Output
-
On entry:
ifail must be set to
,
or
to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of means that an error message is printed while a value of means that it is not.
If halting is not appropriate, the value
or
is recommended. If message printing is undesirable, then the value
is recommended. Otherwise, the value
is recommended.
When the value or is used it is essential to test the value of ifail on exit.
On exit:
unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
or
, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
Note: a further discussion of these errors and the steps which might be taken to correct them is given in
Section 9.
-
On entry, and .
Constraint: .
-
No further progress can be made when stepping to obtain a Jacobian update for the current parameter values. Step length .
-
Currently the matching point does not lie in range .
If , or depend on the parameters then this may occur when care is not taken to avoid it.
, and .
-
No further progress can be made when stepping to a solution corresponding to the current parameter values.
Step length .
The step length for integration
h has halved more than
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
. If, on failure,
h has the sign of
then failure has occurred whilst integrating from
to
, otherwise it has occurred whilst integrating from
to
.
-
The Jacobian for parameter corrections is singular.
-
The Newton method failed to converge while updating parameter values.
-
The Newton method has not converged after iterations while updating parameter values.
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 7 in the Introduction to the NAG Library FL Interface for further information.
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library FL Interface for further information.
Dynamic memory allocation failed.
See
Section 9 in the Introduction to the NAG Library FL Interface for further information.
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.
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 or ). The value of should be adjusted to avoid such difficulties.
If the matching point
is at one of the end points
or
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
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
always occurs in expressions of the form
, and
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.
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
or
) 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
and
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
) occurs because the mathematical problem has been posed incorrectly. The case
usually occurs because
or
has been poorly estimated, so these values should be checked first. If
is monitored, the solution
is sensitive to perturbations in the parameters
. Reduce the size of one or more values
to reduce the perturbations. Since only one value
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
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
. If it seems that too much computing time is required and, in particular, if the values
(available on each call of
prsol) are much larger than the expected values of the solution at the matching point
, 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
.
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 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 or 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
on the range
, with boundary conditions
and
.
We cannot use the differential equation at
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
is one of the parameters to be determined. We choose the range as
and setting
, we can determine all the boundary conditions. We take the matching point to be
, the end of the range, and so a good initial guess for
is not necessary. We write
,
, and estimate
,
.
Example 2 (EX2)
This example finds the gravitational constant
and the range
over which a projectile must be fired to hit the target with a given velocity. The differential equations are
on the range
with boundary conditions
We write
,
,
, and we take the matching point
. We estimate
,
and
(though this estimate is not important).
10.1
Program Text
10.2
Program Data
10.3
Program Results