NAG Library Function Document
nag_ode_bvp_fd_nonlin_fixedbc (d02gac)
1
Purpose
nag_ode_bvp_fd_nonlin_fixedbc (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> |
#include <nagd02.h> |
void |
nag_ode_bvp_fd_nonlin_fixedbc (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) |
|
3
Description
nag_ode_bvp_fd_nonlin_fixedbc (d02gac) solves a two-point boundary value problem for a system of
neq differential equations in the interval
. The system is written in the form
and the derivatives are evaluated by
fcn. Initially,
neq boundary values of the variables
must be specified (assigned), some at
and some at
. 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
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:
– IntegerInput
-
On entry: the number of equations.
Constraint:
.
- 2:
– function, supplied by the userExternal Function
-
fcn must evaluate the functions
(i.e., the derivatives
) at the general point
.
The specification of
fcn is:
void |
fcn (Integer neq,
double x,
const double y[],
double f[],
Nag_User *comm)
|
|
- 1:
– IntegerInput
-
On entry: the number of differential equations.
- 2:
– doubleInput
-
On entry: the value of the argument .
- 3:
– const doubleInput
-
On entry: holds the value of the argument , for .
- 4:
– doubleOutput
-
On exit: must contain the values of , for .
- 5:
– Nag_User *
-
Pointer to a structure of type Nag_User with the following member:
- p – Pointer
-
On entry/exit: the pointer
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
nag_ode_bvp_fd_nonlin_fixedbc (d02gac). If your code inadvertently
does return any NaNs or infinities,
nag_ode_bvp_fd_nonlin_fixedbc (d02gac) is likely to produce unexpected results.
- 3:
– doubleInput
-
On entry: the left-hand boundary point, .
- 4:
– doubleInput
-
On entry: the right-hand boundary point, .
Constraint:
.
- 5:
– const doubleInput
-
On entry: must be set to the known (assigned) or estimated values of at and must be set to the known or estimated values of at , for .
- 6:
– const IntegerInput
-
On entry: must be set to 0 if is a known (assigned) value and to 1 if is an estimated value, and .
Constraint:
precisely
neq of the
must be set to 0, i.e., precisely
neq of
and
must be known values and these must not be all at
or
.
- 7:
– IntegerInput
-
On entry: the maximum permitted number of mesh points.
Constraint:
.
- 8:
– Integer *Input/Output
-
On entry: determines whether a default or user-supplied initial mesh is used.
- np is set to a default value of 4 and a corresponding equispaced mesh is used.
- You must define an initial mesh using the array x as described.
Constraint:
or .
On exit: the number of points in the final (returned) mesh.
- 9:
– doubleInput/Output
-
On entry: if
(see
np above), the first
np elements must define an initial mesh. Otherwise the elements of
x need not be set.
On exit:
define the final mesh (with the returned value of
np) satisfying the relation
(2).
- 10:
– doubleOutput
-
On exit: the approximate solution
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:
– doubleInput
-
On entry: a positive absolute error tolerance. If
is the final mesh,
is the
th component of the approximate solution at
, and
is the
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:
.
- 12:
– Nag_User *
-
Pointer to a structure of type Nag_User with the following member:
- p – Pointer
-
On entry/exit: the pointer
, 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
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:
– NagError *Input/Output
-
The NAG error argument (see
Section 3.7 in How to Use the NAG Library and its Documentation).
6
Error Indicators and Warnings
- NE_2_REAL_ARG_LE
-
On entry, while . These arguments must satisfy .
- 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
nag_ode_bvp_fd_nonlin_gen (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, .
Constraint: .
On entry, .
Constraint: .
- NE_INT_RANGE_CONS_2
-
On entry,
and
. The argument
np must satisfy either
or
.
- 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
:
,
.
- 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 :
The number of equations .
- 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 :
The number of known right boundary values :
The number of equations .
- NE_NOT_STRICTLY_INCREASING
-
The sequence
x is not strictly increasing:
,
.
- NE_REAL_ARG_LE
-
On entry,
tol must not be less than or equal to 0.0:
.
- NE_RT_B_MESH
-
On entry, the right boundary value
b, has not been set to
:
,
.
- 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 :
The number of equations .
7
Accuracy
The solution returned by
nag_ode_bvp_fd_nonlin_fixedbc (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
nag_ode_bvp_fd_nonlin_fixedbc (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
nag_ode_bvp_fd_nonlin_gen (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
and
to an accuracy specified by
. We solve first the simpler problem with
using an equispaced mesh of 26 points and then we solve the problem with
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)