naginterfaces.library.ode.bvp_​shoot_​bval

naginterfaces.library.ode.bvp_shoot_bval(u, v, a, b, tol, fcn, m1, monlev, comm, data=None, io_manager=None)

bvp_shoot_bval solves a two-point boundary value problem for a system of ordinary differential equations, using a Runge–Kutta–Merson method and a Newton iteration in a shooting and matching technique.

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

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

Parameters

ufloat, array-like, shape $(n,2)$

$u[\text{i}-1,0]$ must be set to the known or estimated value of $y_{\text{i}}$ at $a$ and $u[\text{i}-1,1]$ must be set to the known or estimated value of $y_{\text{i}}$ at $b$, for $\text{i}=1,2,\dots ,\text{n}$.

vfloat, array-like, shape $(n,2)$

$v[\text{i}-1,\text{j}-1]$ must be set to $0.0$ if $u[\text{i}-1,\text{j}-1]$ is a known value and to $1.0$ if $u[\text{i}-1,\text{j}-1]$ is an estimated value, for $\text{j}=1,2,\dots ,2$, for $\text{i}=1,2,\dots ,\text{n}$.

afloat

$a$, the initial point of the interval of integration.

bfloat

$b$, the final point of the interval of integration.

tolfloat

Must be set to a small quantity suitable for:

1. testing the local error in $y_i$ during integration,

2. testing for the convergence of $y_i$ at $b$,

3. calculating the perturbation in estimated boundary values for $y_i$, which are used to obtain the approximate derivatives of the residuals for use in the Newton iteration.

You are advised to check your results by varying $tol$.

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

$fcn$ must evaluate the functions $f_{\text{i}}$ (i.e., the derivatives $y_{\text{i}}^{\prime }$), for $\text{i}=1,2,\dots ,\text{n}$, at a general point $x$.

Parameters

nint

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

xfloat

$x$, the value of the argument.

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

$y_{\text{i}}$, for $\text{i}=1,2,\dots ,\text{n}$, the value of the argument.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

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

The values of $f_{\text{i}}\left(x\right)$, for $\text{i}=1,2,\dots ,\text{n}$.

m1int

A value which controls output.

$m1=1$

The final solution is not evaluated.

$m1>1$

The final values of $y_{\text{i}}$ at interval $(b-a)/(m1-1)$ are calculated and stored in the array $soln$ by columns, starting with values $y_{\text{i}}$ at $a$ stored in $soln[\text{i}-1,0]$, for $\text{i}=1,2,\dots ,\text{n}$.

monlevint

Setting $monlev=0$ disables monitoring of the pseudo-Newton iteration. Setting $monlev=1$ enables this monitoring.

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.

Returns

ufloat, ndarray, shape $(n,2)$

The known values unaltered, and corrected values of the estimates, unless an error has occurred. If an error has occurred, $u$ contains the known values and the latest values of the estimates.

solnfloat, ndarray, shape $(n,m1)$

The solution when $m1>1$.

wfloat, ndarray, shape $(n,3\times n+17+max(11,n))$

If $errno$ = 2, 3, 4 or 5, $w[\text{i}-1,0]$, for $\text{i}=1,2,\dots ,\text{n}$, contains the solution at the point where the integration fails and the point of failure is returned in $w[0,1]$.

Raises

NagValueError

(errno $1$)

On entry, $monlev=⟨value⟩$.

Constraint: $monlev=0$ or $1$.

(errno $1$)

On entry, incorrect number of boundary values were flagged as known.

Number flagged as known: $⟨value⟩$, but number should be $⟨value⟩$.

(errno $1$)

On entry all left-hand boundary values were flagged as known.

(errno $1$)

On entry no left-hand boundary values were flagged as known.

(errno $1$)

On entry, $m1=⟨value⟩$.

Constraint: $m1\ge 1$.

(errno $1$)

On entry, $tol=⟨value⟩$.

Constraint: $tol>0.0$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $2$)

In the integration with initial or final parameters, the step size was reduced too far for the integration to proceed. Either this function is not a suitable method for solving the problem, or the initial choice of parameters is very poor.

(errno $3$)

In the integration with initial or final parameters, a suitable initial step could not be found. Either this function is not suitable for solving the problem, or the initial choice of parameters is very poor.

(errno $4$)

An initial step-length could be found for integration to proceed with the current parameters.

(errno $5$)

The step-length required to calculate the Jacobian to sufficient accuracy is too small

(errno $6$)

The Jacobian has an insignificant column. Make sure that the solution vector depends on all the parameters.

(errno $7$)

An internal singular value decomposition has failed.

This error can be avoided by changing the initial parameter estimates.

(errno $8$)

The Newton iteration has failed to converge.

This can indicate a poor initial choice of parameters or a very difficult problem.

Consider varying elements of the parameter convergence control if the residuals are small; otherwise vary initial parameter estimates.

(errno $10$)

Internal error in calculating residual. Please contact NAG.

(errno $11$)

Internal error in calculating Jacobian. Please contact NAG.

(errno $12$)

Internal error in Newton method. Please contact NAG.

Notes

No equivalent traditional C interface for this routine exists in the NAG Library.

bvp_shoot_bval solves a two-point boundary value problem for a system of $\text{n}$ ordinary differential equations in the range $a,b$. The system is written in the form:

$$y_i^{\prime }=f_i(x,y_1,y_2,\dots ,y_{\text{n}})\text{,}i=1,2,\dots ,\text{n}$$

and the derivatives $f_i$ are evaluated by $fcn$. Initially, $\text{n}$ boundary values of the variables $y_i$ must be specified, some at $a$ and some at $b$. You must supply estimates of the remaining $\text{n}$ boundary values (called parameters below); the function corrects these by a form of Newton iteration. It also calculates the complete solution on an equispaced mesh if required.

Starting from the known and estimated values of $y_i$ at $a$, the function integrates the equations from $a$ to $b$ (using a Runge–Kutta–Merson method). The differences between the values of $y_i$ at $b$ from integration and those specified initially should be zero for the true solution. (These differences are called residuals below.) The function uses a generalized Newton method to reduce the residuals to zero, by calculating corrections to the estimated boundary values. This process is repeated iteratively until convergence is obtained, or until the function can no longer reduce the residuals. See Hall and Watt (1976) for a simple discussion of shooting and matching techniques.

References

Hall, G and Watt, J M (ed.), 1976, Modern Numerical Methods for Ordinary Differential Equations, Clarendon Press, Oxford