naginterfaces.library.ode.dae_​dassl_​gen

naginterfaces.library.ode.dae_dassl_gen(t, tout, y, ydot, rtol, atol, itask, res, comm, jac=None, data=None)

dae_dassl_gen is a function for integrating stiff systems of implicit ordinary differential equations coupled with algebraic equations.

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

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

Parameters

tfloat

On initial entry: the initial value of the independent variable, $t$.

toutfloat

The next value of $t$ at which a computed solution is desired.

On initial entry: $tout$ is used to determine the direction of integration. Integration is permitted in either direction (see also $itask$).

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

On initial entry: the vector of initial values of the dependent variables $y$.

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

On initial entry: $ydot$ must contain approximations to the time derivatives $y^{\prime }$ of the vector $y$ evaluated at the initial value of the independent variable.

rtolfloat, array-like, shape $(:)$

Note: the required length for this argument is determined as follows: if $comm{[}^{\prime }ico{m}^{\prime }\left]\right[1]=1$: $\text{neq}$; if $comm{[}^{\prime }ico{m}^{\prime }\left]\right[1]=0$: $1$; otherwise: $0$.

The relative local error tolerance.

atolfloat, array-like, shape $(:)$

Note: the required length for this argument is determined as follows: if $comm{[}^{\prime }ico{m}^{\prime }\left]\right[1]=1$: $\text{neq}$; if $comm{[}^{\prime }ico{m}^{\prime }\left]\right[1]=0$: $1$; otherwise: $0$.

The absolute local error tolerance.

itaskint

On initial entry: need not be set.

rescallable (r, ires) = res(t, y, ydot, ires, data=None)

$res$ must evaluate the residual

$$R=F(t,y,y^{\prime })\text{.}$$

Parameters

tfloat

$t$, the current value of the independent variable.

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

$y_{\text{i}}$, for $\text{i}=1,2,\dots ,\text{neq}$, the current solution component.

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

The derivative of the solution at the current point $t$.

iresint

Is always equal to zero.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

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

$r[\text{i}-1]$ must contain the $\text{i}$th component of $R$, for $\text{i}=1,2,\dots ,\text{neq}$ where

$$R=F(t,y,ydot)\text{.}$$

iresint

$ires$ should normally be left unchanged. However, if an illegal value of $y$ is encountered, $ires$ should be set to $-1$; dae_dassl_gen will then attempt to resolve the problem so that illegal values of $y$ are not encountered. $ires$ should be set to $-2$ if you wish to return control to the calling function; this will cause dae_dassl_gen to exit with $errno$ = 23.

commdict, communication object, modified in place

Communication structure.

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

jacNone or callable pd = jac(t, y, ydot, pd, cj, data=None), optional

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

Evaluates the matrix of partial derivatives, $J$, where

$$J_{ij}=\frac{\partial F_i}{\partial y_j}+cj\times \frac{\partial F_i}{\partial y_j^{\prime }}\text{,}i,j=1,2,\dots ,\text{neq}\text{.}$$

If this option is not required, the actual argument for $jac$ must be None. You must indicate to the integrator whether this option is to be used by setting the argument $\text{jceval}$ appropriately in a call to the setup function dae_dassl_setup().

Parameters

tfloat

$t$, the current value of the independent variable.

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

$y_{\text{i}}$, for $\text{i}=1,2,\dots ,\text{neq}$, the current solution component.

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

The derivative of the solution at the current point $t$.

pdfloat, ndarray, shape $(:)$

$pd$ is preset to zero before the call to $jac$.

cjfloat

$cj$ is a scalar constant which will be defined in dae_dassl_gen.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

pdfloat, array-like, shape $(:)$

If the Jacobian is full then $pd[(\text{j}-1)\times \text{neq}+\text{i}-1]=J_{\text{i}\text{j}}$, for $\text{j}=1,2,\dots ,\text{neq}$, for $\text{i}=1,2,\dots ,\text{neq}$; if the Jacobian is banded then $pd[(j-1)\times (2\text{ml}+\text{mu}+1)+\text{ml}+\text{mu}+i-j]=J_{ij}$, for $max(1,j-\text{mu})\le i\le min(n,j+\text{ml})$.

dataarbitrary, optional

User-communication data for callback functions.

Returns

tfloat

On intermediate exit: $t$, the current value of the independent variable.

On final exit: the value of the independent variable at which the computed solution $y$ is returned (usually at $tout$).

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

On intermediate exit: the computed solution vector, $y$, evaluated at $t=T$.

On final exit: the computed solution vector, evaluated at $t$ (usually $t=tout$).

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

The time derivatives $y^{\prime }$ of the vector $y$ at the last integration point.

rtolfloat, ndarray, shape $(:)$

$rtol$ remains unchanged unless dae_dassl_gen exits with $errno$ = 16 in which case the values may have been increased to values estimated to be appropriate for continuing the integration.

atolfloat, ndarray, shape $(:)$

$atol$ remains unchanged unless dae_dassl_gen exits with $errno$ = 16 in which case the values may have been increased to values estimated to be appropriate for continuing the integration.

itaskint

The task performed by the integrator on successful completion or an indicator that a problem occurred during integration.

$itask=2$

The integration to $tout$ was successfully completed ($t=tout$) by stepping exactly to $tout$.

$itask=3$

The integration to $tout$ was successfully completed ($t=tout$) by stepping past $tout$. $y$ and $ydot$ are obtained by interpolation.

$itask<0$

Different negative values of $itask$ returned correspond to different failure exits. $\text{errno}$ should always be checked in such cases and the corrective action taken where appropriate.

$itask$ must remain unchanged between calls to dae_dassl_gen.

Raises

NagValueError

(errno $1$)

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

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

(errno $3$)

On entry, $t=⟨value⟩$.

Constraint: $tout\ne t$.

(errno $3$)

$tout$ is too close to $t$ to start integration: $tout-t=⟨value⟩$: $\text{hmin}=⟨value⟩$.

(errno $3$)

$tout$ is behind $t$ in the direction of $h$: $tout-t=⟨value⟩$, $h=⟨value⟩$.

(errno $6$)

Some element of $rtol$ is less than zero.

(errno $7$)

Some element of $atol$ is less than zero.

(errno $8$)

A previous call to this function returned with $itask=⟨value⟩$ and no appropriate action was taken.

(errno $11$)

Either the initialization function has not been called prior to the first call of this function or a communication array has become corrupted.

(errno $12$)

Either the initialization function has not been called prior to the first call of this function or a communication array has become corrupted.

(errno $13$)

$comm$[‘com’] array is of insufficient length; length required $=⟨value⟩$; actual length $\text{lcom}=⟨value⟩$.

(errno $14$)

All elements of $rtol$ and $atol$ are zero.

(errno $15$)

Maximum number of steps taken on this call before reaching $tout$: $t=⟨value⟩$, maximum number of steps $=⟨value⟩$.

(errno $16$)

Too much accuracy requested for precision of machine. $rtol$ and $atol$ were increased by scale factor $R$. Try running again with these scaled tolerances. $t=⟨value⟩$, $R=⟨value⟩$.

(errno $17$)

A solution component has become zero when a purely relative tolerance (zero absolute tolerance) was selected for that component. $t=⟨value⟩$, $y[\text{I}-1]=⟨value⟩$ for component $\text{I}=⟨value⟩$.

(errno $18$)

The error test failed repeatedly with $\left|h\right|=\text{hmin}$. $t=⟨value⟩$. Stepsize $h=⟨value⟩$.

(errno $19$)

The corrector repeatedly failed to converge with $\left|h\right|=\text{hmin}$. $t=⟨value⟩$. Stepsize $h=⟨value⟩$.

(errno $20$)

The iteration matrix is singular. $t=⟨value⟩$. Stepsize $h=⟨value⟩$.

(errno $21$)

The corrector could not converge and the error test failed repeatedly. $t=⟨value⟩$. Stepsize $h=⟨value⟩$.

(errno $22$)

$ires$ was set to $-1$ during a call to $res$ and could not be resolved. $t=⟨value⟩$. Stepsize $h=⟨value⟩$.

(errno $23$)

$ires$ was set to $-2$ during a call to $res$. $t=⟨value⟩$. Stepsize $=⟨value⟩$.

(errno $24$)

The initial $ydot$ could not be computed. $t=⟨value⟩$. Stepsize $h=⟨value⟩$.

(errno $25$)

Repeated occurrences of input constraint violations have been detected. This could result in a potential infinite loop: $itask=⟨value⟩$. Current violation corresponds to exit with $\text{errno}=⟨value⟩$.

Notes

dae_dassl_gen is a general purpose function for integrating the initial value problem for a stiff system of implicit ordinary differential equations with coupled algebraic equations written in the form

$$F(t,y,y^{\prime })=0\text{.}$$

dae_dassl_gen uses the DASSL implementation of the Backward Differentiation Formulae (BDF) of orders one to five to solve a system of the above form for $y$ ($y$) and $y^{\prime }$ ($ydot$). Values for $y$ and $ydot$ at the initial time must be given as input. These values must be consistent, (i.e., if $t$, $y$, $ydot$ are the given initial values, they must satisfy $F(t,y,ydot)=0$). The function solves the system from $t=t$ to $t=tout$.

A typical calling progrm for dae_dassl_gen would involve calling the DASSL implementation of the BDF integrator setup function dae_dassl_setup() and the banded matrix setup function dae_dassl_linalg() (if required), and, if the integration needs to proceed, calls dae_dassl_cont() before continuing the integration.