NAG CL Interface
d02gac (bvp_fd_nonlin_fixedbc)
1
Purpose
d02gac solves the twopoint boundary value problem with assigned boundary values for a system of ordinary differential equations, using a deferred correction technique and a Newton iteration.
2
Specification
void 
d02gac (Integer neq,
void 
(*fcn)(Integer neq,
double x,
const double y[],
double f[],
Nag_User *comm),


double a,
double b,
const double u[],
const Integer v[],
Integer mnp,
Integer *np,
double x[],
double y[],
double tol,
Nag_User *comm,
NagError *fail) 

The function may be called by the names: d02gac or nag_ode_bvp_fd_nonlin_fixedbc.
3
Description
d02gac solves a twopoint boundary value problem for a system of
neq differential equations in the interval
$\left[a,b\right]$. The system is written in the form
and the derivatives are evaluated by
fcn. Initially,
neq boundary values of the variables
${y}_{i}$ must be specified (assigned), some at
$a$ and some at
$b$. You also need to supply estimates of the remaining
neq boundary values and all the boundary values are used in constructing an initial approximation to the solution. This approximate solution is corrected by a finite difference technique with deferred correction allied with a Newton iteration to solve the finite difference equations. The technique used is described fully in
Pereyra (1979). The Newton iteration requires a Jacobian matrix
$\frac{\partial {f}_{i}}{\partial {y}_{j}}$ and this is calculated by numerical differentiation using an algorithm described in
Curtis et al. (1974).
You need to supply an absolute error tolerance and may also supply an initial mesh for the construction of the finite difference equations (alternatively a default mesh is used). The algorithm constructs a solution on a mesh defined by adding points to the initial mesh. This solution is chosen so that the error is everywhere less than your tolerance and so that the error is approximately equidistributed on the final mesh. The solution is returned on this final mesh.
If the solution is required at a few specific points then these should be included in the initial mesh. If on the other hand the solution is required at several specific points then you should use the interpolation functions provided in
Chapter E01 if these points do not themselves form a convenient mesh.
4
References
Curtis A R, Powell M J D and Reid J K (1974) On the estimation of sparse Jacobian matrices J. Inst. Maths. Applics. 13 117–119
Pereyra V (1979) PASVA3: An adaptive finitedifference Fortran program for first order nonlinear, ordinary boundary problems 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
Arguments

1:
$\mathbf{neq}$ – Integer
Input

On entry: the number of equations.
Constraint:
${\mathbf{neq}}\ge 2$.

2:
$\mathbf{fcn}$ – function, supplied by the user
External Function

fcn must evaluate the functions
${f}_{i}$ (i.e., the derivatives
${y}_{i}^{\prime}$) at the general point
$x$.
The specification of
fcn is:
void 
fcn (Integer neq,
double x,
const double y[],
double f[],
Nag_User *comm)



1:
$\mathbf{neq}$ – Integer
Input

On entry: the number of differential equations.

2:
$\mathbf{x}$ – double
Input

On entry: the value of the argument $x$.

3:
$\mathbf{y}\left[{\mathbf{neq}}\right]$ – const double
Input

On entry: $y\left[\mathit{i}1\right]$ holds the value of the argument ${y}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{\mathbf{neq}}$.

4:
$\mathbf{f}\left[{\mathbf{neq}}\right]$ – double
Output

On exit: $f\left[\mathit{i}1\right]$ must contain the values of ${f}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{\mathbf{neq}}$.

5:
$\mathbf{comm}$ – Nag_User *

Pointer to a structure of type Nag_User with the following member:
 p – Pointer

On entry/exit: the pointer
$\mathbf{comm}\mathbf{\to}\mathbf{p}$ should be cast to the required type, e.g.,
struct user *s = (struct user *)comm → p, to obtain the original object's address with appropriate type. (See the argument
comm below.)
Note: fcn should not return floatingpoint NaN (Not a Number) or infinity values, since these are not handled by
d02gac. If your code inadvertently
does return any NaNs or infinities,
d02gac is likely to produce unexpected results.

3:
$\mathbf{a}$ – double
Input

On entry: the lefthand boundary point, $a$.

4:
$\mathbf{b}$ – double
Input

On entry: the righthand boundary point, $b$.
Constraint:
${\mathbf{b}}>{\mathbf{a}}$.

5:
$\mathbf{u}\left[{\mathbf{neq}}\times 2\right]$ – const double
Input

On entry: ${\mathbf{u}}\left[\left(i1\right)\times 2\right]$ must be set to the known (assigned) or estimated values of ${y}_{i}$ at $a$ and ${\mathbf{u}}\left[\left(\mathit{i}1\right)\times 2+1\right]$ must be set to the known or estimated values of ${y}_{\mathit{i}}$ at $b$, for $\mathit{i}=1,2,\dots ,{\mathbf{neq}}$.

6:
$\mathbf{v}\left[{\mathbf{neq}}\times 2\right]$ – const Integer
Input

On entry: ${\mathbf{v}}\left[\left(i1\right)\times 2+j1\right]$ must be set to 0 if ${\mathbf{u}}\left[\left(i1\right)\times 2+j1\right]$ is a known (assigned) value and to 1 if ${\mathbf{u}}\left[\left(i1\right)\times 2+j1\right]$ is an estimated value, $i=1,2,\dots ,{\mathbf{neq}}$ and $j=1,2$.
Constraint:
precisely
neq of the
${\mathbf{v}}\left[\left(i1\right)\times 2+j1\right]$ must be set to
$0$, i.e., precisely
neq of
${\mathbf{u}}\left[\left(i1\right)\times 2\right]$ and
${\mathbf{u}}\left[\left(i1\right)\times 2+1\right]$ must be known values and these must not be all at
$a$ or
$b$.

7:
$\mathbf{mnp}$ – Integer
Input

On entry: the maximum permitted number of mesh points.
Constraint:
${\mathbf{mnp}}\ge 32$.

8:
$\mathbf{np}$ – Integer *
Input/Output

On entry: determines whether a default or usersupplied initial mesh is used.
 ${\mathbf{np}}=0$
 np is set to a default value of 4 and a corresponding equispaced mesh ${\mathbf{x}}\left[0\right],{\mathbf{x}}\left[1\right],\dots ,{\mathbf{x}}\left[{\mathbf{np}}1\right]$ is used.
 ${\mathbf{np}}\ge 4$
 You must define an initial mesh using the array x as described.
Constraint:
${\mathbf{np}}=0$ or $4\le {\mathbf{np}}\le {\mathbf{mnp}}$.
On exit: the number of points in the final (returned) mesh.

9:
$\mathbf{x}\left[{\mathbf{mnp}}\right]$ – double
Input/Output

On entry: if
${\mathbf{np}}\ge 4$ (see
np above), the first
np elements must define an initial mesh. Otherwise the elements of
x need not be set.
On exit:
${\mathbf{x}}\left[0\right],{\mathbf{x}}\left[1\right],\dots ,{\mathbf{x}}\left[{\mathbf{np}}1\right]$ define the final mesh (with the returned value of
np) satisfying the relation
(2).

10:
$\mathbf{y}\left[{\mathbf{neq}}\times {\mathbf{mnp}}\right]$ – double
Output

On exit: the approximate solution
${z}_{j}\left({x}_{i}\right)$ satisfying
(3), on the final mesh, that is
where
np is the number of points in the final mesh.
The remaining columns of
y are not used.

11:
$\mathbf{tol}$ – double
Input

On entry: a positive absolute error tolerance. If
is the final mesh,
${z}_{j}\left({x}_{i}\right)$ is the
$j$th component of the approximate solution at
${x}_{i}$, and
${y}_{j}\left({x}_{i}\right)$ is the
$j$th component of the true solution of equation
(1) (see
Section 3) and the boundary conditions, then, except in extreme cases, it is expected that
Constraint:
${\mathbf{tol}}>0.0$.

12:
$\mathbf{comm}$ – Nag_User *

Pointer to a structure of type Nag_User with the following member:
 p – Pointer

On entry/exit: the pointer
$\mathbf{comm}\mathbf{\to}\mathbf{p}$, of type Pointer, allows you to communicate information to and from
fcn. An object of the required type should be declared, e.g., a structure, and its address assigned to the pointer
$\mathbf{comm}\mathbf{\to}\mathbf{p}$ by means of a cast to Pointer in the calling program, e.g.,
comm.p = (Pointer)&s. The type pointer will be
void * with a C compiler that defines
void * and
char * otherwise.

13:
$\mathbf{fail}$ – NagError *
Input/Output

The NAG error argument (see
Section 7 in the Introduction to the NAG Library CL Interface).
6
Error Indicators and Warnings
 NE_2_REAL_ARG_LE

On entry, ${\mathbf{b}}=\u2329\mathit{\text{value}}\u232a$ while ${\mathbf{a}}=\u2329\mathit{\text{value}}\u232a$. These arguments must satisfy ${\mathbf{b}}>{\mathbf{a}}$.
 NE_ALLOC_FAIL

Dynamic memory allocation failed.
 NE_CONV_MESH

A finer mesh is required for the accuracy requested; that is
mnp is not large enough.
 NE_CONV_MESH_INIT

The Newton iteration failed to converge on the initial mesh. This may be due to the initial mesh having too few points or the initial approximate solution being too inaccurate. Try using
d02rac.
 NE_CONV_ROUNDOFF

Solution cannot be improved due to roundoff error. Too much accuracy might have been requested.
 NE_INT_ARG_LT

On entry, ${\mathbf{mnp}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{mnp}}\ge 32$.
On entry, ${\mathbf{neq}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{neq}}\ge 2$.
 NE_INT_RANGE_CONS_2

On entry,
${\mathbf{np}}=\u2329\mathit{\text{value}}\u232a$ and
${\mathbf{mnp}}=\u2329\mathit{\text{value}}\u232a$. The argument
np must satisfy either
$4\le {\mathbf{np}}\le {\mathbf{mnp}}$ or
${\mathbf{np}}=0$.
 NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact
NAG for assistance.
 NE_LF_B_MESH

On entry, the left boundary value
a, has not been set to
${\mathbf{x}}\left[0\right]$:
${\mathbf{a}}=\u2329\mathit{\text{value}}\u232a$,
${\mathbf{x}}\left[0\right]=\u2329\mathit{\text{value}}\u232a$.
 NE_LF_B_VAL

The number of known left boundary values must be less than the number of equations:
The number of known left boundary values $\text{}=\u2329\mathit{\text{value}}\u232a$:
The number of equations $\text{}=\u2329\mathit{\text{value}}\u232a$.
 NE_LFRT_B_VAL

The sum of known left and right boundary values must equal the number of equations:
The number of known left boundary values $\text{}=\u2329\mathit{\text{value}}\u232a$:
The number of known right boundary values $\text{}=\u2329\mathit{\text{value}}\u232a$:
The number of equations $\text{}=\u2329\mathit{\text{value}}\u232a$.
 NE_NOT_STRICTLY_INCREASING

The sequence
x is not strictly increasing:
${\mathbf{x}}\left[\u2329\mathit{\text{value}}\u232a\right]=\u2329\mathit{\text{value}}\u232a$,
${\mathbf{x}}\left[\u2329\mathit{\text{value}}\u232a\right]=\u2329\mathit{\text{value}}\u232a$.
 NE_REAL_ARG_LE

On entry,
tol must not be less than or equal to 0.0:
${\mathbf{tol}}=\u2329\mathit{\text{value}}\u232a$.
 NE_RT_B_MESH

On entry, the right boundary value
b, has not been set to
${\mathbf{x}}\left[{\mathbf{np}}1\right]$:
${\mathbf{b}}=\u2329\mathit{\text{value}}\u232a$,
${\mathbf{x}}\left[{\mathbf{np}}1\right]=\u2329\mathit{\text{value}}\u232a$.
 NE_RT_B_VAL

The number of known right boundary values must be less than the number of equations:
The number of known right boundary values $\text{}=\u2329\mathit{\text{value}}\u232a$:
The number of equations $\text{}=\u2329\mathit{\text{value}}\u232a$.
7
Accuracy
The solution returned by
d02gac will be accurate to your tolerance as defined by the relation
(3) except in extreme circumstances. If too many points are specified in the initial mesh, the solution may be more accurate than requested and the error may not be approximately equidistributed.
8
Parallelism and Performance
d02gac is not threaded in any implementation.
The time taken by the function depends on the difficulty of the problem, the number of mesh points used (and the number of different meshes used), the number of Newton iterations and the number of deferred corrections.
A common cause of convergence problems in the Newton iteration is that you are specifying too few points in the initial mesh. Although the function adds points to the mesh to improve accuracy it is unable to do so until the solution on the initial mesh has been calculated in the Newton iteration.
If the known and estimated boundary values are set to zero, the function constructs a zero initial approximation and in many cases the Jacobian is singular when evaluated for this approximation, leading to the breakdown of the Newton iteration.
You may be unable to provide a sufficiently good choice of initial mesh and estimated boundary values, and hence the Newton iteration may never converge. In this case the continuation facility provided in
d02rac is recommended.
In the case where you wish to solve a sequence of similar problems, the final mesh from solving one case is strongly recommended as the initial mesh for the next.
10
Example
We solve the differential equation
with boundary conditions
for
$\beta =0.0$ and
$\beta =0.2$ to an accuracy specified by
${\mathbf{tol}}=\text{1.0e\u22123}$. We solve first the simpler problem with
$\beta =0.0$ using an equispaced mesh of 26 points and then we solve the problem with
$\beta =0.2$ using the final mesh from the first problem.
10.1
Program Text
10.2
Program Data
None.
10.3
Program Results