naginterfaces.library.ode.bvp_fd_nonlin_gen¶

naginterfaces.library.ode.bvp_fd_nonlin_gen(np, numbeg, nummix, tol, init, x, y, fcn, g, ijac, deleps, itrace, comm, jacobf=None, jacobg=None, jaceps=None, jacgep=None, data=None, io_manager=None, spiked_sorder='C')[source]¶

bvp_fd_nonlin_gen solves a two-point boundary value problem with general boundary conditions for a system of ordinary differential equations, using a deferred correction technique and Newton iteration.

For full information please refer to the NAG Library document for d02ra

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/d02/d02raf.html

Parameters

npint

Must be set to the number of points to be used in the initial mesh.

numbegint

The number of left-hand boundary conditions (that is the number involving $y (a)$ only).

nummixint

The number of coupled boundary conditions (that is the number involving both $y (a)$ and $y (b)$ ).

tolfloat

A positive absolute error tolerance. If

a = x_{1} < x_{2} < \dots < x_{n p} = 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)$ is the $j$ th component of the true solution of (1) and (2), then, except in extreme circumstances, it is expected that

∣ ∣ z_{j} (x_{i}) - y_{j} (x_{i}) ∣ ∣ \leq t o l, i = 1, 2, \dots, n p and j = 1, 2, \dots, n .

initint

Indicates whether you wish to supply an initial mesh and approximate solution ( $i n i t = 1$ ) or whether default values are to be used, ( $i n i t = 0$ ).

xfloat, array-like, shape $(mnp)$

You must set $x [0] = a$ and $x [n p - 1] = b$ . If $i n i t = 0$ on entry a default equispaced mesh will be used, otherwise you must specify a mesh by setting $x [i - 1] = x_{i}$ , for $i = 2, 3, \dots, n p - 1$ .

yfloat, array-like, shape $(n, mnp)$

If $i n i t = 0$ , $y$ need not be set.

If $i n i t = 1$ , the array $y$ must contain an initial approximation to the solution such that $y [j - 1, i - 1]$ contains an approximation to

y_{j} (x_{i}), i = 1, 2, \dots, n p and j = 1, 2, \dots, n .

fcncallable f = fcn(x, eps, y, data=None)

$f c n$ must evaluate the functions $f_{i}$ (i.e., the derivatives $y_{i}^{'}$ ) at a general point $x$ for a given value of $ϵ$ , the continuation parameter (see Notes).

Parameters

xfloat: $x$ , the value of the independent variable.
epsfloat: $ϵ$ , the value of the continuation parameter. This is $1$ if continuation is not being used.
yfloat, ndarray, shape $(n)$: $y_{i}$ , for $i = 1, 2, \dots, n$ , the values of the dependent variables at $x$ .
dataarbitrary, optional, modifiable in place: User-communication data for callback functions.

Returns

ffloat, array-like, shape $(n)$: The values of the derivatives $f_{i}$ evaluated at $x$ given $ϵ$ , for $i = 1, 2, \dots, n$ .

gcallable bc = g(eps, ya, yb, data=None)

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

Parameters

epsfloat: $ϵ$ , the value of the continuation parameter. This is $1$ if continuation is not being used.
yafloat, ndarray, shape $(n)$: The value $y_{i} (a)$ , for $i = 1, 2, \dots, n$ .
ybfloat, ndarray, shape $(n)$: The value $y_{i} (b)$ , for $i = 1, 2, \dots, n$ .
dataarbitrary, optional, modifiable in place: User-communication data for callback functions.

Returns

bcfloat, array-like, shape $(n)$

The values $g_{i} (y (a), y (b), ϵ)$ , for $i = 1, 2, \dots, n$ . These must be ordered as follows:

first, the conditions involving only $y (a)$ (see $n u m b e g$ );
next, the $n u m m i x$ coupled conditions involving both $y (a)$ and $y (b)$ (see $n u m m i x$ ); and,
finally, the conditions involving only $y (b)$ ( $n - n u m b e g - n u m m i x$ ).

ijacint

Indicates whether or not you are supplying Jacobian evaluation functions.

$i j a c \neq 0$

You must supply $j a c o b f$ and $j a c o b g$ and also, when continuation is used, $j a c e p s$ and $j a c g e p$ .

$i j a c = 0$

Numerical differentiation is used to calculate the Jacobian and None may be used for the respective callbacks.

delepsfloat

Must be given a value which specifies whether continuation is required. If $d e l e p s \leq 0.0$ or $d e l e p s \geq 1.0$ then it is assumed that continuation is not required. If $0.0 < d e l e p s < 1.0$ then it is assumed that continuation is required unless $d e l e p s < \sqrt{machine precision}$ when an error exit is taken. $d e l e p s$ is used as the increment $ϵ_{2} - ϵ_{1}$ (see (4)) and the choice $d e l e p s = 0.1$ is recommended.

itraceint

If $i t r a c e = 0$ warning messages be suppressed, otherwise warning messages will be printed (see Exceptions).

commdict, communication object, modified in place

Communication structure.

On initial entry: need not be set.

jacobfNone or callable f = jacobf(x, eps, y, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

$j a c o b f$ evaluates the Jacobian $(\frac{\partial f_{i}}{\partial y_{j}})$ , for $j = 1, 2, \dots, n$ , for $i = 1, 2, \dots, n$ , given $x$ and $y_{j}$ , for $j = 1, 2, \dots, n$ .

If $i j a c = 0$ , numerical differentiation is used to calculate the Jacobian.

Parameters

xfloat: $x$ , the value of the independent variable.
epsfloat: $ϵ$ , the value of the continuation parameter. This is $1$ if continuation is not being used.
yfloat, ndarray, shape $(n)$: $y_{i}$ , for $i = 1, 2, \dots, n$ , the values of the dependent variables at $x$ .
dataarbitrary, optional, modifiable in place: User-communication data for callback functions.

Returns

ffloat, array-like, shape $(n, n)$: $f [j - 1, i - 1]$ must be set to the value of $\frac{\partial f_{i}}{\partial y_{j}}$ , evaluated at the point $(x, y)$ , for $j = 1, 2, \dots, n$ , for $i = 1, 2, \dots, n$ .

jacobgNone or callable (aj, bj) = jacobg(eps, ya, yb, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

$j a c o b g$ evaluates the Jacobians $(\frac{\partial g_{i}}{\partial y_{j} (a)})$ and $(\frac{\partial g_{i}}{\partial y_{j} (b)})$ .

The ordering of the rows of $a j$ and $b j$ must correspond to the ordering of the boundary conditions described in the specification of $g$ .

If $i j a c = 0$ , numerical differentiation is used to calculate the Jacobian.

Parameters

epsfloat: $ϵ$ , the value of the continuation parameter. This is $1$ if continuation is not being used.
yafloat, ndarray, shape $(n)$: The value $y_{i} (a)$ , for $i = 1, 2, \dots, n$ .
ybfloat, ndarray, shape $(n)$: The value $y_{i} (b)$ , for $i = 1, 2, \dots, n$ .
dataarbitrary, optional, modifiable in place: User-communication data for callback functions.

Returns

ajfloat, array-like, shape $(n, n)$: $a j [i - 1, j - 1]$ must be set to the value $\frac{\partial g_{i}}{\partial y_{j} (a)}$ , for $j = 1, 2, \dots, n$ , for $i = 1, 2, \dots, n$ .
bjfloat, array-like, shape $(n, n)$: $b j [i - 1, j - 1]$ must be set to the value $\frac{\partial g_{i}}{\partial y_{j} (b)}$ , for $j = 1, 2, \dots, n$ , for $i = 1, 2, \dots, n$ .

jacepsNone or callable f = jaceps(x, eps, y, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

$j a c e p s$ evaluates the derivative $\frac{\partial f_{i}}{\partial ϵ}$ given $x$ and $y$ if continuation is being used.

Parameters

xfloat: $x$ , the value of the independent variable.
epsfloat: $ϵ$ , the value of the continuation parameter.
yfloat, ndarray, shape $(n)$: The solution values $y_{i}$ , for $i = 1, 2, \dots, n$ , at the point $x$ .
dataarbitrary, optional, modifiable in place: User-communication data for callback functions.

Returns

ffloat, array-like, shape $(n)$: $f [i - 1]$ must contain the value $\frac{\partial f_{i}}{\partial ϵ}$ at the point $(x, y)$ , for $i = 1, 2, \dots, n$ .

jacgepNone or callable bcep = jacgep(eps, ya, yb, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

$j a c g e p$ evaluates the derivatives $\frac{\partial g_{i}}{\partial ϵ}$ if continuation is being used.

Parameters

epsfloat: $ϵ$ , the value of the continuation parameter.
yafloat, ndarray, shape $(n)$: The value of $y_{i} (a)$ , for $i = 1, 2, \dots, n$ .
ybfloat, ndarray, shape $(n)$: The value of $y_{i} (b)$ , for $i = 1, 2, \dots, n$ .
dataarbitrary, optional, modifiable in place: User-communication data for callback functions.

Returns

bcepfloat, array-like, shape $(n)$: $b c e p [i - 1]$ must contain the value of $\frac{\partial g_{i}}{\partial ϵ}$ , for $i = 1, 2, \dots, n$ .

dataarbitrary, optional

User-communication data for callback functions.

io_managerFileObjManager, optional

Manager for I/O in this routine.

spiked_sorderstr, optional

If $y$ is spiked (i.e., has unit extent in all but one dimension, or has size $1$ ), $s p i k e d_s o r d e r$ selects the storage order to associate with it in the NAG Engine:

spiked_sorder = $'C'$: row-major storage will be used;
spiked_sorder = $'F'$: column-major storage will be used.

Two-dimensional arrays returned from callback functions in this routine must then use the same storage order.

Returns

npint

The number of points in the final mesh.

xfloat, ndarray, shape $(mnp)$

$x [0], x [1], \dots, x [n p - 1]$ define the final mesh (with the returned value of $n p$ ) and $x [0] = a$ and $x [n p - 1] = b$ .

yfloat, ndarray, shape $(n, mnp)$

The approximate solution $z_{j} (x_{i})$ satisfying (5) on the final mesh, that is

y [j - 1, i - 1] = z_{j} (x_{i}), i = 1, 2, \dots, n p and j = 1, 2, \dots, n,

where $n p$ 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.

abtfloat, ndarray, shape $(n)$

$a b t [i - 1]$ , for $i = 1, 2, \dots, n$ , holds the largest estimated error (in magnitude) of the $i$ th component of the solution over all mesh points.

delepsfloat

An overestimate of the increment $ϵ_{p} - ϵ_{p - 1}$ (in fact the value of the increment which would have been tried if the restriction $ϵ_{p} = 1$ had not been imposed). If continuation was not requested then $d e l e p s = 0.0$ .

If continuation is not requested then $j a c e p s$ and $j a c g e p$ may each be replaced by None.

Raises

NagValueError

(errno $1$ )

On entry the mesh points are not in strictly ascending order.

For $i = ⟨ v a l u e ⟩$ , mesh point $i = ⟨ v a l u e ⟩$ , but mesh point $i + 1 = ⟨ v a l u e ⟩$ .

(errno $1$ )

On entry, $n u m b e g = ⟨ v a l u e ⟩$ , $n u m m i x = ⟨ v a l u e ⟩$ and $n = ⟨ v a l u e ⟩$ .

Constraint: $n u m b e g + n u m m i x \leq n$ .

(errno $1$ )

On entry, $n u m m i x = ⟨ v a l u e ⟩$ .

Constraint: $n u m m i x \geq 0$ .

(errno $1$ )

On entry, $n u m b e g = ⟨ v a l u e ⟩$ and $n = ⟨ v a l u e ⟩$ .

Constraint: $n u m b e g < n$ .

(errno $1$ )

On entry, $n u m b e g = ⟨ v a l u e ⟩$ .

Constraint: $n u m b e g \geq 0$ .

(errno $1$ )

On entry, $x [0] = ⟨ v a l u e ⟩$ and $x [n p - 1] = ⟨ v a l u e ⟩$ .

Constraint: $x [0] < x [n p - 1]$ .

(errno $1$ )

On entry, $mnp = ⟨ v a l u e ⟩$ .

Constraint: $mnp \geq 32$ .

(errno $1$ )

On entry, $n p = ⟨ v a l u e ⟩$ and $mnp = ⟨ v a l u e ⟩$ .

Constraint: $n p \leq mnp$ .

(errno $1$ )

On entry, $n p = ⟨ v a l u e ⟩$ .

Constraint: $n p \geq 4$ .

(errno $1$ )

On entry, $t o l = ⟨ v a l u e ⟩$ .

Constraint: $t o l > 0.0$ .

(errno $1$ )

On entry, $n = ⟨ v a l u e ⟩$ .

Constraint: $n \geq 1$ .

(errno $2$ )

A finer mesh is required for the accuracy requested; that is, $mnp = ⟨ v a l u e ⟩$ is not large enough.

(errno $3$ )

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.

(errno $5$ )

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.

(errno $6$ )

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.

(errno $7$ )

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.

(errno $8$ )

A serious error occurred in a call to the internal integrator.

The error code internally was $⟨ v a l u e ⟩$ .

Please contact NAG.

(errno $9$ )

A continuation error occurred, but continuation is not being used.

Please contact NAG.

Warns

NagAlgorithmicWarning

(errno $4$ )

Newton iteration has reached round-off level.

If desired accuracy has not been reached, $t o l$ is too small for this problem and this machine precision.

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

bvp_fd_nonlin_gen solves a two-point boundary value problem for a system of $n$ ordinary differential equations in the interval $[a, b]$ with $b > a$ . The system is written in the form

y_{i}^{'} = f_{i} (x, y_{1}, y_{2}, \dots, y_{n}), i = 1, 2, \dots, n

and the derivatives $f_{i}$ are evaluated by $f c n$ . With the differential equations (1) must be given a system of $n$ (nonlinear) boundary conditions

g_{i} (y (a), y (b)) = 0, i = 1, 2, \dots, n,

where

y (x) = {[y_{1} (x), y_{2} (x), \dots, y_{n} (x)]}^{T} .

The functions $g_{i}$ are evaluated by $g$ . The solution is computed using a finite difference technique with deferred correction allied to a Newton iteration to solve the finite difference equations. The technique used is described fully in Pereyra (1979).

You must supply an absolute error tolerance and may also supply an initial mesh for the finite difference equations and an initial approximate solution (alternatively a default mesh and approximation are used). The approximate solution is corrected using Newton iteration and deferred correction. Then, additional points are added to the mesh and the solution is recomputed with the aim of making the error everywhere less than your tolerance and of approximately equidistributing the error 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 submodule interp if these points do not themselves form a convenient mesh.

The Newton iteration requires Jacobian matrices

(\frac{\partial f_{i}}{\partial y_{j}}), (\frac{\partial g_{i}}{\partial y_{j} (a)}) and (\frac{\partial g_{i}}{\partial y_{j} (b)}) .

These may be supplied through $j a c o b f$ for $(\frac{\partial f_{i}}{\partial y_{j}})$ and $j a c o b g$ for the others. Alternatively the Jacobians may be calculated by numerical differentiation using the algorithm described in Curtis et al. (1974).

For problems of the type (1) and (2) for which it is difficult to determine an initial approximation from which the Newton iteration will converge, a continuation facility is provided. You must set up a family of problems

y^{'} = f (x, y, ϵ), g (y (a), y (b), ϵ) = 0,

where $f = {[f_{1}, f_{2}, \dots, f_{n}]}_{1}^{T}$ etc., and where $ϵ$ is a continuation parameter. The choice $ϵ = 0$ must give a problem (3) which is easy to solve and $ϵ = 1$ must define the problem whose solution is actually required. The function solves a sequence of problems with $ϵ$ values

0 = ϵ_{1} < ϵ_{2} < \dots < ϵ_{p} = 1 .

The number $p$ and the values $ϵ_{i}$ are chosen by the function so that each problem can be solved using the solution of its predecessor as a starting approximation. Jacobians $\frac{\partial f}{\partial ϵ}$ and $\frac{\partial g}{\partial ϵ}$ are required and they may be supplied by you via $j a c e p s$ and $j a c g e p$ respectively or may be computed by numerical differentiation.

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

NAG and Python

Return to Front

naginterfaces.library.ode.bvp_fd_nonlin_gen¶

naginterfaces.library.ode.bvp_​fd_​nonlin_​gen¶

naginterfaces.library.ode.bvp_fd_nonlin_gen¶