# NAG FL Interfaced02hbf (bvp_​shoot_​genpar)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

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.

## 2Specification

Fortran Interface
 Subroutine d02hbf ( p, n1, pe, e, n, soln, m1, fcn, bc, w, sdw,
 Integer, Intent (In) :: n1, n, m1, sdw Integer, Intent (Inout) :: ifail Real (Kind=nag_wp), Intent (In) :: pe(n1), e(n) Real (Kind=nag_wp), Intent (Inout) :: p(n1) Real (Kind=nag_wp), Intent (Out) :: soln(n,m1), w(n,sdw) External :: fcn, bc, range
#include <nag.h>
 void d02hbf_ (double p[], const Integer *n1, const double pe[], const double e[], const Integer *n, double soln[], const Integer *m1, void (NAG_CALL *fcn)(const double *x, const double y[], double f[], const double p[]),void (NAG_CALL *bc)(double g1[], double g2[], const double p[]),void (NAG_CALL *range)(double *a, double *b, const double p[]),double w[], const Integer *sdw, Integer *ifail)
The routine may be called by the names d02hbf or nagf_ode_bvp_shoot_genpar.

## 3Description

d02hbf solves a two-point boundary value problem by determining the unknown parameters ${p}_{1},{p}_{2},\dots ,{p}_{{\mathit{n}}_{1}}$ 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 ${p}_{1},{p}_{2},\dots ,{p}_{{\mathit{n}}_{1}}$ correspond precisely to the unknown boundary conditions in d02haf.) It is assumed that we have a system of $\mathit{n}$ first-order ordinary differential equations of the form:
 $dyi dx =fi(x,y1,y2,…,yn), i=1,2,…,n,$
and that the derivatives ${f}_{i}$ are evaluated by fcn. The system, including the boundary conditions given by bc and the range of integration given by range, involves the ${\mathit{n}}_{1}$ unknown parameters ${p}_{1},{p}_{2},\dots ,{p}_{{\mathit{n}}_{1}}$ which are to be determined, and for which initial estimates must be supplied. The number of unknown parameters ${\mathit{n}}_{1}$ must not exceed the number of equations $\mathit{n}$. If ${\mathit{n}}_{1}<\mathit{n}$, we assume that $\left(\mathit{n}-{\mathit{n}}_{1}\right)$ 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 ${\mathit{n}}_{1}$ 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 $\left(i,j\right)$th element depends on the derivative of the $i$th component of the solution, ${y}_{i}$, with respect to the $j$th parameter, ${p}_{j}$. This matrix is calculated by a simple numerical differentiation technique which requires ${\mathit{n}}_{1}$ evaluations of the differential system.
If the argument 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 9.
d02hbf is a simplified version of d02saf which is described in detail in Gladwell (1979).

## 4References

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

## 5Arguments

You are strongly recommended to read Sections 3 and 9 in conjunction with this section.
1: $\mathbf{p}\left({\mathbf{n1}}\right)$Real (Kind=nag_wp) array Input/Output
On entry: an estimate for the $\mathit{i}$th argument, ${p}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{\mathit{n}}_{1}$.
On exit: the corrected value for the $i$th argument, unless an error has occurred, when it contains the last calculated value of the argument.
2: $\mathbf{n1}$Integer Input
On entry: ${\mathit{n}}_{1}$, the number of arguments.
Constraint: $1\le {\mathbf{n1}}\le {\mathbf{n}}$.
3: $\mathbf{pe}\left({\mathbf{n1}}\right)$Real (Kind=nag_wp) array Input
On entry: the elements of pe must be given small positive values. The element ${\mathbf{pe}}\left(i\right)$ is used
1. (i)in the convergence test on the $i$th argument in the Newton iteration, and
2. (ii)in perturbing the $i$th argument when approximating the derivatives of the components of the solution with respect to this argument for use in the Newton iteration.
The elements ${\mathbf{pe}}\left(i\right)$ should not be chosen too small. They should usually be several orders of magnitude larger than machine precision.
Constraint: ${\mathbf{pe}}\left(\mathit{i}\right)>0.0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n1}}$.
4: $\mathbf{e}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Input
On entry: the elements of e must be given positive values. The element ${\mathbf{e}}\left(i\right)$ is used in the bound on the local error in the $i$th component of the solution ${y}_{i}$ during integration.
The elements ${\mathbf{e}}\left(i\right)$ should not be chosen too small. They should usually be several orders of magnitude larger than machine precision.
Constraint: ${\mathbf{e}}\left(\mathit{i}\right)>0.0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
5: $\mathbf{n}$Integer Input
On entry: $\mathit{n}$, the total number of differential equations.
Constraint: ${\mathbf{n}}\ge {\mathbf{n1}}$.
6: $\mathbf{soln}\left({\mathbf{n}},{\mathbf{m1}}\right)$Real (Kind=nag_wp) array Output
On exit: the solution when ${\mathbf{m1}}>1$.
7: $\mathbf{m1}$Integer Input
On entry: a value which controls exit values.
${\mathbf{m1}}=1$
The final solution is not calculated.
${\mathbf{m1}}>1$
The final values of the solution at interval (length of range)/$\left({\mathbf{m1}}-1\right)$ 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: ${\mathbf{m1}}\ge 1$.
8: $\mathbf{fcn}$Subroutine, supplied by the user. External Procedure
fcn must evaluate the functions ${f}_{\mathit{i}}$ (i.e., the derivatives ${y}_{\mathit{i}}^{\prime }$), for $\mathit{i}=1,2,\dots ,\mathit{n}$, at a general point $x$.
The specification of fcn is:
Fortran Interface
 Subroutine fcn ( x, y, f, p)
 Real (Kind=nag_wp), Intent (In) :: x, y(*), p(*) Real (Kind=nag_wp), Intent (Out) :: f(*)
 void fcn (const double *x, const double y[], double f[], const double p[])
In the description of the arguments of d02hbf below, $\mathit{n}$ and $\mathit{n1}$ denote the numerical values of n and n1 in the call of d02hbf.
1: $\mathbf{x}$Real (Kind=nag_wp) Input
On entry: $x$, the value of the argument.
2: $\mathbf{y}\left(*\right)$Real (Kind=nag_wp) array Input
On entry: ${y}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,\mathit{n}$, the value of the argument.
3: $\mathbf{f}\left(*\right)$Real (Kind=nag_wp) array Output
On exit: the value of ${f}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,\mathit{n}$. The ${f}_{i}$ may depend upon the parameters ${p}_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,{\mathit{n}}_{1}$. 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: $\mathbf{p}\left(*\right)$Real (Kind=nag_wp) array Input
On entry: the current estimate of the argument ${p}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{\mathit{n}}_{1}$.
fcn must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02hbf is called. Arguments denoted as Input must not be changed by this procedure.
Note: fcn should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02hbf. If your code inadvertently does return any NaNs or infinities, d02hbf is likely to produce unexpected results.
9: $\mathbf{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:
Fortran Interface
 Subroutine bc ( g1, g2, p)
 Real (Kind=nag_wp), Intent (In) :: p(*) Real (Kind=nag_wp), Intent (Out) :: g1(*), g2(*)
 void bc (double g1[], double g2[], const double p[])
In the description of the arguments of d02hbf below, $\mathit{n}$ and $\mathit{n1}$ denote the numerical values of n and n1 in the call of d02hbf.
1: $\mathbf{g1}\left(*\right)$Real (Kind=nag_wp) array Output
On exit: the value of ${y}_{\mathit{i}}\left(a\right)$, (where this may be a known value or a function of the parameters ${p}_{\mathit{j}}$, for $\mathit{i}=1,2,\dots ,\mathit{n}$ and $\mathit{j}=1,2,\dots ,{\mathit{n}}_{1}$).
2: $\mathbf{g2}\left(*\right)$Real (Kind=nag_wp) array Output
On exit: the value of ${y}_{\mathit{i}}\left(b\right)$, for $\mathit{i}=1,2,\dots ,\mathit{n}$, (where these may be known values or functions of the parameters ${p}_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,{\mathit{n}}_{1}$). If $\mathit{n}>{\mathit{n}}_{1}$, so that there are some driving equations, the first $\mathit{n}-{\mathit{n}}_{1}$ values of g2 need not be set since they are never used.
3: $\mathbf{p}\left(*\right)$Real (Kind=nag_wp) array Input
On entry: an estimate of the argument ${p}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{\mathit{n}}_{1}$.
bc must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02hbf is called. Arguments denoted as Input must not be changed by this procedure.
Note: bc should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02hbf. If your code inadvertently does return any NaNs or infinities, d02hbf is likely to produce unexpected results.
10: $\mathbf{range}$Subroutine, supplied by the user. External Procedure
range must evaluate the boundary points $a$ and $b$, each of which may depend on the arguments ${p}_{1},{p}_{2},\dots ,{p}_{{\mathit{n}}_{1}}$. The integrations in the shooting method are always from $a$ to $b$.
The specification of range is:
Fortran Interface
 Subroutine range ( a, b, p)
 Real (Kind=nag_wp), Intent (In) :: p(*) Real (Kind=nag_wp), Intent (Out) :: a, b
 void range (double *a, double *b, const double p[])
In the description of the arguments of d02hbf below, $\mathit{n1}$ denotes the actual value of n1 in the call of d02hbf.
1: $\mathbf{a}$Real (Kind=nag_wp) Output
On exit: $a$, one of the boundary points.
2: $\mathbf{b}$Real (Kind=nag_wp) Output
On exit: the second boundary point, $b$. Note that ${\mathbf{b}}>{\mathbf{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: $\mathbf{p}\left(*\right)$Real (Kind=nag_wp) array Input
On entry: the current estimate of the $\mathit{i}$th argument, ${p}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{\mathit{n}}_{1}$.
range must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02hbf is called. Arguments denoted as Input must not be changed by this procedure.
Note: range should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02hbf. If your code inadvertently does return any NaNs or infinities, d02hbf is likely to produce unexpected results.
11: $\mathbf{w}\left({\mathbf{n}},{\mathbf{sdw}}\right)$Real (Kind=nag_wp) array Output
Used mainly for workspace.
On exit: with ${\mathbf{ifail}}={\mathbf{2}}$, ${\mathbf{3}}$, ${\mathbf{4}}$ or ${\mathbf{5}}$ (see Section 6), ${\mathbf{w}}\left(\mathit{i},1\right)$, for $\mathit{i}=1,2,\dots ,\mathit{n}$, contains the solution at the point $x$ when the error occurred. ${\mathbf{w}}\left(1,2\right)$ contains $x$.
12: $\mathbf{sdw}$Integer Input
On entry: the second dimension of the array w as declared in the (sub)program from which d02hbf is called.
Constraint: ${\mathbf{sdw}}\ge 3{\mathbf{n}}+14+\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(11,{\mathbf{n}}\right)$.
13: $\mathbf{ifail}$Integer Input/Output
This routine uses an ifail input value codification that differs from the normal case to distinguish between errors and warnings (see Section 4 in the Introduction to the NAG Library FL Interface).
On entry: ifail must be set to one of the values below to set behaviour on detection of an error; these values have no effect when no error is detected. The behaviour relate to whether or not program execution is halted and whether or not messages are printed when an error or warning is detected.
ifail Execution Error Printing Warning Printed
$\phantom{00}0$ halted No No
$\phantom{00}1$ continue No No
$\phantom{0}10$ halted Yes No
$\phantom{0}11$ continue Yes No
$100$ halted No Yes
$101$ continue No Yes
$110$ halted Yes Yes
$111$ continue Yes Yes
For environments where it might be inappropriate to halt program execution when an error is detected, the value $1$, $11$, $101$ or $111$ is recommended. If the printing of messages is undesirable, then the value $1$ is recommended. Otherwise, the recommended value is $110$. When the value $\mathbf{1}$, $\mathbf{11}$, $\mathbf{101}$ or $\mathbf{111}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{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:
${\mathbf{ifail}}=1$
On entry, ${\mathbf{m1}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{m1}}\ge 1$.
On entry, ${\mathbf{n1}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n1}}\ge 1$.
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n1}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge {\mathbf{n1}}$.
On entry, ${\mathbf{sdw}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{sdw}}\ge 3×{\mathbf{n}}+\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(25,{\mathbf{n}}+14\right)$; that is, $⟨\mathit{\text{value}}⟩$.
On entry a negative or zero convergence test tolerance has been set.
On entry a negative or zero local error tolerance has been set.
${\mathbf{ifail}}=2$
In the integration with initial or final parameters, the step size was reduced too far for the integration to proceed. Either this routine is not a suitable method for solving the problem, or the initial choice of parameters is very poor.
The step length for the integration became too short to proceed when calculating the residual.
${\mathbf{ifail}}=3$
An initial step-length could be found for integration to proceed with the current parameters.
In the integration with initial or final parameters, a suitable initial step could not be found. Either this routine is not suitable for solving the problem, or the initial choice of parameters is very poor.
${\mathbf{ifail}}=4$
The step-length required to calculate the Jacobian to sufficient accuracy is too small
${\mathbf{ifail}}=5$
An initial step-length could be found for Jacobian calculation to proceed with the current parameters.
${\mathbf{ifail}}=6$
The Jacobian has an insignificant column. Make sure that the solution vector depends on all the parameters.
${\mathbf{ifail}}=7$
An internal singular value decomposition has failed.
This error can be avoided by changing the initial parameter estimates.
${\mathbf{ifail}}=8$
The Newton iteration has failed to converge.
This can indicate a poor initial choice of parameters or a very difficult problem.
Consider varying elements of the parameter convergence control if the residuals are small; otherwise vary initial parameter estimates.
${\mathbf{ifail}}=9$
${\mathbf{ifail}}=10$
${\mathbf{ifail}}=11$
${\mathbf{ifail}}=12$
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
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.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

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.

## 8Parallelism and Performance

d02hbf 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 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 arguments contained in the arrays e and pe are used in ‘mixed’ form; that is ${\mathbf{e}}\left(i\right)$ always occurs in expressions of the form
 $e(i)×(1+|yi|)$
and ${\mathbf{pe}}\left(i\right)$ always occurs in expressions of the form
 $pe(i)×(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.
You may determine a suitable direction of integration $a$ to $b$ and suitable values for ${\mathbf{e}}\left(i\right)$ by integrations with d02pef. 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 unit numbers on which this output is to appear by calls of x04aaf (for error messages) or x04abf (for monitoring information). Otherwise the default unit 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 $2$-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 argument monit there.
The computing time for integrating the differential equations can sometimes depend critically on the quality of the initial estimates for the parameters ${p}_{i}$. 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 ${p}_{i}$.
The subroutine can be used to solve a very wide range of problems, for example:
1. (a)eigenvalue problems, including problems where the eigenvalue occurs in the boundary conditions;
2. (b)problems where the differential equations depend on some parameters which are to be determined so as to satisfy certain boundary conditions;
3. (c)problems where one of the end points of the range of integration is to be determined as the point where a variable ${y}_{i}$ takes a particular value;
4. (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; and
5. (e)differential equations with certain terms defined by other independent (driving) differential equations.

## 10Example

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
 $y′′=(y3-y′)/2x$
on the range $0\le x\le 16$, with boundary conditions $y\left(0\right)=0.1$ and $y\left(16\right)=1/6$. We cannot use the differential equation at $x=0$ because it is singular, so we take a truncated power series expansion
 $y(x)=1/10+p1×x/10+x/100$
near the origin where ${p}_{1}$ is one of the parameters to be determined. We choose the interval as $\left[0.1,16\right]$ and setting ${p}_{2}={y}^{\prime }\left(16\right)$, we can determine all the boundary conditions. We take $\mathrm{X1}=16$. We write $y={\mathbf{y}}\left(1\right)$, ${y}^{\prime }={\mathbf{y}}\left(2\right)$, and estimate $\mathrm{PARAM}\left(1\right)=0.2$, $\mathrm{PARAM}\left(2\right)=0.0$. Note the call to x04abf before the call to d02hbf.
Example 2 (EX2)
This example finds the gravitational constant ${p}_{1}$ and the range ${p}_{2}$ over which a projectile must be fired to hit the target with a given velocity.
The differential equations are
 $y′ = tan⁡ϕ v′ = -(p1sin⁡ϕ+0.00002⁢v2) vcos⁡ϕ ϕ ′ = -p1v2$
on the range $0, with boundary conditions
We write $y={\mathbf{y}}\left(1\right)$, $v={\mathbf{y}}\left(2\right)$, $\varphi ={\mathbf{y}}\left(3\right)$. We estimate ${p}_{1}=\mathrm{PARAM}\left(1\right)=32$, ${p}_{2}=\mathrm{PARAM}\left(2\right)=6000$ and ${p}_{3}=\mathrm{PARAM}\left(3\right)=0.54$ (though this last estimate is not important).

### 10.1Program Text

Program Text (d02hbfe.f90)

### 10.2Program Data

Program Data (d02hbfe.d)

### 10.3Program Results

Program Results (d02hbfe.r)