naginterfaces.library.ode.bvp_​coll_​nlin_​solve

naginterfaces.library.ode.bvp_coll_nlin_solve(ffun, fjac, gafun, gbfun, gajac, gbjac, guess, comm, data=None, spiked_sorder='C')

bvp_coll_nlin_solve solves a general two-point boundary value problem for a nonlinear mixed order system of ordinary differential equations.

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

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

Parameters

ffuncallable f = ffun(x, y, m, data=None)

$ffun$ must evaluate the functions $f_i$ for given values $x,z\left(y\left(x\right)\right)$.

Parameters

xfloat

$x$, the independent variable.

yfloat, ndarray, shape $(\text{neq},:)$

$y[\text{i}-1,\text{j}]$ contains $y_{\text{i}}^{\left(\text{j}\right)}\left(x\right)$, for $\text{j}=0,1,\dots ,m[\text{i}-1]-1$, for $\text{i}=1,2,\dots ,\text{neq}$.

Note: $y_i^{\left(0\right)}\left(x\right)=y_i\left(x\right)$.

mint, ndarray, shape $\left(\text{neq}\right)$

$m[\text{i}-1]$ contains $m_{\text{i}}$, the order of the $\text{i}$th differential equation, for $\text{i}=1,2,\dots ,\text{neq}$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

ffloat, array-like, shape $\left(\text{neq}\right)$

$f[\text{i}-1]$ must contain $f_{\text{i}}$, for $\text{i}=1,2,\dots ,\text{neq}$.

fjaccallable dfdy = fjac(x, y, m, dfdy, data=None)

$fjac$ must evaluate the partial derivatives of $f_i$ with respect to the elements of

$z\left(y\left(x\right)\right)=(y_1\left(x\right),y_1^1\left(x\right),\dots ,y_1^{(m_1-1)}\left(x\right),y_2\left(x\right),\dots ,y_n^{(m_n-1)}\left(x\right))$.

Parameters

xfloat

$x$, the independent variable.

yfloat, ndarray, shape $(\text{neq},:)$

$y[\text{i}-1,\text{j}]$ contains $y_{\text{i}}^{\left(\text{j}\right)}\left(x\right)$, for $\text{j}=0,1,\dots ,m[\text{i}-1]-1$, for $\text{i}=1,2,\dots ,\text{neq}$.

Note: $y_i^{\left(0\right)}\left(x\right)=y_i\left(x\right)$.

mint, ndarray, shape $\left(\text{neq}\right)$

$m[\text{i}-1]$ contains $m_{\text{i}}$, the order of the $\text{i}$th differential equation, for $\text{i}=1,2,\dots ,\text{neq}$.

dfdyfloat, ndarray, shape $(\text{neq},\text{neq},:)$

Set to zero.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

dfdyfloat, array-like, shape $(\text{neq},\text{neq},:)$

$dfdy[\text{i}-1,\text{j}-1,\text{k}]$ must contain the partial derivative of $f_{\text{i}}$ with respect to $y_{\text{j}}^{\left(\text{k}\right)}$, for $\text{k}=0,1,\dots ,m[\text{j}-1]-1$, for $\text{j}=1,2,\dots ,\text{neq}$, for $\text{i}=1,2,\dots ,\text{neq}$. Only nonzero partial derivatives need be set.

gafuncallable ga = gafun(ya, m, nlbc, data=None)

$gafun$ must evaluate the boundary conditions at the left-hand end of the range, that is functions $g_i\left(z\left(y\left(a\right)\right)\right)$ for given values of $z\left(y\left(a\right)\right)$.

Parameters

yafloat, ndarray, shape $(\text{neq},:)$

$ya[\text{i}-1,\text{j}]$ contains $y_{\text{i}}^{\left(\text{j}\right)}\left(a\right)$, for $\text{j}=0,1,\dots ,m[\text{i}-1]-1$, for $\text{i}=1,2,\dots ,\text{neq}$.

Note: $y_i^{\left(0\right)}\left(a\right)=y_i\left(a\right)$.

mint, ndarray, shape $\left(\text{neq}\right)$

$m[\text{i}-1]$ contains $m_{\text{i}}$, the order of the $\text{i}$th differential equation, for $\text{i}=1,2,\dots ,\text{neq}$.

nlbcint

The number of boundary conditions at $a$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

gafloat, array-like, shape $\left(nlbc\right)$

$ga[\text{i}-1]$ must contain $g_{\text{i}}\left(z\left(y\left(a\right)\right)\right)$, for $\text{i}=1,2,\dots ,nlbc$.

gbfuncallable gb = gbfun(yb, m, nrbc, data=None)

$gbfun$ must evaluate the boundary conditions at the right-hand end of the range, that is functions ${\overline{g}}_i\left(z\left(y\left(b\right)\right)\right)$ for given values of $z\left(y\left(b\right)\right)$.

Parameters

ybfloat, ndarray, shape $(\text{neq},:)$

$yb[\text{i}-1,\text{j}]$ contains $y_{\text{i}}^{\left(\text{j}\right)}\left(b\right)$, for $\text{j}=0,1,\dots ,m[\text{i}-1]-1$, for $\text{i}=1,2,\dots ,\text{neq}$.

Note: $y_i^{\left(0\right)}\left(b\right)=y_i\left(b\right)$.

mint, ndarray, shape $\left(\text{neq}\right)$

$m[\text{i}-1]$ contains $m_{\text{i}}$, the order of the $\text{i}$th differential equation, for $\text{i}=1,2,\dots ,\text{neq}$.

nrbcint

The number of boundary conditions at $b$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

gbfloat, array-like, shape $\left(nrbc\right)$

$gb[\text{i}-1]$ must contain ${\overline{g}}_{\text{i}}\left(z\left(y\left(b\right)\right)\right)$, for $\text{i}=1,2,\dots ,nrbc$.

gajaccallable dgady = gajac(ya, m, dgady, data=None)

$gajac$ must evaluate the partial derivatives of $g_i\left(z\left(y\left(a\right)\right)\right)$ with respect to the elements of $z\left(y\left(a\right)\right)=(y_1\left(a\right),y_1^1\left(a\right),\dots ,y_1^{(m_1-1)}\left(a\right),y_2\left(a\right),\dots ,y_n^{(m_n-1)}\left(a\right))$.

Parameters

yafloat, ndarray, shape $(\text{neq},:)$

$ya[\text{i}-1,\text{j}]$ contains $y_{\text{i}}^{\left(\text{j}\right)}\left(a\right)$, for $\text{j}=0,1,\dots ,m[\text{i}-1]-1$, for $\text{i}=1,2,\dots ,\text{neq}$.

Note: $y_i^{\left(0\right)}\left(a\right)=y_i\left(a\right)$.

mint, ndarray, shape $\left(\text{neq}\right)$

$m[\text{i}-1]$ contains $m_{\text{i}}$, the order of the $\text{i}$th differential equation, for $\text{i}=1,2,\dots ,\text{neq}$.

dgadyfloat, ndarray, shape $(\text{nlbc},\text{neq},:)$

Set to zero.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

dgadyfloat, array-like, shape $(\text{nlbc},\text{neq},:)$

$dgady[\text{i}-1,\text{j}-1,\text{k}]$ must contain the partial derivative of $g_{\text{i}}\left(z\left(y\left(a\right)\right)\right)$ with respect to $y_{\text{j}}^{\left(\text{k}\right)}\left(a\right)$, for $\text{k}=0,1,\dots ,m[\text{j}-1]-1$, for $\text{j}=1,2,\dots ,\text{neq}$, for $\text{i}=1,2,\dots ,nlbc$. Only nonzero partial derivatives need be set.

gbjaccallable dgbdy = gbjac(yb, m, dgbdy, data=None)

$gbjac$ must evaluate the partial derivatives of ${\overline{g}}_i\left(z\left(y\left(b\right)\right)\right)$ with respect to the elements of $z\left(y\left(b\right)\right)=(y_1\left(b\right),y_1^1\left(b\right),\dots ,y_1^{(m_1-1)}\left(b\right),y_2\left(b\right),\dots ,y_n^{(m_n-1)}\left(b\right))$.

Parameters

ybfloat, ndarray, shape $(\text{neq},:)$

$yb[\text{i}-1,\text{j}]$ contains $y_{\text{i}}^{\left(\text{j}\right)}\left(b\right)$, for $\text{j}=0,1,\dots ,m[\text{i}-1]-1$, for $\text{i}=1,2,\dots ,\text{neq}$.

Note: $y_i^{\left(0\right)}\left(b\right)=y_i\left(b\right)$.

mint, ndarray, shape $\left(\text{neq}\right)$

$m[\text{i}-1]$ contains $m_{\text{i}}$, the order of the $\text{i}$th differential equation, for $\text{i}=1,2,\dots ,\text{neq}$.

dgbdyfloat, ndarray, shape $(\text{nrbc},\text{neq},:)$

Set to zero.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

dgbdyfloat, array-like, shape $(\text{nrbc},\text{neq},:)$

$dgbdy[\text{i}-1,\text{j}-1,\text{k}]$ must contain the partial derivative of ${\overline{g}}_{\text{i}}\left(z\left(y\left(b\right)\right)\right)$ with respect to $y_{\text{j}}^{\left(\text{k}\right)}\left(b\right)$, for $\text{k}=0,1,\dots ,m[\text{j}-1]-1$, for $\text{j}=1,2,\dots ,\text{neq}$, for $\text{i}=1,2,\dots ,nrbc$. Only nonzero partial derivatives need be set.

guesscallable (y, dym) = guess(x, m, mmax, data=None)

$guess$ must return initial approximations for the solution components $y_{\text{i}}^{\left(\text{j}\right)}$ and the derivatives $y_{\text{i}}^{\left(m_{\text{i}}\right)}$, for $\text{j}=0,1,\dots ,m[\text{i}-1]-1$, for $\text{i}=1,2,\dots ,\text{neq}$.

Try to compute each derivative $y_i^{\left(m_i\right)}$ such that it corresponds to your approximations to $y_i^{\left(\text{j}\right)}$, for $\text{j}=0,1,\dots ,m[i-1]-1$.

You should not call $ffun$ to compute $y_i^{\left(m_i\right)}$.

If bvp_coll_nlin_solve is being used in conjunction with bvp_coll_nlin_contin() as part of a continuation process, $guess$ is not called by bvp_coll_nlin_solve after the call to bvp_coll_nlin_contin().

Parameters

xfloat

$x$, the independent variable; $x\in [a,b]$.

mint, ndarray, shape $\left(\text{neq}\right)$

$m[\text{i}-1]$ contains $m_{\text{i}}$, the order of the $\text{i}$th differential equation, for $\text{i}=1,2,\dots ,\text{neq}$.

mmaxint

$max\left(m\right[i\left]\right)$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

yfloat, array-like, shape $(\text{neq},\text{mmax})$

$y[\text{i}-1,\text{j}]$ must contain $y_{\text{i}}^{\left(\text{j}\right)}\left(x\right)$, for $\text{j}=0,1,\dots ,m[\text{i}-1]-1$, for $\text{i}=1,2,\dots ,\text{neq}$.

Note: $y_i^{\left(0\right)}\left(x\right)=y_i\left(x\right)$.

dymfloat, array-like, shape $\left(\text{neq}\right)$

$dym[\text{i}-1]$ must contain $y_{\text{i}}^{\left(m_{\text{i}}\right)}\left(x\right)$, for $\text{i}=1,2,\dots ,\text{neq}$.

commdict, communication object, modified in place

Communication structure.

This argument must have been initialized by a prior call to bvp_coll_nlin_setup().

dataarbitrary, optional

User-communication data for callback functions.

spiked_sorderstr, optional

If $dfdy$ in $fjac$, $dgady$ in $gajac$ or $y$ in $guess$ 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.

Raises

NagValueError

(errno $1$)

Either the setup function has not been called or the communication arrays have become corrupted. No solution will be computed.

(errno $2$)

Numerical singularity has been detected in the Jacobian used in the Newton iteration.

No results have been generated. Check the coding of the functions for calculating the Jacobians of system and boundary conditions.

(errno $3$)

All Newton iterations that have been attempted have failed to converge.

No results have been generated. Check the coding of the functions for calculating the Jacobians of system and boundary conditions.

Try to provide a better initial solution approximation.

Warns

NagAlgorithmicWarning

(errno $4$)

A Newton iteration has failed to converge. The computation has not succeeded but results have been returned for an intermediate mesh on which convergence was achieved.

These results should be treated with extreme caution.

(errno $5$)

The expected number of sub-intervals required to continue the computation exceeds the maximum specified: $⟨value⟩$.

Results have been generated which may be useful.

Try increasing this number or relaxing the error requirements.

Notes

bvp_coll_nlin_solve and its associated functions (bvp_coll_nlin_setup(), bvp_coll_nlin_contin(), bvp_coll_nlin_interp() and bvp_coll_nlin_diag()) solve the two-point boundary value problem for a nonlinear mixed order system of ordinary differential equations

$$\begin{array}{c}\begin{array}{ccc}{y}_1^{\left(m_1\right)}\left(x\right)& =& f_1(x,y_1,y_1^{\left(1\right)},\dots ,y_1^{(m_1-1)},y_2,\dots ,y_n^{(m_n-1)})\\ y_2^{\left(m_2\right)}\left(x\right)& =& f_2(x,y_1,y_1^{\left(1\right)},\dots ,y_1^{(m_1-1)},y_2,\dots ,y_n^{(m_n-1)})\\ & ⋮& \\ y_n^{\left(m_n\right)}\left(x\right)& =& f_n(x,y_1,y_1^{\left(1\right)},\dots ,y_1^{(m_1-1)},y_2,\dots ,y_n^{(m_n-1)})\end{array}\end{array}$$

over an interval $[a,b]$ subject to $p$ ($>0$) nonlinear boundary conditions at $a$ and $q$ ($>0$) nonlinear boundary conditions at $b$, where $p+q={\sum }_{i=1}^n{m}_i$. Note that $y_i^{\left(m\right)}\left(x\right)$ is the $m$th derivative of the $i$th solution component. Hence $y_i^{\left(0\right)}\left(x\right)=y_i\left(x\right)$. The left boundary conditions at $a$ are defined as

$$g_i\left(z\left(y\left(a\right)\right)\right)=0\text{,}i=1,2,\dots ,p\text{,}$$

and the right boundary conditions at $b$ as

$${\overline{g}}_j\left(z\left(y\left(b\right)\right)\right)=0\text{,}j=1,2,\dots ,q\text{,}$$

where $y=(y_1,y_2,\dots ,y_n)$ and

$$z\left(y\left(x\right)\right)=(y_1\left(x\right),y_1^{\left(1\right)}\left(x\right),\dots ,y_1^{(m_1-1)}\left(x\right),y_2\left(x\right),\dots ,y_n^{(m_n-1)}\left(x\right))\text{.}$$

First, bvp_coll_nlin_setup() must be called to specify the initial mesh, error requirements and other details. Note that the error requirements apply only to the solution components $y_1,y_2,\dots ,y_n$ and that no error control is applied to derivatives of solution components. (If error control is required on derivatives then the system must be reduced in order by introducing the derivatives whose error is to be controlled as new variables. See Further Comments.) Then, bvp_coll_nlin_solve can be used to solve the boundary value problem. After successful computation, bvp_coll_nlin_diag() can be used to ascertain details about the final mesh and other details of the solution procedure, and bvp_coll_nlin_interp() can be used to compute the approximate solution anywhere on the interval $[a,b]$.

A description of the numerical technique used in bvp_coll_nlin_solve is given in Notes for bvp_coll_nlin_setup.

bvp_coll_nlin_solve can also be used in the solution of a series of problems, for example in performing continuation, when the mesh used to compute the solution of one problem is to be used as the initial mesh for the solution of the next related problem. bvp_coll_nlin_contin() should be used in between calls to bvp_coll_nlin_solve in this context.

See Further Comments for details of how to solve boundary value problems of a more general nature.

The functions are based on modified versions of the codes COLSYS and COLNEW (see Ascher et al. (1979) and Ascher and Bader (1987)). A comprehensive treatment of the numerical solution of boundary value problems can be found in Ascher et al. (1988) and Keller (1992).

References

Ascher, U M and Bader, G, 1987, A new basis implementation for a mixed order boundary value ODE solver, SIAM J. Sci. Stat. Comput. (8), 483–500

Ascher, U M, Christiansen, J and Russell, R D, 1979, A collocation solver for mixed order systems of boundary value problems, Math. Comput. (33), 659–679

Ascher, U M, Mattheij, R M M and Russell, R D, 1988, Numerical Solution of Boundary Value Problems for Ordinary Differential Equations, Prentice–Hall

Keller, H B, 1992, Numerical Methods for Two-point Boundary-value Problems, Dover, New York