naginterfaces.library.ode.bvp_​shoot_​genpar

naginterfaces.library.ode.bvp_shoot_genpar(p, pe, e, m1, monlev, fcn, bc, ebndry, comm, data=None, io_manager=None)

bvp_shoot_genpar solves a two-point boundary value problem for a system of ordinary differential equations, using initial value techniques and Newton iteration; it generalizes function bvp_shoot_bval() to include the case where parameters other than boundary values are to be determined.

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

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

Parameters

pfloat, array-like, shape $\left(\text{n1}\right)$

An estimate for the $\text{i}$th argument, $p_{\text{i}}$, for $\text{i}=1,2,\dots ,{\text{n}}_1$.

pefloat, array-like, shape $\left(\text{n1}\right)$

The elements of $pe$ must be given small positive values. The element $pe[i-1]$ is used

1. in the convergence test on the $i$th argument in the Newton iteration, and

2. in perturbing the $i$th argument when approximating the derivatives of the components of the solution with respect to this argument for use in the Newton iteration.

The elements $pe[i-1]$ should not be chosen too small.

They should usually be several orders of magnitude larger than machine precision.

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

The elements of $e$ must be given positive values. The element $e[i-1]$ is used in the bound on the local error in the $i$th component of the solution $y_i$ during integration.

The elements $e[i-1]$ should not be chosen too small.

They should usually be several orders of magnitude larger than machine precision.

m1int

A value which controls exit values.

$m1=1$

The final solution is not calculated.

$m1>1$

The final values of the solution at interval (length of range)/$(m1-1)$ are calculated and stored sequentially in the array $soln$ starting with the values of the solutions evaluated at the first end point (see $ebndry$) stored in the first column of $soln$.

monlevint

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

fcncallable f = fcn(n, n1, x, y, p, 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.

n1int

${\text{n}}_1$, the number of parameters.

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.

pfloat, ndarray, shape $\left(n1\right)$

The current estimate of the argument $p_{\text{i}}$, for $\text{i}=1,2,\dots ,{\text{n}}_1$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

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

The value of $f_{\text{i}}$, for $\text{i}=1,2,\dots ,\text{n}$. The $f_i$ may depend upon the parameters $p_{\text{j}}$, for $\text{j}=1,2,\dots ,{\text{n}}_1$. If there are any driving equations (see Notes) then these must be numbered first in the ordering of the components of $f$ in $fcn$.

bccallable (g1, g2) = bc(n, n1, p, data=None)

$bc$ must place in $g1$ and $g2$ the boundary conditions at $a$ and $b$ respectively (see $ebndry$).

Parameters

nint

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

n1int

${\text{n}}_1$, the number of parameters.

pfloat, ndarray, shape $\left(n1\right)$

An estimate of the argument $p_{\text{i}}$, for $\text{i}=1,2,\dots ,{\text{n}}_1$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

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

The value of $y_{\text{i}}\left(a\right)$, (where this may be a known value or a function of the parameters $p_{\text{j}}$, for $\text{j}=1,2,\dots ,{\text{n}}_1$, for $\text{i}=1,2,\dots ,\text{n}$).

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

The value of $y_{\text{i}}\left(b\right)$, for $\text{i}=1,2,\dots ,\text{n}$, (where these may be known values or functions of the parameters $p_{\text{j}}$, for $\text{j}=1,2,\dots ,{\text{n}}_1$). If $\text{n}>{\text{n}}_1$, so that there are some driving equations, the first $\text{n}-{\text{n}}_1$ values of $g2$ need not be set since they are never used.

ebndrycallable (a, b) = ebndry(n1, p, data=None)

$ebndry$ must evaluate the boundary points $a$ and $b$, each of which may depend on the arguments $p_1,p_2,\dots ,p_{{\text{n}}_1}$.

The integrations in the shooting method are always from $a$ to $b$.

Parameters

n1int

${\text{n}}_1$, the number of parameters.

pfloat, ndarray, shape $\left(n1\right)$

The current estimate of the $\text{i}$th argument, $p_{\text{i}}$, for $\text{i}=1,2,\dots ,{\text{n}}_1$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

afloat

$a$, one of the boundary points.

bfloat

The second boundary point, $b$. Note that $b>a$ forces the direction of integration to be that of increasing $x$. If $a$ and $b$ are interchanged the direction of integration is reversed.

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

pfloat, ndarray, shape $\left(\text{n1}\right)$

The corrected value for the $i$th argument, unless an error has occurred, when it contains the last calculated value of the argument.

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

The solution when $m1>1$.

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

With $errno$ = 2, 3, 4 or 5 (see Exceptions), $w[\text{i}-1,0]$, for $\text{i}=1,2,\dots ,\text{n}$, contains the solution at the point $x$ when the error occurred. $w[0,1]$ contains $x$.

Raises

NagValueError

(errno $1$)

On entry, $monlev=⟨value⟩$.

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

(errno $1$)

On entry a negative or zero local error tolerance has been set.

(errno $1$)

On entry a negative or zero convergence test tolerance has been set.

(errno $1$)

On entry, $m1=⟨value⟩$.

Constraint: $m1\ge 1$.

(errno $1$)

On entry, $n=⟨value⟩$ and $\text{n1}=⟨value⟩$.

Constraint: $n\ge \text{n1}$.

(errno $1$)

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

Constraint: $\text{n1}\ge 1$.

(errno $2$)

The step length for the integration became too short to proceed when calculating the residual.

(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$)

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

(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$)

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

(errno $5$)

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

(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 $9$)

Internal error in Newton method. Please contact NAG.

(errno $10$)

Internal error in calculating Jacobian. Please contact NAG.

(errno $11$)

Internal error in calculating residual. Please contact NAG.

(errno $12$)

Internal error in calculating residual. Please contact NAG.

Notes

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

bvp_shoot_genpar solves a two-point boundary value problem by determining the unknown parameters $p_1,p_2,\dots ,p_{{\text{n}}_1}$ of the problem. These parameters may be, but need not be, boundary values; they may include eigenvalue parameters in the coefficients of the differential equations, length of the range of integration, etc. The notation and methods used are similar to those of bvp_shoot_bval() and you are advised to study this first. (The parameters $p_1,p_2,\dots ,p_{{\text{n}}_1}$ correspond precisely to the unknown boundary conditions in bvp_shoot_bval().) It is assumed that we have a system of $\text{n}$ first-order ordinary differential equations of the form:

$$\frac{d{y}_i}{dx}=f_i(x,y_1,y_2,\dots ,y_{\text{n}})\text{,}i=1,2,\dots ,\text{n}\text{,}$$

and that the derivatives $f_i$ are evaluated by $fcn$. The system, including the boundary conditions given by $bc$ and the range of integration given by $ebndry$, involves the ${\text{n}}_1$ unknown parameters $p_1,p_2,\dots ,p_{{\text{n}}_1}$ which are to be determined, and for which initial estimates must be supplied. The number of unknown parameters ${\text{n}}_1$ must not exceed the number of equations $\text{n}$. If ${\text{n}}_1<\text{n}$, we assume that $(\text{n}-{\text{n}}_1)$ equations of the system are not involved in the matching process. These are usually referred to as ‘driving equations’; they are independent of the parameters and of the solutions of the other ${\text{n}}_1$ equations. In numbering the equations for $fcn$, the driving equations must be put first.

The estimated values of the parameters are corrected by a form of Newton iteration. The Newton correction on each iteration is calculated using a Jacobian matrix whose $(i,j)$th element depends on the derivative of the $i$th component of the solution, $y_i$, with respect to the $j$th parameter, $p_j$. This matrix is calculated by a simple numerical differentiation technique which requires ${\text{n}}_1$ evaluations of the differential system.

If the argument $monlev$ is set appropriately, the function automatically prints messages to inform you of the flow of the calculation. These messages are discussed in detail in Further Comments.

bvp_shoot_genpar is a simplified version of bvp_shoot_genpar_algeq() which is described in detail in Gladwell (1979).

References

Gladwell, I, 1979, The development of the boundary value codes in the ordinary differential equations module of the NAG Library, 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