NAG C Library Function Document

nag_ode_bvp_coll_nlin_setup (d02tvc)


nag_ode_bvp_coll_nlin_setup (d02tvc) is a setup function which must be called prior to the first call of the nonlinear two-point boundary value solver nag_ode_bvp_coll_nlin_solve (d02tlc).


#include <nag.h>
#include <nagd02.h>
void  nag_ode_bvp_coll_nlin_setup (Integer neq, const Integer m[], Integer nlbc, Integer nrbc, Integer ncol, const double tols[], Integer mxmesh, Integer nmesh, const double mesh[], const Integer ipmesh[], double rcomm[], Integer lrcomm, Integer icomm[], Integer licomm, NagError *fail)


nag_ode_bvp_coll_nlin_setup (d02tvc) and its associated functions (nag_ode_bvp_coll_nlin_solve (d02tlc), nag_ode_bvp_coll_nlin_contin (d02txc), nag_ode_bvp_coll_nlin_interp (d02tyc) and nag_ode_bvp_coll_nlin_diag (d02tzc)) solve the two-point boundary value problem for a nonlinear system of ordinary differential equations
y1m1 x = f1 x,y1,y11,,y1m1-1,y2,,ynmn-1 y2m2 x = f2 x,y1,y11,,y1m1-1,y2,,ynmn-1 ynmn x = fn x,y1,y11,,y1m1-1,y2,,ynmn-1  
over an interval a,b subject to p (>0) nonlinear boundary conditions at a and q (>0) nonlinear boundary conditions at b, where p+q = i=1 n mi . Note that yi m x is the mth derivative of the ith solution component. Hence yi 0 x=yix. The left boundary conditions at a are defined as
gizya=0,  i=1,2,,p,  
and the right boundary conditions at b as
g-jzyb=0,  j=1,2,,q,  
where y=y1,y2,,yn and
zyx = y1x, y11 x ,, y1m1-1 x ,y2x,, ynmn-1 x .  
See Section 9 for information on how boundary value problems of a more general nature can be treated.
nag_ode_bvp_coll_nlin_setup (d02tvc) is used to specify an initial mesh, error requirements and other details. nag_ode_bvp_coll_nlin_solve (d02tlc) is then used to solve the boundary value problem.
The solution function nag_ode_bvp_coll_nlin_solve (d02tlc) proceeds as follows. A modified Newton method is applied to the equations
yi mi x-fix,zyx= 0,   i= 1,,n  
and the boundary conditions. To solve these equations numerically the components yi are approximated by piecewise polynomials vij using a monomial basis on the jth mesh sub-interval. The coefficients of the polynomials vij form the unknowns to be computed. Collocation is applied at Gaussian points
vij mi xjk-fixjk,zvxjk=0,  i=1,2,,n,  
where xjk is the kth collocation point in the jth mesh sub-interval. Continuity at the mesh points is imposed, that is
vijxj+1-vi,j+1xj+1=0,  i=1,2,,n,  
where xj+1 is the right-hand end of the jth mesh sub-interval. The linearized collocation equations and boundary conditions, together with the continuity conditions, form a system of linear algebraic equations, an almost block diagonal system which is solved using special linear solvers. To start the modified Newton process, an approximation to the solution on the initial mesh must be supplied via the procedure argument guess of nag_ode_bvp_coll_nlin_solve (d02tlc).
The solver attempts to satisfy the conditions
yi-vi 1.0+vi tols[i-1],  i=1,2,,n, (1)
where vi is the approximate solution for the ith solution component and tols is supplied by you. The mesh is refined by trying to equidistribute the estimated error in the computed solution over all mesh sub-intervals, and an extrapolation-like test (doubling the number of mesh sub-intervals) is used to check for (1).
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).


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
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Keller H B (1992) Numerical Methods for Two-point Boundary-value Problems Dover, New York
Schwartz I B (1983) Estimating regions of existence of unstable periodic orbits using computer-based techniques SIAM J. Sci. Statist. Comput. 20(1) 106–120


1:     neq IntegerInput
On entry: n, the number of ordinary differential equations to be solved.
Constraint: neq1.
2:     m[neq] const IntegerInput
On entry: m[i-1] must contain mi, the order of the ith differential equation, for i=1,2,,n.
Constraint: 1m[i-1]4, for i=1,2,,n.
3:     nlbc IntegerInput
On entry: p, the number of left boundary conditions defined at the left-hand end, a (=mesh[0]).
Constraint: nlbc1.
4:     nrbc IntegerInput
On entry: q, the number of right boundary conditions defined at the right-hand end, b (=mesh[nmesh-1]).
  • nrbc1;
  • nlbc+nrbc=i=1nm[i-1].
5:     ncol IntegerInput
On entry: the number of collocation points to be used in each mesh sub-interval.
Constraint: mmaxncol7, where mmax=maxm[i-1].
6:     tols[neq] const doubleInput
On entry: tols[i-1] must contain the error requirement for the ith solution component.
Constraint: 100×machine precision<tols[i-1]<1.0, for i=1,2,,n.
7:     mxmesh IntegerInput
On entry: the maximum number of mesh points to be used during the solution process.
Constraint: mxmesh2×nmesh-1.
8:     nmesh IntegerInput
On entry: the number of points to be used in the initial mesh of the solution process.
Constraint: nmesh6.
9:     mesh[mxmesh] const doubleInput
On entry: the positions of the initial nmesh mesh points. The remaining elements of mesh need not be set. You should try to place the mesh points in areas where you expect the solution to vary most rapidly. In the absence of any other information the points should be equally distributed on a,b.
mesh[0] must contain the left boundary point, a, and mesh[nmesh-1] must contain the right boundary point, b.
Constraint: mesh[i-1]<mesh[i], for i=1,2,,nmesh-1.
10:   ipmesh[mxmesh] const IntegerInput
On entry: ipmesh[i-1] specifies whether or not the initial mesh point defined in mesh[i-1], for i=1,2,,nmesh, should be a fixed point in all meshes computed during the solution process. The remaining elements of ipmesh need not be set.
Indicates that mesh[i-1] should be a fixed point in all meshes.
Indicates that mesh[i-1] is not a fixed point.
  • ipmesh[0]=1 and ipmesh[nmesh-1]=1, (i.e., the left and right boundary points, a and b, must be fixed points, in all meshes);
  • ipmesh[i-1]=1 or 2, for i=2,3,,nmesh-1.
11:   rcomm[lrcomm] doubleCommunication Array
On exit: contains information for use by nag_ode_bvp_coll_nlin_solve (d02tlc). This must be the same array as will be supplied to nag_ode_bvp_coll_nlin_solve (d02tlc). The contents of this array must remain unchanged between calls.
12:   lrcomm IntegerInput
On entry: the dimension of the array rcomm. If lrcomm=0, a communication array size query is requested. In this case there is an immediate return with communication array dimensions stored in icomm; icomm[0] contains the required dimension of rcomm, while icomm[1] contains the required dimension of icomm.
Constraint: lrcomm=0, or lrcomm51+neq+mxmesh×2+m*+kn-kn+mxmesh/2, where m*=i=1nm[i-1] and kn=ncol×neq.
13:   icomm[licomm] IntegerCommunication Array
On exit: contains information for use by nag_ode_bvp_coll_nlin_solve (d02tlc). This must be the same array as will be supplied to nag_ode_bvp_coll_nlin_solve (d02tlc). The contents of this array must remain unchanged between calls. If lrcomm=0, a communication array size query is requested. In this case, on immediate return, icomm[0] will contain the required dimension for rcomm while icomm[1] will contain the required dimension for icomm.
14:   licomm IntegerInput
On entry: the dimension of the array icomm. If lrcomm=0, a communication array size query is requested. In this case icomm need only be of dimension 2 in order to hold the required communication array dimensions for the given problem and algorithmic parameters.
  • if lrcomm=0, licomm2;
  • otherwise licomm23+neq+mxmesh.
15:   fail NagError *Input/Output
The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

Error Indicators and Warnings

Dynamic memory allocation failed.
See Section in How to Use the NAG Library and its Documentation for further information.
On entry, argument value had an illegal value.
On entry, ipmesh[0] or ipmesh[nmesh-1] does not equal 1.
On entry, ipmesh[i]1 or 2 for some i.
On entry, licomm=value.
Constraint: licommvalue.
On entry, lrcomm=value.
Constraint: lrcomm=0 or lrcommvalue.
On entry, m[value]=value.
Constraint: 1m[i-1]4 for all i.
On entry, neq=value.
Constraint: neq1.
On entry, nmesh=value.
Constraint: nmesh6.
On entry, mxmesh=value and nmesh=value.
Constraint: mxmesh2×nmesh-1.
On entry, ncol=value and maxm[i]=value.
Constraint: maxm[i]ncol7.
On entry, nlbc=value and nrbc=value.
Constraint: nlbc1 and nrbc1.
On entry, nlbc=value, nrbc=value and summ[i]=value.
Constraint: nlbc+nrbc=summ[i].
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 2.7.6 in How to Use the NAG Library and its Documentation for further information.
Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.
On entry, the elements of mesh are not strictly increasing.
On entry, tols[value]=value.
Constraint: tols[i-1]>value for all i.


Not applicable.

Parallelism and Performance

nag_ode_bvp_coll_nlin_setup (d02tvc) is not threaded in any implementation.

Further Comments

For problems where sharp changes of behaviour are expected over short intervals it may be advisable to:
use a large value for ncol;
cluster the initial mesh points where sharp changes in behaviour are expected;
maintain fixed points in the mesh using the argument ipmesh to ensure that the remeshing process does not inadvertently remove mesh points from areas of known interest before they are detected automatically by the algorithm.

Nonseparated Boundary Conditions

A boundary value problem with nonseparated boundary conditions can be treated by transformation to an equivalent problem with separated conditions. As a simple example consider the system
y1=f1x,y1,y2 y2=f2x,y1,y2  
on a,b subject to the boundary conditions
g1y1a=0 g2y2a,y2b=0.  
By adjoining the trivial ordinary differential equation
which implies ra=rb, and letting rb=y2b, say, we have a new system
y1 = f1x,y1,y2 y2 = f2x,y1,y2 r = 0,  
subject to the separated boundary conditions
g1y1a=0 g2y2a,ra=0 y2b-rb=0.  
There is an obvious overhead in adjoining an extra differential equation: the system to be solved is increased in size.

Multipoint Boundary Value Problems

Multipoint boundary value problems, that is problems where conditions are specified at more than two points, can also be transformed to an equivalent problem with two boundary points. Each sub-interval defined by the multipoint conditions can be transformed onto the interval 0,1, say, leading to a larger set of differential equations. The boundary conditions of the transformed system consist of the original boundary conditions and the conditions imposed by the requirement that the solution components be continuous at the interior break-points. For example, consider the equation
y 3 =ft,y,y 1 ,y 2   on  a,c  
subject to the conditions
ya=A yb=B y1c=C  
where a<b<c. This can be transformed to the system
y1 3 = ft,y1,y1 1 ,y1 2 y2 3 = ft,y2,y2 1 ,y2 2   on ​ 0,1  
y1 y   on   a,b y2 y   on   b,c,  
subject to the boundary conditions
y10 = A y11 = B y2 1 1 = C y20 = Bfrom ​ y11=y20 y1 1 1 = y2 1 0 y1 2 1 = y2 2 0.  
In this instance two of the resulting boundary conditions are nonseparated but they may next be treated as described above.

High Order Systems

Systems of ordinary differential equations containing derivatives of order greater than four can always be reduced to systems of order suitable for treatment by nag_ode_bvp_coll_nlin_setup (d02tvc) and its related functions. For example suppose we have the sixth-order equation
y 6 =-y.  
Writing the variables y1=y and y2=y 4  we obtain the system
y1 4 = y2 y2 2 = -y1  
which has maximal order four, or writing the variables y1=y and y2=y 3  we obtain the system
y1 3 = y2 y2 3 = -y1  
which has maximal order three. The best choice of reduction by choosing new variables will depend on the structure and physical meaning of the system. Note that you will control the error in each of the variables y1 and y2. Indeed, if you wish to control the error in certain derivatives of the solution of an equation of order greater than 1, then you should make those derivatives new variables.

Fixed Points and Singularities

The solver function nag_ode_bvp_coll_nlin_solve (d02tlc) employs collocation at Gaussian points in each sub-interval of the mesh. Hence the coefficients of the differential equations are not evaluated at the mesh points. Thus, fixed points should be specified in the mesh where either the coefficients are singular, or the solution has less smoothness, or where the differential equations should not be evaluated. Singular coefficients at boundary points often arise when physical symmetry is used to reduce partial differential equations to ordinary differential equations. These do not pose a direct numerical problem for using this code but they can severely impact its convergence.

Numerical Jacobians

The solver function nag_ode_bvp_coll_nlin_solve (d02tlc) requires an external function fjac to evaluate the partial derivatives of fi with respect to the elements of zy (=y1,y11,,y1 m1-1 ,y2,,yn mn-1 ). In cases where the partial derivatives are difficult to evaluate, numerical approximations can be used. However, this approach might have a negative impact on the convergence of the modified Newton method. You could consider the use of symbolic mathematic packages and/or automatic differentiation packages if available to you.
See Section 10 in nag_ode_bvp_coll_nlin_diag (d02tzc) for an example using numerical approximations to the Jacobian. There central differences are used and each fi is assumed to depend on all the components of z. This requires two evaluations of the system of differential equations for each component of z. The perturbation used depends on the size of each component of z and a minimum quantity dependent on the machine precision. The cost of this approach could be reduced by employing an alternative difference scheme and/or by only perturbing the components of z which appear in the definitions of the fi. A discussion on the choice of perturbation factors for use in finite difference approximations to partial derivatives can be found in Gill et al. (1981).


The following example is used to illustrate the treatment of nonseparated boundary conditions. See also nag_ode_bvp_coll_nlin_solve (d02tlc), nag_ode_bvp_coll_nlin_contin (d02txc), nag_ode_bvp_coll_nlin_interp (d02tyc) and nag_ode_bvp_coll_nlin_diag (d02tzc), for the illustration of other facilities.
The following equations model of the spread of measles. See Schwartz (1983). Under certain assumptions the dynamics of the model can be expressed as
y1=μ-βxy1y3 y2=βxy1y3-y2/λ y3=y2/λ-y3/η  
subject to the periodic boundary conditions
yi0=yi1 ,   i= 1,2,3.  
Here y1,y2 and y3 are respectively the proportions of susceptibles, infectives and latents to the whole population. λ (=0.0279 years) is the latent period, η (=0.01 years) is the infectious period and μ (=0.02) is the population birth rate. βx=β01.0+cos2πx is the contact rate where β0=1575.0.
The nonseparated boundary conditions are treated as described in Section 9 by adjoining the trivial differential equations
y4=0 y5=0 y6=0  
that is y4,y5 and y6 are constants. The boundary conditions of the augmented system can then be posed in the separated form
y10-y40=0 y20-y50=0 y30-y60=0 y11-y41=0 y21-y51=0 y31-y61=0.  
This is a relatively easy problem and an (arbitrary) initial guess of 1 for each component suffices, even though two components of the solution are much smaller than 1.

Program Text

Program Text (d02tvce.c)

Program Data

Program Data (d02tvce.d)

Program Results

Program Results (d02tvce.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0.01 0.02 0.03 0.04 0.05 0.06 0.08 0 0.2 0.4 0.6 0.8 1 1e−08 1e−07 1e−06 1e−05 0.0001 0.001 0.01 0.1 Susceptibles Infectives and Latents Time Example Program Model of Spread of Measles susceptibles infectives latents gnuplot_plot_1 gnuplot_plot_2 gnuplot_plot_3