naginterfaces.library.ode.bvp_​fd_​lin_​gen

naginterfaces.library.ode.bvp_fd_lin_gen(a, b, tol, fcnf, fcng, c, d, gam, x, np, itrace, comm, data=None, io_manager=None, spiked_sorder='C')

bvp_fd_lin_gen solves a general linear two-point boundary value problem for a system of ordinary differential equations, using a deferred correction technique.

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

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

Parameters

afloat

$a$, the left-hand boundary point.

bfloat

$b$, the right-hand boundary point.

tolfloat

A positive absolute error tolerance. If

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

is the final mesh, $z\left(x\right)$ is the approximate solution from bvp_fd_lin_gen and $y\left(x\right)$ is the true solution of equations (1) and (2) then, except in extreme cases, it is expected that

$$\parallel z-y\parallel \le tol$$

where

$$\parallel u\parallel ={max}_{1\le i\le n}{max}_{1\le j\le np}\left|u_i\left(x_j\right)\right|\text{.}$$

fcnfcallable f = fcnf(n, x, data=None)

$fcnf$ must evaluate the matrix $F\left(x\right)$ in (1) at a general point $x$.

Parameters

nint

$\text{n}$, the number of equations.

xfloat

$x$, the value of the independent variable.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

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

$f[\text{j}-1,\text{i}-1]$ must contain the $(\text{i},\text{j})$th element of the matrix $F\left(x\right)$, for $\text{j}=1,2,\dots ,\text{n}$, for $\text{i}=1,2,\dots ,\text{n}$.

fcngcallable g = fcng(n, x, data=None)

$fcng$ must evaluate the vector $g\left(x\right)$ in (1) at a general point $x$.

Parameters

nint

$\text{n}$, the number of equations.

xfloat

$x$, the value of the independent variable.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

gfloat, array-like, shape $\left(n\right)$

The $\text{i}$th element of the vector $g\left(x\right)$, for $\text{i}=1,2,\dots ,\text{n}$.

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

The arrays $c$ and $d$ must be set to the matrices $C$ and $D$ in (2)). $gam$ must be set to the vector $\gamma$ in (2).

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

The arrays $c$ and $d$ must be set to the matrices $C$ and $D$ in (2)). $gam$ must be set to the vector $\gamma$ in (2).

gamfloat, array-like, shape $\left(n\right)$

The arrays $c$ and $d$ must be set to the matrices $C$ and $D$ in (2)). $gam$ must be set to the vector $\gamma$ in (2).

xfloat, array-like, shape $\left(\text{mnp}\right)$

If $np\ge 4$ (see $np$), the first $np$ elements must define an initial mesh. Otherwise the elements of $x$ need not be set.

npint

Determines whether a default mesh or user-supplied mesh is used.

$np=0$

A default value of $4$ for $np$ and a corresponding equispaced mesh $x\left[0\right],x\left[1\right],\dots ,x[np-1]$ are used.

$np\ge 4$

You must define an initial mesh $x$ as in [equation].

itraceint

If $itrace=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.

dataarbitrary, optional

User-communication data for callback functions.

io_managerFileObjManager, optional

Manager for I/O in this routine.

spiked_sorderstr, optional

If $c$ and $d$ are spiked (i.e., have unit extent in all but one dimension, or have size $1$), $spiked\_sorder$ selects the storage order to associate with them in the NAG Engine:

spiked_sorder = $\text{'C'}$

row-major storage will be used;

spiked_sorder = $\text{'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

cfloat, ndarray, shape $(n,n)$

The rows of $c$ and $d$ and the components of $gam$ are reordered so that the boundary conditions are in the order:

1. conditions on $y\left(a\right)$ only;

2. condition involving $y\left(a\right)$ and $y\left(b\right)$; and

3. conditions on $y\left(b\right)$ only.

The function will be slightly more efficient if the arrays $c$, $d$ and $gam$ are ordered in this way before entry, and in this event they will be unchanged on exit.

Note that the problems (1) and (2) must be of boundary value type, that is neither $C$ nor $D$ may be identically zero.

Note also that the rank of the matrix $[C,D]$ must be $\text{n}$ for the problem to be properly posed.

Any violation of these conditions will lead to an error exit.

dfloat, ndarray, shape $(n,n)$

The rows of $c$ and $d$ and the components of $gam$ are reordered so that the boundary conditions are in the order:

1. conditions on $y\left(a\right)$ only;

2. condition involving $y\left(a\right)$ and $y\left(b\right)$; and

3. conditions on $y\left(b\right)$ only.

The function will be slightly more efficient if the arrays $c$, $d$ and $gam$ are ordered in this way before entry, and in this event they will be unchanged on exit.

Note that the problems (1) and (2) must be of boundary value type, that is neither $C$ nor $D$ may be identically zero.

Note also that the rank of the matrix $[C,D]$ must be $\text{n}$ for the problem to be properly posed.

Any violation of these conditions will lead to an error exit.

gamfloat, ndarray, shape $\left(n\right)$

The rows of $c$ and $d$ and the components of $gam$ are reordered so that the boundary conditions are in the order:

1. conditions on $y\left(a\right)$ only;

2. condition involving $y\left(a\right)$ and $y\left(b\right)$; and

3. conditions on $y\left(b\right)$ only.

The function will be slightly more efficient if the arrays $c$, $d$ and $gam$ are ordered in this way before entry, and in this event they will be unchanged on exit.

Note that the problems (1) and (2) must be of boundary value type, that is neither $C$ nor $D$ may be identically zero.

Note also that the rank of the matrix $[C,D]$ must be $\text{n}$ for the problem to be properly posed.

Any violation of these conditions will lead to an error exit.

xfloat, ndarray, shape $\left(\text{mnp}\right)$

$x\left[0\right],x\left[1\right],\dots ,x[np-1]$ define the final mesh (with the returned value of $np$) satisfying the relation [equation].

yfloat, ndarray, shape $(n,\text{mnp})$

The approximate solution $z\left(x\right)$ satisfying [equation], on the final mesh, that is

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

where $np$ is the number of points in the final mesh.

The remaining columns of $y$ are not used.

npint

The number of points in the final (returned) mesh.

Raises

NagValueError

(errno $1$)

The sequence $x$ is not strictly increasing. For $i=⟨value⟩$, $x[i-1]=⟨value⟩$ and $x\left[i\right]=⟨value⟩$.

(errno $1$)

On entry: $b=⟨value⟩$ and $x[np-1]=⟨value⟩$.

Constraint: $a=x\left[0\right]<x\left[1\right]<\cdots <x[np-1]=b\text{,}np\ge 4$.

(errno $1$)

On entry: $a=⟨value⟩$ and $x\left[0\right]=⟨value⟩$.

Constraint: $a=x\left[0\right]<x\left[1\right]<\cdots <x[np-1]=b\text{,}np\ge 4$.

(errno $1$)

On entry, $a=⟨value⟩$ and $b=⟨value⟩$.

Constraint: $b>a$.

(errno $1$)

On entry, $\text{mnp}=⟨value⟩$.

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

(errno $1$)

On entry, $np=⟨value⟩$ and $\text{mnp}=⟨value⟩$.

Constraint: $np\le \text{mnp}$.

(errno $1$)

On entry, $np=⟨value⟩$.

Constraint: $np=0$ or $np\ge 4$.

(errno $1$)

On entry, $tol=⟨value⟩$.

Constraint: $tol>0.0$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 2$.

(errno $2$)

More than $\text{n}$ columns of the $\text{n}$ by $2\times n$ matrix $[C,D]$ are identically zero, i.e., the boundary conditions are rank deficient. The number of non-identically zero columns is $⟨value⟩$.

(errno $2$)

Row $⟨value⟩$ of the array $c$ and the corresponding row of array $d$ are identically zero, i.e., the boundary conditions are rank deficient.

(errno $2$)

$c$ is identically zero; $\text{n}$ conditions are set in $d$.

At least one condition must be on the left. $n=⟨value⟩$.

(errno $2$)

$d$ is identically zero; $\text{n}$ conditions are set in $c$.

At least one condition must be on the right. $n=⟨value⟩$.

(errno $4$)

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

The error code internally was $⟨value⟩$. Please contact NAG.

(errno $5$)

At least one row of the $\text{n}$ by $2\times n$ matrix $[C,D]$ is a linear combination of the other rows determined up to a numerical tolerance, i.e., the boundary conditions are rank deficient. The index of first such row is $⟨value⟩$.

(errno $5$)

At least one row of the $\text{n}$ by $2\times n$ matrix $[C,D]$ is a linear combination of the other rows, i.e., the boundary conditions are rank deficient. The index of the first such row is $⟨value⟩$.

Warns

NagAlgorithmicWarning

(errno $3$)

Newton iteration has reached round-off level.

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

(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 routine with a continuation facility instead.

(errno $3$)

A finer mesh is required for the accuracy requested; that is, $\text{mnp}$ is not large enough.

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_lin_gen solves a linear two-point boundary value problem for a system of $\text{n}$ ordinary differential equations in the interval [$a,b$]. The system is written in the form

$$y^{\prime }=F\left(x\right)y+g\left(x\right)$$

and the boundary conditions are written in the form

$$Cy\left(a\right)+Dy\left(b\right)=\gamma \text{.}$$

Here $F\left(x\right)$, $C$ and $D$ are $\text{n}\times \text{n}$ matrices, and $g\left(x\right)$ and $\gamma$ are $\text{n}$-component vectors. The approximate solution to (1) and (2) is found using a finite difference method with deferred correction. The algorithm is a specialization of that used in function bvp_fd_nonlin_gen() which solves a nonlinear version of (1) and (2). The nonlinear version of the algorithm is described fully in Pereyra (1979).

You 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 submodule interp if these points do not themselves form a convenient mesh.

References

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