NAG CL Interface
d02tlc (bvp_coll_nlin_solve)
1
Purpose
d02tlc solves a general two-point boundary value problem for a nonlinear mixed order system of ordinary differential equations.
2
Specification
void |
d02tlc (
void |
(*ffun)(double x,
const double y[],
Integer neq,
const Integer m[],
double f[],
Nag_Comm *comm),
|
|
void |
(*fjac)(double x,
const double y[],
Integer neq,
const Integer m[],
double dfdy[],
Nag_Comm *comm),
|
|
void |
(*gafun)(const double ya[],
Integer neq,
const Integer m[],
Integer nlbc,
double ga[],
Nag_Comm *comm),
|
|
void |
(*gbfun)(const double yb[],
Integer neq,
const Integer m[],
Integer nrbc,
double gb[],
Nag_Comm *comm),
|
|
void |
(*guess)(double x,
Integer neq,
const Integer m[],
double y[],
double dym[],
Nag_Comm *comm),
|
|
double rcomm[],
Integer icomm[],
Nag_Comm *comm,
NagError *fail) |
|
The function may be called by the names: d02tlc or nag_ode_bvp_coll_nlin_solve.
3
Description
d02tlc and its associated functions (
d02tvc,
d02txc,
d02tyc and
d02tzc) solve the two-point boundary value problem for a nonlinear mixed order system of ordinary differential equations
over an interval
subject to
(
) nonlinear boundary conditions at
and
(
) nonlinear boundary conditions at
, where
. Note that
is the
th derivative of the
th solution component. Hence
. The left boundary conditions at
are defined as
and the right boundary conditions at
as
where
and
First,
d02tvc must be called to specify the initial mesh, error requirements and other details. Note that the error requirements apply only to the solution components
and that no error control is applied to derivatives of solution components. (If error control is required on derivatives then the system must be reduced in order by introducing the derivatives whose error is to be controlled as new variables. See
Section 9 in
d02tvc.) Then,
d02tlc can be used to solve the boundary value problem. After successful computation,
d02tzc can be used to ascertain details about the final mesh and other details of the solution procedure, and
d02tyc can be used to compute the approximate solution anywhere on the interval
.
A description of the numerical technique used in
d02tlc is given in
Section 3 in
d02tvc.
d02tlc can also be used in the solution of a series of problems, for example in performing continuation, when the mesh used to compute the solution of one problem is to be used as the initial mesh for the solution of the next related problem.
d02txc should be used in between calls to
d02tlc in this context.
See
Section 9 in
d02tvc for details of how to solve boundary value problems of a more general nature.
The functions are based on modified versions of the codes COLSYS and COLNEW (see
Ascher et al. (1979) and
Ascher and Bader (1987)). A comprehensive treatment of the numerical solution of boundary value problems can be found in
Ascher et al. (1988) and
Keller (1992).
4
References
Ascher U M and Bader G (1987) A new basis implementation for a mixed order boundary value ODE solver SIAM J. Sci. Stat. Comput. 8 483–500
Ascher U M, Christiansen J and Russell R D (1979) A collocation solver for mixed order systems of boundary value problems Math. Comput. 33 659–679
Ascher U M, Mattheij R M M and Russell R D (1988) Numerical Solution of Boundary Value Problems for Ordinary Differential Equations Prentice–Hall
Keller H B (1992) Numerical Methods for Two-point Boundary-value Problems Dover, New York
5
Arguments
-
1:
– function, supplied by the user
External Function
-
ffun must evaluate the functions
for given values
.
The specification of
ffun is:
void |
ffun (double x,
const double y[],
Integer neq,
const Integer m[],
double f[],
Nag_Comm *comm)
|
|
-
1:
– double
Input
-
On entry: , the independent variable.
-
2:
– const double
Input
Note: the dimension,
dim, of the array
y
is
.
where appears in this document, it refers to the array element
.
On entry: contains , for and .
Note: .
-
3:
– Integer
Input
-
On entry: the number of differential equations.
-
4:
– const Integer
Input
-
On entry: contains , the order of the th differential equation, for .
-
5:
– double
Output
-
On exit: must contain , for .
-
6:
– Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to
ffun.
- user – double *
- iuser – Integer *
- p – Pointer
The type Pointer will be
void *. Before calling
d02tlc you may allocate memory and initialize these pointers with various quantities for use by
ffun when called from
d02tlc (see
Section 3.1.1 in the Introduction to the NAG Library CL Interface).
Note: ffun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by
d02tlc. If your code inadvertently
does return any NaNs or infinities,
d02tlc is likely to produce unexpected results.
-
2:
– function, supplied by the user
External Function
-
fjac must evaluate the partial derivatives of
with respect to the elements of
.
The specification of
fjac is:
void |
fjac (double x,
const double y[],
Integer neq,
const Integer m[],
double dfdy[],
Nag_Comm *comm)
|
|
-
1:
– double
Input
-
On entry: , the independent variable.
-
2:
– const double
Input
Note: the dimension,
dim, of the array
y
is
.
where appears in this document, it refers to the array element
.
On entry: contains , for and .
Note: .
-
3:
– Integer
Input
-
On entry: the number of differential equations.
-
4:
– const Integer
Input
-
On entry: contains , the order of the th differential equation, for .
-
5:
– double
Input/Output
Note: the dimension,
dim, of the array
dfdy
is
.
where appears in this document, it refers to the array element .
On entry: set to zero.
On exit: must contain the partial derivative of with respect to , for , and . Only nonzero partial derivatives need be set.
-
6:
– Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to
fjac.
- user – double *
- iuser – Integer *
- p – Pointer
The type Pointer will be
void *. Before calling
d02tlc you may allocate memory and initialize these pointers with various quantities for use by
fjac when called from
d02tlc (see
Section 3.1.1 in the Introduction to the NAG Library CL Interface).
Note: fjac should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by
d02tlc. If your code inadvertently
does return any NaNs or infinities,
d02tlc is likely to produce unexpected results.
-
3:
– function, supplied by the user
External Function
-
gafun must evaluate the boundary conditions at the left-hand end of the range, that is functions
for given values of
.
The specification of
gafun is:
void |
gafun (const double ya[],
Integer neq,
const Integer m[],
Integer nlbc,
double ga[],
Nag_Comm *comm)
|
|
-
1:
– const double
Input
Note: the dimension,
dim, of the array
ya
is
.
where appears in this document, it refers to the array element
.
On entry: contains , for and .
Note: .
-
2:
– Integer
Input
-
On entry: the number of differential equations.
-
3:
– const Integer
Input
-
On entry: contains , the order of the th differential equation, for .
-
4:
– Integer
Input
-
On entry: the number of boundary conditions at .
-
5:
– double
Output
-
On exit: must contain , for .
-
6:
– Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to
gafun.
- user – double *
- iuser – Integer *
- p – Pointer
The type Pointer will be
void *. Before calling
d02tlc you may allocate memory and initialize these pointers with various quantities for use by
gafun when called from
d02tlc (see
Section 3.1.1 in the Introduction to the NAG Library CL Interface).
Note: gafun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by
d02tlc. If your code inadvertently
does return any NaNs or infinities,
d02tlc is likely to produce unexpected results.
-
4:
– function, supplied by the user
External Function
-
gbfun must evaluate the boundary conditions at the right-hand end of the range, that is functions
for given values of
.
The specification of
gbfun is:
void |
gbfun (const double yb[],
Integer neq,
const Integer m[],
Integer nrbc,
double gb[],
Nag_Comm *comm)
|
|
-
1:
– const double
Input
Note: the dimension,
dim, of the array
yb
is
.
where appears in this document, it refers to the array element
.
On entry: contains , for and .
Note: .
-
2:
– Integer
Input
-
On entry: the number of differential equations.
-
3:
– const Integer
Input
-
On entry: contains , the order of the th differential equation, for .
-
4:
– Integer
Input
-
On entry: the number of boundary conditions at .
-
5:
– double
Output
-
On exit: must contain , for .
-
6:
– Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to
gbfun.
- user – double *
- iuser – Integer *
- p – Pointer
The type Pointer will be
void *. Before calling
d02tlc you may allocate memory and initialize these pointers with various quantities for use by
gbfun when called from
d02tlc (see
Section 3.1.1 in the Introduction to the NAG Library CL Interface).
Note: gbfun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by
d02tlc. If your code inadvertently
does return any NaNs or infinities,
d02tlc is likely to produce unexpected results.
-
5:
– function, supplied by the user
External Function
-
gajac must evaluate the partial derivatives of
with respect to the elements of
.
The specification of
gajac is:
void |
gajac (const double ya[],
Integer neq,
const Integer m[],
Integer nlbc,
double dgady[],
Nag_Comm *comm)
|
|
-
1:
– const double
Input
Note: the dimension,
dim, of the array
ya
is
.
where appears in this document, it refers to the array element
.
On entry: contains , for and .
Note: .
-
2:
– Integer
Input
-
On entry: the number of differential equations.
-
3:
– const Integer
Input
-
On entry: contains , the order of the th differential equation, for .
-
4:
– Integer
Input
-
On entry: the number of boundary conditions at .
-
5:
– double
Input/Output
Note: the dimension,
dim, of the array
dgady
is
.
where appears in this document, it refers to the array element .
On entry: set to zero.
On exit: must contain the partial derivative of with respect to , for , and . Only nonzero partial derivatives need be set.
-
6:
– Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to
gajac.
- user – double *
- iuser – Integer *
- p – Pointer
The type Pointer will be
void *. Before calling
d02tlc you may allocate memory and initialize these pointers with various quantities for use by
gajac when called from
d02tlc (see
Section 3.1.1 in the Introduction to the NAG Library CL Interface).
Note: gajac should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by
d02tlc. If your code inadvertently
does return any NaNs or infinities,
d02tlc is likely to produce unexpected results.
-
6:
– function, supplied by the user
External Function
-
gbjac must evaluate the partial derivatives of
with respect to the elements of
.
The specification of
gbjac is:
void |
gbjac (const double yb[],
Integer neq,
const Integer m[],
Integer nrbc,
double dgbdy[],
Nag_Comm *comm)
|
|
-
1:
– const double
Input
Note: the dimension,
dim, of the array
yb
is
.
where appears in this document, it refers to the array element
.
On entry: contains , for and .
Note: .
-
2:
– Integer
Input
-
On entry: the number of differential equations.
-
3:
– const Integer
Input
-
On entry: contains , the order of the th differential equation, for .
-
4:
– Integer
Input
-
On entry: the number of boundary conditions at .
-
5:
– double
Input/Output
Note: the dimension,
dim, of the array
dgbdy
is
.
where appears in this document, it refers to the array element .
On entry: set to zero.
On exit: must contain the partial derivative of with respect to , for , and . Only nonzero partial derivatives need be set.
-
6:
– Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to
gbjac.
- user – double *
- iuser – Integer *
- p – Pointer
The type Pointer will be
void *. Before calling
d02tlc you may allocate memory and initialize these pointers with various quantities for use by
gbjac when called from
d02tlc (see
Section 3.1.1 in the Introduction to the NAG Library CL Interface).
Note: gbjac should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by
d02tlc. If your code inadvertently
does return any NaNs or infinities,
d02tlc is likely to produce unexpected results.
-
7:
– function, supplied by the user
External Function
-
guess must return initial approximations for the solution components
and the derivatives
, for
and
. Try to compute each derivative
such that it corresponds to your approximations to
, for
. You should
not call
ffun to compute
.
If
d02tlc is being used in conjunction with
d02txc as part of a continuation process,
guess is not called by
d02tlc after the call to
d02txc.
The specification of
guess is:
void |
guess (double x,
Integer neq,
const Integer m[],
double y[],
double dym[],
Nag_Comm *comm)
|
|
-
1:
– double
Input
-
On entry: , the independent variable; .
-
2:
– Integer
Input
-
On entry: the number of differential equations.
-
3:
– const Integer
Input
-
On entry: contains , the order of the th differential equation, for .
-
4:
– double
Output
Note: the dimension,
dim, of the array
y
is
.
where appears in this document, it refers to the array element
.
On exit: must contain , for and .
Note: .
-
5:
– double
Output
-
On exit: must contain , for .
-
6:
– Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to
guess.
- user – double *
- iuser – Integer *
- p – Pointer
The type Pointer will be
void *. Before calling
d02tlc you may allocate memory and initialize these pointers with various quantities for use by
guess when called from
d02tlc (see
Section 3.1.1 in the Introduction to the NAG Library CL Interface).
Note: guess should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by
d02tlc. If your code inadvertently
does return any NaNs or infinities,
d02tlc is likely to produce unexpected results.
-
8:
– double
Communication Array
-
Note: the dimension,
, of this array is dictated by the requirements of associated functions that must have been previously called. This array MUST be the same array passed as argument
rcomm in the previous call to
d02tvc.
On entry: this must be the same array as supplied to
d02tvc and
must remain unchanged between calls.
On exit: contains information about the solution for use on subsequent calls to associated functions.
-
9:
– Integer
Communication Array
-
Note: the dimension,
, of this array is dictated by the requirements of associated functions that must have been previously called. This array MUST be the same array passed as argument
icomm in the previous call to
d02tvc.
On entry: this must be the same array as supplied to
d02tvc and
must remain unchanged between calls.
On exit: contains information about the solution for use on subsequent calls to associated functions.
-
10:
– Nag_Comm *
-
The NAG communication argument (see
Section 3.1.1 in the Introduction to the NAG Library CL Interface).
-
11:
– 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_ALLOC_FAIL
-
Dynamic memory allocation failed.
See
Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
- NE_BAD_PARAM
-
On entry, argument had an illegal value.
- NE_CONVERGENCE_SOL
-
All Newton iterations that have been attempted have failed to converge.
No results have been generated. Check the coding of the functions for calculating the Jacobians of system and boundary conditions.
Try to provide a better initial solution approximation.
- 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.
See
Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
- NE_MISSING_CALL
-
Either the setup function has not been called or the communication arrays have become corrupted. No solution will be computed.
- NE_NO_LICENCE
-
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library CL Interface for further information.
- NE_SING_JAC
-
Numerical singularity has been detected in the Jacobian used in the Newton iteration.
No results have been generated. Check the coding of the functions for calculating the Jacobians of system and boundary conditions.
- NW_MAX_SUBINT
-
The expected number of sub-intervals required to continue the computation exceeds the maximum specified: .
Results have been generated which may be useful.
Try increasing this number or relaxing the error requirements.
- NW_NOT_CONVERGED
-
A Newton iteration has failed to converge. The computation has not succeeded but results have been returned for an intermediate mesh on which convergence was achieved.
These results should be treated with extreme caution.
7
Accuracy
The accuracy of the solution is determined by the argument
tols in the prior call to
d02tvc (see
Sections 3 and
9 in
d02tvc for details and advice). Note that error control is applied only to solution components (variables) and not to any derivatives of the solution. An estimate of the maximum error in the computed solution is available by calling
d02tzc.
8
Parallelism and Performance
d02tlc is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
d02tlc 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 function. Please also consult the
Users' Note for your implementation for any additional implementation-specific information.
If
d02tlc returns with
NE_CONVERGENCE_SOL,
NE_SING_JAC,
NW_MAX_SUBINT or
NW_NOT_CONVERGED and the call to
d02tlc was a part of some continuation procedure for which successful calls to
d02tlc have already been made, then it is possible that the adjustment(s) to the continuation parameter(s) between calls to
d02tlc is (are) too large for the problem under consideration. More conservative adjustment(s) to the continuation parameter(s) might be appropriate.
10
Example
The following example is used to illustrate the treatment of a high-order system, control of the error in a derivative of a component of the original system, and the use of continuation. See also
d02tvc,
d02txc,
d02tyc and
d02tzc, for the illustration of other facilities.
Consider the steady flow of an incompressible viscous fluid between two infinite coaxial rotating discs. See
Ascher et al. (1979) and the references therein. The governing equations are
subject to the boundary conditions
where
is the Reynolds number and
are the angular velocities of the disks.
We consider the case of counter-rotation and a symmetric solution, that is
. This problem is more difficult to solve, the larger the value of
. For illustration, we use simple continuation to compute the solution for three different values of
(
). However, this problem can be addressed directly for the largest value of
considered here. Instead of the values suggested in
Section 5 in
d02txc for
nmesh,
ipmesh and
mesh in the call to
d02txc prior to a continuation call, we use every point of the final mesh for the solution of the first value of
, that is we must modify the contents of
ipmesh. For illustrative purposes we wish to control the computed error in
and so recast the equations as
subject to the boundary conditions
For the symmetric boundary conditions considered, there exists an odd solution about
. Hence, to satisfy the boundary conditions, we use the following initial approximations to the solution in
guess:
10.1
Program Text
10.2
Program Data
10.3
Program Results