NAG Library Function Document

nag_ode_bvp_fd_nonlin_gen (d02rac)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     neq – IntegerInput

On entry: $\mathit{n}$, the number of differential equations.

Constraint: $\mathbf{neq}>0$.

2:     deleps – double *Input/Output

On entry: must be given a value which specifies whether continuation is required. If $\mathbf{deleps}\le 0.0$ or $\mathbf{deleps}\ge 1.0$ then it is assumed that continuation is not required. If $0.0<\mathbf{deleps}<1.0$ then it is assumed that continuation is required unless $\mathbf{deleps}<\sqrt{\mathit{machine precision}}$ when an error exit is taken. deleps is used as the increment ${\epsilon }_2-{\epsilon }_1$ (see (4)) and the choice $\mathbf{deleps}=0.1$ is recommended.

On exit: an overestimate of the increment ${\epsilon }_p-{\epsilon }_{p-1}$ (in fact the value of the increment which would have been tried if the restriction ${\epsilon }_p=1$ had not been imposed). If continuation was not requested then $\mathbf{deleps}=0.0$.

If continuation is not requested then jaceps and jacgep may each be replaced by the NAG defined null function pointer NULLFN.

3:     fcn – function, supplied by the userExternal Function

fcn must evaluate the functions $f_i$ (i.e., the derivatives $y_i^{\prime }$) at a general point $x$ for a given value of $\epsilon$, the continuation parameter (see Section 3).

The specification of fcn is:

void  fcn (Integer neq, double x, double eps, const double y[], double f[], Nag_User *comm)

1:     neq – IntegerInput

On entry: $n$, the number of equations.

2:     x – doubleInput

On entry: $x$, the value of the independent variable.

3:     eps – doubleInput

On entry: $\epsilon$, the value of the continuation parameter. This is $1$ if continuation is not being used.

4:     y[neq] – const doubleInput

On entry: $y_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,\mathit{n}$, the values of the dependent variables at $x$.

5:     f[neq] – doubleOutput

On exit: the values of the derivatives $f_{\mathit{i}}$ evaluated at $x$ given $\epsilon$, for $\mathit{i}=1,2,\dots ,\mathit{n}$.

6:     comm – Nag_User *

Pointer to structure of type Nag_User.

p – Pointer 

The type Pointer will be void *. Before calling nag_ode_bvp_fd_nonlin_gen (d02rac) these pointers may be allocated memory and initialized with various quantities for use by comm when called from nag_ode_bvp_fd_nonlin_gen (d02rac).

4:     numbeg – IntegerInput

On entry: the number of left-hand boundary conditions (that is the number involving $y\left(a\right)$ only).

Constraint: $0\le \mathbf{numbeg}<\mathbf{neq}$.

5:     nummix – IntegerInput

On entry: the number of coupled boundary conditions (that is the number involving both $y\left(a\right)$ and $y\left(b\right)$).

Constraint: $0\le \mathbf{nummix}\le \mathbf{neq}-\mathbf{numbeg}$.

6:     g – function, supplied by the userExternal Function

g must evaluate the boundary conditions in equation (3) and place them in the array bc.

The specification of g is:

void  g (Integer neq, double eps, const double ya[], const double yb[], double bc[], Nag_User *comm)

1:     neq – IntegerInput

On entry: $\mathit{n}$, the number of equations.

2:     eps – doubleInput

On entry: $\epsilon$, the value of the continuation parameter. This is $1$ if continuation is not being used.

3:     ya[neq] – const doubleInput

On entry: the value $y_{\mathit{i}}\left(a\right)$, for $\mathit{i}=1,2,\dots ,n$.

4:     yb[neq] – const doubleInput

On entry: the value $y_{\mathit{i}}\left(b\right)$, for $\mathit{i}=1,2,\dots ,n$.

5:     bc[neq] – doubleOutput

On exit: the values $g_{\mathit{i}}\left(y\left(a\right),y\left(b\right),\epsilon \right)$, for $\mathit{i}=1,2,\dots ,n$. These must be ordered as follows:

(i)	first, the conditions involving only $y\left(a\right)$ (see numbeg);
(ii)	next, the nummix coupled conditions involving both $y\left(a\right)$ and $y\left(b\right)$ (see nummix); and,
(iii)	finally, the conditions involving only $y\left(b\right)$ ($\mathbf{neq}-\mathbf{numbeg}-\mathbf{nummix}$).

6:     comm – Nag_User *

Pointer to structure of type Nag_User.

p – Pointer 

The type Pointer will be void *. Before calling nag_ode_bvp_fd_nonlin_gen (d02rac) these pointers may be allocated memory and initialized with various quantities for use by comm when called from nag_ode_bvp_fd_nonlin_gen (d02rac).

7:     init – Nag_MeshSetInput

On entry: indicates whether you wish to supply an initial mesh and approximate solution ($\mathbf{init}=\mathrm{Nag\_UserInitMesh}$) or whether default values are to be used, ($\mathbf{init}=\mathrm{Nag\_DefInitMesh}$).

Constraint: $\mathbf{init}=\mathrm{Nag\_DefInitMesh}$ or $\mathrm{Nag\_UserInitMesh}$.

8:     mnp – IntegerInput

On entry: mnp must be set to the maximum permitted number of points in the finite difference mesh.

Constraint: $\mathbf{mnp}\ge 32$.

9:     np – Integer *Input/Output

On entry: must be set to the number of points to be used in the initial mesh.

Constraint: $4\le \mathbf{np}\le \mathbf{mnp}$.

On exit: the number of points in the final mesh.

10:   x[mnp] – doubleInput/Output

On entry: you must set $\mathbf{x}\left[0\right]=a$ and $\mathbf{x}\left[\mathbf{np}-1\right]=b$. If $\mathbf{init}=\mathrm{Nag\_DefInitMesh}$ on entry a default equispaced mesh will be used, otherwise you must specify a mesh by setting $\mathbf{x}\left[\mathit{i}-1\right]=x_{\mathit{i}}$, for $\mathit{i}=2,3,\dots ,\mathbf{np}-1$.

Constraints:

• if $\mathbf{init}=\mathrm{Nag\_DefInitMesh}$, $\mathbf{x}\left[0\right]<\mathbf{x}\left[\mathbf{np}-1\right]$;
• if $\mathbf{init}=\mathrm{Nag\_UserInitMesh}$, $\mathbf{x}\left[0\right]<\mathbf{x}\left[1\right]<\cdots <\mathbf{x}\left[\mathbf{np}-1\right]$.

On exit: $\mathbf{x}\left[0\right],\mathbf{x}\left[1\right],\dots ,\mathbf{x}\left[\mathbf{np}-1\right]$ define the final mesh (with the returned value of np) and $\mathbf{x}\left[0\right]=a$ and $\mathbf{x}\left[\mathbf{np}-1\right]=b$.

11:   y[$\mathbf{neq}\times \mathbf{mnp}$] – doubleInput/Output

On entry: if $\mathbf{init}=\mathrm{Nag\_DefInitMesh}$, then y need not be set.

If $\mathbf{init}=\mathrm{Nag\_UserInitMesh}$, then the array y must contain an initial approximation to the solution such that $\mathbf{y}\left[\left(j-1\right)\times \mathbf{mnp}+i-1\right]$ contains an approximation to

$$y_j\left(x_i\right)\text{, \hspace{1em}}i=1,2,\dots ,\mathbf{np}\text{ and }j=1,2,\dots ,n\text{.}$$

On exit: the approximate solution $z_j\left(x_i\right)$ satisfying (5) on the final mesh, that is

$$\mathbf{y}\left[\left(j-1\right)\times \mathbf{mnp}+i-1\right]=z_j\left(x_i\right)\text{, \hspace{1em}}i=1,2,\dots ,\mathbf{np}\text{ and }j=1,2,\dots ,n\text{,}$$

where np is the number of points in the final mesh. If an error has occurred then y contains the latest approximation to the solution. The remaining columns of y are not used.

12:   tol – doubleInput

On entry: a positive absolute error tolerance. If

$$a=x_1<x_2<\cdots <x_{\mathbf{np}}=b$$

is the final mesh, $z_j\left(x_i\right)$ is the $j$th component of the approximate solution at $x_i$, and $y_j\left(x\right)$ is the $j$th component of the true solution of (1) and (2), then, except in extreme circumstances, it is expected that

$$\left|z_j\left(x_i\right)-y_j\left(x_i\right)\right|\le \mathbf{tol}\text{, \hspace{1em}}i=1,2,\dots ,\mathbf{np}\text{ and }j=1,2,\dots ,n\text{.}$$

(5)

Constraint: $\mathbf{tol}>0.0$.

13:   abt[neq] – doubleOutput

On exit: $\mathbf{abt}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,n$, holds the largest estimated error (in magnitude) of the $i$th component of the solution over all mesh points.

14:   jacobf – function, supplied by the userExternal Function

jacobf evaluates the Jacobian $\left(\frac{\partial f_{\mathit{i}}}{\partial y_{\mathit{j}}}\right)$, for $\mathit{i}=1,2,\dots ,n$ and $\mathit{j}=1,2,\dots ,n$, given $x$ and $y_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,n$.

If all Jacobians are to be approximated internally by numerical differentiation then it must be replaced by the NAG defined null function pointer NULLFN.

The specification of jacobf is:

void  jacobf (Integer neq, double x, double eps, const double y[], double f[], Nag_User *comm)

1:     neq – IntegerInput

On entry: $\mathit{n}$, the number of equations.

2:     x – doubleInput

On entry: $x$, the value of the independent variable.

3:     eps – doubleInput

On entry: $\epsilon$, the value of the continuation parameter. This is $1$ if continuation is not being used.

4:     y[neq] – const doubleInput

On entry: $y_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,\mathit{n}$, the values of the dependent variables at $x$.

5:     f[$\mathbf{neq}\times \mathbf{neq}$] – doubleOutput

On exit: $\mathbf{f}\left[\left(\mathit{j}-1\right)\times \mathbf{neq}+\mathit{i}-1\right]$ must be set to the value of $\frac{\partial f_{\mathit{i}}}{\partial y_{\mathit{j}}}$, evaluated at the point $\left(x,y\right)$, for $\mathit{i}=1,2,\dots ,n$ and $\mathit{j}=1,2,\dots ,n$.

6:     comm – Nag_User *

Pointer to structure of type Nag_User.

p – Pointer 

The type Pointer will be void *. Before calling nag_ode_bvp_fd_nonlin_gen (d02rac) these pointers may be allocated memory and initialized with various quantities for use by comm when called from nag_ode_bvp_fd_nonlin_gen (d02rac).

Note that if jacobf is supplied then jacobg must also be supplied. Note that if jacobf is supplied and continuation is requested then jaceps and jacgep must also be supplied.

15:   jacobg – function, supplied by the userExternal Function

jacobg evaluates the Jacobians $\left(\frac{\partial g_i}{\partial y_j\left(a\right)}\right)$ and $\left(\frac{\partial g_i}{\partial y_j\left(b\right)}\right)$. The ordering of the rows of aj and bj must correspond to the ordering of the boundary conditions described in the specification of g.

If all Jacobians are to be approximated internally by numerical differentiation then it must be replaced by the NAG defined null function pointer NULLFN.

The specification of jacobg is:

void  jacobg (Integer neq, double eps, const double ya[], const double yb[], double aj[], double bj[], Nag_User *comm)

1:     neq – IntegerInput

On entry: $\mathit{n}$, the number of equations.

2:     eps – doubleInput

On entry: $\epsilon$, the value of the continuation parameter. This is $1$ if continuation is not being used.

3:     ya[neq] – const doubleInput

On entry: the value $y_{\mathit{i}}\left(a\right)$, for $\mathit{i}=1,2,\dots ,n$.

4:     yb[neq] – const doubleInput

On entry: the value $y_{\mathit{i}}\left(b\right)$, for $\mathit{i}=1,2,\dots ,n$.

5:     aj[$\mathbf{neq}\times \mathbf{neq}$] – doubleOutput

On exit: $\mathbf{aj}\left[\left(\mathit{i}-1\right)\times \mathbf{neq}+\mathit{j}-1\right]$ must be set to the value $\frac{\partial g_{\mathit{i}}}{\partial y_{\mathit{j}}\left(a\right)}$, for $\mathit{i}=1,2,\dots ,n$ and $\mathit{j}=1,2,\dots ,n$.

6:     bj[$\mathbf{neq}\times \mathbf{neq}$] – doubleOutput

On exit: $\mathbf{bj}\left[\left(\mathit{i}-1\right)\times \mathbf{neq}+\mathit{j}-1\right]$ must be set to the value $\frac{\partial g_{\mathit{i}}}{\partial y_{\mathit{j}}\left(b\right)}$, for $\mathit{i}=1,2,\dots ,n$ and $\mathit{j}=1,2,\dots ,n$.

7:     comm – Nag_User *

Pointer to structure of type Nag_User.

p – Pointer 

The type Pointer will be void *. Before calling nag_ode_bvp_fd_nonlin_gen (d02rac) these pointers may be allocated memory and initialized with various quantities for use by comm when called from nag_ode_bvp_fd_nonlin_gen (d02rac).

Note that if jacobg is supplied then jacobf must also be supplied.

16:   jaceps – function, supplied by the userExternal Function

jaceps evaluates the derivative $\frac{\partial f_i}{\partial \epsilon }$ given $x$ and $y$ if continuation is being used.

If all Jacobians (derivatives) are to be approximated internally by numerical differentiation, or continuation is not being used, then it must be replaced by the NAG defined null function pointer NULLFN.

The specification of jaceps is:

void  jaceps (Integer neq, double x, double eps, const double y[], double f[], Nag_User *comm)

1:     neq – IntegerInput

On entry: $\mathit{n}$, the number of equations.

2:     x – doubleInput

On entry: $x$, the value of the independent variable.

3:     eps – doubleInput

On entry: $\epsilon$, the value of the continuation parameter.

4:     y[neq] – const doubleInput

On entry: the solution values $y_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$, at the point $x$.

5:     f[neq] – doubleOutput

On exit: $\mathbf{f}\left[\mathit{i}-1\right]$ must contain the value $\frac{\partial f_{\mathit{i}}}{\partial \epsilon }$ at the point $\left(x,y\right)$, for $\mathit{i}=1,2,\dots ,n$.

6:     comm – Nag_User *

Pointer to structure of type Nag_User.

p – Pointer 

The type Pointer will be void *. Before calling nag_ode_bvp_fd_nonlin_gen (d02rac) these pointers may be allocated memory and initialized with various quantities for use by comm when called from nag_ode_bvp_fd_nonlin_gen (d02rac).

Note that if jaceps is defined then jacgep must also be defined.

17:   jacgep – function, supplied by the userExternal Function

jacgep evaluates the derivatives $\frac{\partial g_i}{\partial \epsilon }$ if continuation is being used.

If all Jacobians (derivatives) are to be approximated internally by numerical differentiation, or continuation is not being used, then it must be replaced by the NAG defined null function pointer NULLFN.

The specification of jacgep is:

void  jacgep (Integer neq, double eps, const double ya[], const double yb[], double bcep[], Nag_User *comm)

1:     neq – IntegerInput

On entry: $\mathit{n}$, the number of equations.

2:     eps – doubleInput

On entry: $\epsilon$, the value of the continuation parameter.

3:     ya[neq] – const doubleInput

On entry: the value of $y_{\mathit{i}}\left(a\right)$, for $\mathit{i}=1,2,\dots ,n$.

4:     yb[neq] – const doubleInput

On entry: the value of $y_{\mathit{i}}\left(b\right)$, for $\mathit{i}=1,2,\dots ,n$.

5:     bcep[neq] – doubleOutput

On exit: $\mathbf{bcep}\left[\mathit{i}-1\right]$ must contain the value of $\frac{\partial g_{\mathit{i}}}{\partial \epsilon }$, for $\mathit{i}=1,2,\dots ,n$.

6:     comm – Nag_User *

Pointer to structure of type Nag_User.

p – Pointer 

The type Pointer will be void *. Before calling nag_ode_bvp_fd_nonlin_gen (d02rac) these pointers may be allocated memory and initialized with various quantities for use by comm when called from nag_ode_bvp_fd_nonlin_gen (d02rac).

Note that if jacgep is defined then jaceps must also be defined.

18:   comm – Nag_User *

Pointer to structure of type Nag_User.

p – Pointer 

The type Pointer will be void *. Before calling nag_ode_bvp_fd_nonlin_gen (d02rac) these pointers may be allocated memory and initialized with various quantities for use by comm when called from nag_ode_bvp_fd_nonlin_gen (d02rac).

19:   fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_2_INT_ARG_ZERO

On entry, $\mathbf{numbeg}=0$ and $\mathbf{nummix}=0$. These arguments must not both be zero.

NE_2_REAL_ARG_LE

On entry, $\mathbf{x}\left[0\right]=⟨\mathit{\text{value}}⟩$ and $\mathbf{x}\left[\mathbf{np}-1\right]=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{x}\left[0\right]<\mathbf{x}\left[\mathbf{np}-1\right]$.

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument init had an illegal value.

NE_CONV_CONT

Convergence failure. There are a number of possible causes.

(a)	Faulty coding of the Jacobian calculation functions.
(b)	If Jacobians have not been supplied then inaccurate Jacobians have been calculated internally (not very likely).
(c)	A poor choice of initial mesh or initial starting conditions either by the user or by default. Try using the continuation facility.

The Newton iteration has failed to converge.
This could be due to there being too few points in the initial mesh or to the initial approximate solution being too inaccurate.
If this latter reason is suspected or you cannot make changes to prevent this error, you should use the function with a continuation facility instead.

NE_CONV_CONT_DELEPS

deleps is required to be less than machine precision for continuation to proceed. It is likely that either the problem has no solution for some value near the current value of $\epsilon$ or that the problem is so difficult that even with continuation it is unlikely to be solved using this function. Using more mesh points may help.

The continuation step is required to be less than machine precision for continuation to proceed. It is likely that either the problem has no solution for some value of the continuation parameter near the current value or that the problem is so difficult that even with continuation it is unlikely to be solved using this function. In the latter case using more mesh points initially may help.

NE_CONV_CONT_DEP

There is no dependence on the continuation parameter when continuation is being used. This can be due to faulty coding of derivatives with respect to the continuation parameter or to a zero initial choice of approximate solution.

There is no dependence on $\epsilon$ when continuation is being used. This may be due to faulty coding of jaceps or jacgep, or in some circumstances, to a zero initial choice of approximate solution (such as is chosen when $\mathbf{init}=\mathrm{Nag\_DefInitMesh}$).

NE_CONV_JACOBG

The Jacobian calculated by jacobg (or the equivalent matrix calculated by numerical differentiation) is singular. This may be due to faulty coding of jacobg or in some circumstances, to a zero initial choice of approximate solution (such as is chosen when $\mathbf{init}=\mathrm{Nag\_DefInitMesh}$).

The Jacobian for the boundary conditions is singular.
This may occur due to faulty coding of the Jacobian or, in some circumstances, to a zero initial choice of approximate solution.

NE_CONV_MESH

A finer mesh is required for the accuracy requested; that is, $\mathbf{mnp}=⟨\mathit{\text{value}}⟩$ is not large enough.

NE_CONV_ROUNDOFF

Newton iteration has reached round-off level.
If desired accuracy has not been reached, then tol is too small for this problem and this machine precision.

Solution cannot be improved due to roundoff error. Too much accuracy might have been requested.

NE_INT_ARG_LT

On entry, $\mathbf{mnp}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{mnp}\ge 32$.

On entry, $\mathbf{neq}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{neq}\ge 1$.

On entry, $\mathbf{np}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{np}\ge 4$.

On entry, $\mathbf{numbeg}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{numbeg}\ge 0$.

On entry, $\mathbf{nummix}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nummix}\ge 0$.

NE_INT_RANGE_CONS

On entry, $\mathbf{np}=⟨\mathit{\text{value}}⟩$ and $\mathbf{mnp}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{np}\le \mathbf{mnp}$.

On entry, $\mathbf{numbeg}=⟨\mathit{\text{value}}⟩$ and $\mathbf{neq}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{numbeg}<\mathbf{neq}$.

On entry, $\mathbf{numbeg}=⟨\mathit{\text{value}}⟩$, $\mathbf{nummix}=⟨\mathit{\text{value}}⟩$
and $\mathbf{neq}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{numbeg}+\mathbf{nummix}\le \mathbf{neq}$.

NE_INTERNAL_ERROR

A continuation error occurred, but continuation is not being used.
Please contact NAG.

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.

A serious error occurred in a call to the internal integrator.
The error code internally was $⟨\mathit{\text{value}}⟩$.
Please contact NAG.

NE_INVALID_FUN_JAC

Only one of jacobf or jacobg has been set to non-null possibly implying user-defined Jacobians. Both must be non-null.

NE_INVALID_FUN_JAC_CONT

deleps has been set to $⟨\mathit{\text{value}}⟩$ implying continuation and both jacobf and jacobg have been set to non-null implying user-defined Jacobians. Hence the functions jaceps and jacgep must also be non-null.

NE_INVALID_FUN_JAC_NO_CONT

deleps has been set to $⟨\mathit{\text{value}}⟩$ implying no continuation and both jacobf and jacobg have been set to non-null implying user-defined Jacobians. Hence the functions jaceps and jacgep must be NULL.

NE_INVALID_FUN_NO_JAC_CONT

deleps has been set to $⟨\mathit{\text{value}}⟩$ implying continuation and both jacobf and jacobg have been set to NULL implying no user-defined Jacobians. Hence the functions jaceps and jacgep must also be NULL.

NE_NOT_STRICTLY_INCREASING

On entry the mesh points are not in strictly ascending order.
For $i=⟨\mathit{\text{value}}⟩$, mesh point $i=⟨\mathit{\text{value}}⟩$, but mesh point $i+1=⟨\mathit{\text{value}}⟩$.

NE_REAL_ARG_LE

On entry, $\mathbf{tol}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{tol}>0.0$.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (d02race.c)

10.2  Program Data

10.3  Program Results

Program Results (d02race.r)