NAG CL Interface
d02gac (bvp_​fd_​nonlin_​fixedbc)

Settings help

CL Name Style:


1 Purpose

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 ,, y neq ) , i = 1 , 2 , , 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 fi yj 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: neq2 .
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,,neq.
4: f[neq] double Output
On exit: f [i-1] must contain the values of f i , for i=1,2,,neq.
5: comm Nag_User *
Pointer to a structure of type Nag_User with the following member:
pPointer 
On entry/exit: the pointer commp 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×2] const double Input
On entry: u[(i-1)×2] must be set to the known (assigned) or estimated values of y i at a and u[(i-1)×2+1] must be set to the known or estimated values of y i at b , for i=1,2,,neq.
6: v[neq×2] const Integer Input
On entry: v[(i-1)×2+j-1] must be set to 0 if u[(i-1)×2+j-1] is a known (assigned) value and to 1 if u[(i-1)×2+j-1] is an estimated value, i = 1 , 2 , , neq and j = 1 , 2 .
Constraint: precisely neq of the v[(i-1)×2+j-1] must be set to 0, i.e., precisely neq of u[(i-1)×2] and u[(i-1)×2+1] must be known values and these must not be all at a or b .
7: mnp Integer Input
On entry: the maximum permitted number of mesh points.
Constraint: mnp32 .
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] , , x[np-1] is used.
np4
You must define an initial mesh using the array x as described.
Constraint: np=0 or 4npmnp.
On exit: the number of points in the final (returned) mesh.
9: x[mnp] double Input/Output
On entry: if np4 (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] < < x[np-1] = b ​ for ​ np 4 (2)
On exit: x[0] , x[1] , , x[np-1] define the final mesh (with the returned value of np) satisfying the relation (2).
10: y[neq×mnp] double Output
On exit: the approximate solution z j ( x i ) satisfying (3), on the final mesh, that is
y[(j-1)×mnp+i-1] = z j ( x i ) , i = 1 , 2 , , np ; ​ j = 1 , 2 , , 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 < < 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 )| tol , i = 1 , 2 , , np ; ​ j = 1 , 2 , , neq (3)
Constraint: tol>0.0 .
12: comm Nag_User *
Pointer to a structure of type Nag_User with the following member:
pPointer 
On entry/exit: the pointer commp, 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 commp 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: mnp32.
On entry, neq=value.
Constraint: neq2.
NE_INT_RANGE_CONS_2
On entry, np=value and mnp=value . The argument np must satisfy either 4 np 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.

10 Example

We solve the differential equation
y ′′′ = - yy - β (1- y 2 )  
with boundary conditions
y (0) = y (0) = 0 ,   y (10) = 1  
for β=0.0 and β=0.2 to an accuracy specified by tol = 1.0e−3 . We solve first the simpler problem with β=0.0 using an equispaced mesh of 26 points and then we solve the problem with β=0.2 using the final mesh from the first problem.

10.1 Program Text

Program Text (d02gace.c)

10.2 Program Data

None.

10.3 Program Results

Program Results (d02gace.r)