d02gac solves the two-point 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

#include <nag.h>

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 two-point boundary value problem for a system of neq differential equations in the interval

[a, b]

. The system is written in the form

y_{i}^{'} = f_{i} (x, y_{1}, y_{2}, \dots, y_{neq}), i = 1, 2, \dots, neq

(1)

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 finite-difference 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: $neq$ – Integer Input

On entry: the number of equations.

Constraint:

neq \geq 2

2: $fcn$ – function, supplied by the user External Function

fcn must evaluate the functions

f_{i}

(i.e., the derivatives

y_{i}^{'}

) 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: $neq$ – Integer Input

On entry: the number of differential equations.

2: $x$ – double Input

On entry: the value of the argument

x

3: $y [neq]$ – const double Input

On entry:

y [i - 1]

holds the value of the argument

y_{i}

, for

i = 1, 2, \dots, neq

4: $f [neq]$ – double Output

On exit:

f [i - 1]

must contain the values of

f_{i}

, for

i = 1, 2, \dots, neq

5: $comm$ – Nag_User *

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

p – Pointer: On entry/exit: the pointer $comm \to 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 floating-point 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: $a$ – double Input

On entry: the left-hand boundary point,

a

4: $b$ – double Input

On entry: the right-hand boundary point,

b

Constraint:

b > a

5: $u [neq \times 2]$ – const double Input

On entry:

u [(i - 1) \times 2]

must be set to the known (assigned) or estimated values of

y_{i}

a

and

u [(i - 1) \times 2 + 1]

must be set to the known or estimated values of

y_{i}

b

, for

i = 1, 2, \dots, neq

6: $v [neq \times 2]$ – const Integer Input

On entry:

v [(i - 1) \times 2 + j - 1]

must be set to 0 if

u [(i - 1) \times 2 + j - 1]

is a known (assigned) value and to 1 if

u [(i - 1) \times 2 + j - 1]

is an estimated value,

i = 1, 2, \dots, neq

and

j = 1, 2

Constraint: precisely neq of the

v [(i - 1) \times 2 + j - 1]

must be set to

0

, i.e., precisely neq of

u [(i - 1) \times 2]

and

u [(i - 1) \times 2 + 1]

must be known values and these must not be all at

a

b

7: $mnp$ – Integer Input

On entry: the maximum permitted number of mesh points.

Constraint:

mnp \geq 32

8: $np$ – Integer * Input/Output

On entry: determines whether a default or user-supplied initial mesh is used.

$np = 0$: np is set to a default value of 4 and a corresponding equispaced mesh $x [0], x [1], \dots, x [np - 1]$ is used.
$np \geq 4$: You must define an initial mesh using the array x as described.

Constraint:

np = 0

4 \leq np \leq mnp

On exit: the number of points in the final (returned) mesh.

9: $x [mnp]$ – double Input/Output

On entry: if

np \geq 4

(see np above), the first np elements must define an initial mesh. Otherwise the elements of x need not be set.

Constraint:

a = x [0] < x [1] < \dots < x [np - 1] = b ​ for ​ np \geq 4

(2)

On exit:

x [0], x [1], \dots, x [np - 1]

define the final mesh (with the returned value of np) satisfying the relation (2).

10: $y [neq \times mnp]$ – double Output

On exit: the approximate solution

z_{j} (x_{i})

satisfying (3), on the final mesh, that is

y [(j - 1) \times mnp + i - 1] = z_{j} (x_{i}), i = 1, 2, \dots, np; ​ j = 1, 2, \dots, neq,

where np is the number of points in the final mesh.

The remaining columns of y are not used.

11: $tol$ – double Input

On entry: a positive absolute error tolerance. If

a = x_{1} < x_{2} < \dots < x_{np} = b

is the final mesh,

z_{j} (x_{i})

is the

j

th component of the approximate solution at

x_{i}

, and

y_{j} (x_{i})

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

| z_{j} (x_{i}) - y_{j} (x_{i}) | \leq tol, i = 1, 2, \dots, np; ​ j = 1, 2, \dots, neq

(3)

Constraint:

tol > 0.0

12: $comm$ – Nag_User *

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

p – Pointer: On entry/exit: the pointer $comm \to 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 $comm \to 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: $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, $b = ⟨ value ⟩$ while $a = ⟨ value ⟩$ . These arguments must satisfy $b > 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, $mnp = ⟨ value ⟩$ .
Constraint: $mnp \geq 32$ .

On entry, $neq = ⟨ value ⟩$ .
Constraint: $neq \geq 2$ .
NE_INT_RANGE_CONS_2: On entry, $np = ⟨ value ⟩$ and $mnp = ⟨ value ⟩$ . The argument np must satisfy either $4 \leq np \leq mnp$ or $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 $x [0]$ : $a = ⟨ value ⟩$ , $x [0] = ⟨ value ⟩$ .
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 $= ⟨ value ⟩$ :
The number of equations $= ⟨ value ⟩$ .
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 $= ⟨ value ⟩$ :
The number of known right boundary values $= ⟨ value ⟩$ :
The number of equations $= ⟨ value ⟩$ .
NE_NOT_STRICTLY_INCREASING: The sequence x is not strictly increasing: $x [⟨ value ⟩] = ⟨ value ⟩$ , $x [⟨ value ⟩] = ⟨ value ⟩$ .
NE_REAL_ARG_LE: On entry, tol must not be less than or equal to 0.0: $tol = ⟨ value ⟩$ .
NE_RT_B_MESH: On entry, the right boundary value b, has not been set to $x [np - 1]$ : $b = ⟨ value ⟩$ , $x [np - 1] = ⟨ value ⟩$ .
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 $= ⟨ value ⟩$ :
The number of equations $= ⟨ value ⟩$ .

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

Background information to multithreading can be found in the Multithreading documentation.

d02gac is not threaded in any implementation.

9 Further Comments

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.