The function may be called by the names: d02nec, nag_ode_dae_dassl_gen or nag_dae_ivp_dassl_gen.
3Description
d02nec 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{.}$$
d02nec 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({\mathbf{t}},{\mathbf{y}},{\mathbf{ydot}})=0$). The function solves the system from $t={\mathbf{t}}$ to $t={\mathbf{tout}}$.
An outline of a typical calling program for d02nec is given below. It calls the DASSL implementation of the BDF integrator setup function d02mwc and the banded matrix setup function d02npc (if required), and, if the integration needs to proceed, calls d02mcc before continuing the integration.
/* declarations */
EXTERN res, jac
.
.
.
/* Initialize the integrator */
nag_ode_dae_dassl_setup(...);
/* Is the Jacobian matrix banded? */
if (banded) {nag_ode_dae_dassl_linalg(...);}
/* Set dt to the required temporal resolution */
/* Set tend to the final time */
/* Call the integrator for each temporal value */
itask = 0;
while (tout<tend && itask>-1) {
nag_ode_dae_dassl_gen (...);
if (itask != 1)
tout = MIN(tout+dt,tend);
/* Print the solution */
}
.
.
.
4References
None.
5Arguments
1: $\mathbf{neq}$ – IntegerInput
On entry: the number of differential-algebraic equations to be solved.
Constraint:
${\mathbf{neq}}\ge 1$.
2: $\mathbf{t}$ – double *Input/Output
On initial entry: the initial value of the independent variable, $t$.
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).
3: $\mathbf{tout}$ – doubleInput
On entry: 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).
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.
On exit: the time derivatives ${y}^{\prime}$ of the vector $y$ at the last integration point.
Note: the dimension, dim, of the array rtol depends on the value of vector_tol as set in d02mwc; it
must be at least
${\mathbf{neq}}$ when ${\mathbf{vector\_tol}}=\mathrm{Nag\_TRUE}$ was set in d02mwc;
$1$ when ${\mathbf{vector\_tol}}=\mathrm{Nag\_FALSE}$ was set in d02mwc.
On entry: the relative local error tolerance.
Constraint:
${\mathbf{rtol}}\left[\mathit{i}-1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,n$
where $n={\mathbf{neq}}$ when ${\mathbf{vector\_tol}}=\mathrm{Nag\_TRUE}$ and $n=1$ otherwise.
On exit: rtol remains unchanged unless d02nec exits with ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$NE_ODE_TOL in which case the values may have been increased to values estimated to be appropriate for continuing the integration.
Note: the dimension, dim, of the array atol depends on the value of vector_tol as set in d02mwc; it
must be at least
${\mathbf{neq}}$ when ${\mathbf{vector\_tol}}=\mathrm{Nag\_TRUE}$ was set in d02mwc;
$1$ when ${\mathbf{vector\_tol}}=\mathrm{Nag\_FALSE}$ was set in d02mwc.
On entry: the absolute local error tolerance.
Constraint:
${\mathbf{atol}}\left[\mathit{i}-1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,n$
where $n={\mathbf{neq}}$ when ${\mathbf{vector\_tol}}=\mathrm{Nag\_TRUE}$ and $n=1$ otherwise.
On exit: atol remains unchanged unless d02nec exits with ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$NE_ODE_TOL in which case the values may have been increased to values estimated to be appropriate for continuing the integration.
8: $\mathbf{itask}$ – Integer *Input/Output
On initial entry: need not be set.
On exit: the task performed by the integrator on successful completion or an indicator that a problem occurred during integration.
${\mathbf{itask}}=2$
The integration to tout was successfully completed (${\mathbf{t}}={\mathbf{tout}}$) by stepping exactly to tout.
${\mathbf{itask}}=3$
The integration to tout was successfully completed (${\mathbf{t}}={\mathbf{tout}}$) by stepping past tout. y and ydot are obtained by interpolation.
${\mathbf{itask}}<0$
Different negative values of itask returned correspond to different failure exits. fail should always be checked in such cases and the corrective action taken where appropriate.
itask must remain unchanged between calls to d02nec.
9: $\mathbf{res}$ – function, supplied by the userExternal Function
On exit: ires should normally be left unchanged. However, if an illegal value of y is encountered, ires should be set to $\mathrm{-1}$; d02nec will then attempt to resolve the problem so that illegal values of y are not encountered. ires should be set to $\mathrm{-2}$ if you wish to return control to the calling function; this will cause d02nec to exit with ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$NE_RES_FLAG.
7: $\mathbf{comm}$ – Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to res.
user – double *
iuser – Integer *
p – Pointer
The type Pointer will be void *. Before calling d02nec you may allocate memory and initialize these pointers with various quantities for use by res when called from d02nec (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).
Note:res should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02nec. If your code inadvertently does return any NaNs or infinities, d02nec is likely to produce unexpected results.
10: $\mathbf{jac}$ – function, supplied by the userExternal Function
Evaluates the matrix of partial derivatives, $J$, where
If this option is not required, the actual argument for jac must be specified as NULLFN. You must indicate to the integrator whether this option is to be used by setting the argument jceval appropriately in a call to the setup function d02mwc.
Note: the dimension of the array pd will be ${\mathbf{neq}}\times {\mathbf{neq}}$ when the Jacobian is full and will be $(2\times {\mathbf{ml}}+{\mathbf{mu}}+1)\times {\mathbf{neq}}$ when the Jacobian is banded (that is, a prior call to d02npc has been made).
On entry: pd is preset to zero before the call to jac.
On exit: if the Jacobian is full then
${\mathbf{pd}}\left[(\mathit{j}-1)\times {\mathbf{neq}}+\mathit{i}-1\right]={J}_{\mathit{i}\mathit{j}}$, for $\mathit{i}=1,2,\dots ,{\mathbf{neq}}$ and $\mathit{j}=1,2,\dots ,{\mathbf{neq}}$; if the Jacobian is banded then ${\mathbf{pd}}\left[(j-1)\times (2{\mathbf{ml}}+{\mathbf{mu}}+1)+{\mathbf{ml}}+{\mathbf{mu}}+i-j\right]={J}_{ij}$, for $\mathrm{max}\phantom{\rule{0.125em}{0ex}}(1,j-{\mathbf{mu}})\le i\le \mathrm{min}\phantom{\rule{0.125em}{0ex}}(n,j+{\mathbf{ml}})$.
6: $\mathbf{cj}$ – doubleInput
On entry: cj is a scalar constant which will be defined in d02nec.
7: $\mathbf{comm}$ – Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to jac.
user – double *
iuser – Integer *
p – Pointer
The type Pointer will be void *. Before calling d02nec you may allocate memory and initialize these pointers with various quantities for use by jac when called from d02nec (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).
Note:jac should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02nec. If your code inadvertently does return any NaNs or infinities, d02nec is likely to produce unexpected results.
com contains information which is usually of no interest, but is necessary for subsequent calls. However you may find the following useful:
${\mathbf{com}}\left[2\right]$
The step size to be attempted on the next step.
${\mathbf{com}}\left[3\right]$
The current value of the independent variable, i.e., the farthest point integration has reached. This will be different from t only when interpolation has been performed (${\mathbf{itask}}=3$).
Constraint:
${\mathbf{lcom}}\ge 40+(\mathit{maxorder}+4)\times {\mathbf{neq}}+{\mathbf{neq}}\times p+q$ where $\mathit{maxorder}$ is the maximum order that can be used by the integration method (see maxord in d02mwc); $p={\mathbf{neq}}$ when the Jacobian is full and $p=(2\times {\mathbf{ml}}+{\mathbf{mu}}+1)$ when the Jacobian is banded; and, $q=({\mathbf{neq}}/({\mathbf{ml}}+{\mathbf{mu}}+1))+1$ when the Jacobian is to be evaluated numerically and $q=0$ otherwise.
14: $\mathbf{comm}$ – Nag_Comm *
The NAG communication argument (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).
15: $\mathbf{fail}$ – NagError *Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).
6Error Indicators and Warnings
NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
On entry, argument $\u27e8\mathit{\text{value}}\u27e9$ had an illegal value.
NE_CONV_CONT
The corrector could not converge and the error test failed repeatedly. ${\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$. Stepsize $h=\u27e8\mathit{\text{value}}\u27e9$.
The corrector repeatedly failed to converge with $\left|h\right|=\mathit{hmin}$. ${\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$. Stepsize $h=\u27e8\mathit{\text{value}}\u27e9$.
NE_CONV_JACOBG
The iteration matrix is singular. ${\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$. Stepsize $h=\u27e8\mathit{\text{value}}\u27e9$.
NE_CONV_ROUNDOFF
The error test failed repeatedly with $\left|h\right|=\mathit{hmin}$. ${\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$. Stepsize $h=\u27e8\mathit{\text{value}}\u27e9$.
NE_INITIALIZATION
Either the initialization function has not been called prior to the first call of this function or a communication array has become corrupted.
NE_INT
A previous call to this function returned with ${\mathbf{itask}}=\u27e8\mathit{\text{value}}\u27e9$ and no appropriate action was taken.
NE_INT_2
com array is of insufficient length; length required $\text{}=\u27e8\mathit{\text{value}}\u27e9$; actual length ${\mathbf{lcom}}=\u27e8\mathit{\text{value}}\u27e9$.
NE_INT_ARG_LT
On entry, ${\mathbf{neq}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{neq}}\ge 1$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_MAX_STEP
Maximum number of steps taken on this call before reaching tout: ${\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$, maximum number of steps $\text{}=\u27e8\mathit{\text{value}}\u27e9$.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
NE_ODE_TOL
A solution component has become zero when a purely relative tolerance (zero absolute tolerance) was selected for that component. ${\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$, ${\mathbf{y}}\left[\mathit{I}-1\right]=\u27e8\mathit{\text{value}}\u27e9$ for component $\mathit{I}=\u27e8\mathit{\text{value}}\u27e9$.
Too much accuracy requested for precision of machine. rtol and atol were increased by scale factor $R$. Try running again with these scaled tolerances. ${\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$, $R=\u27e8\mathit{\text{value}}\u27e9$.
NE_REAL_2
tout is behind t in the direction of $h$: ${\mathbf{tout}}-{\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$, $h=\u27e8\mathit{\text{value}}\u27e9$.
tout is too close to t to start integration: ${\mathbf{tout}}-{\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$: $\mathit{hmin}=\u27e8\mathit{\text{value}}\u27e9$.
NE_REAL_ARG_EQ
On entry, ${\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{tout}}\ne {\mathbf{t}}$.
NE_RES_FLAG
ires was set to $-1$ during a call to res and could not be resolved. ${\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$. Stepsize $h=\u27e8\mathit{\text{value}}\u27e9$.
ires was set to $-2$ during a call to res. ${\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$. Stepsize $\text{}=\u27e8\mathit{\text{value}}\u27e9$.
Repeated occurrences of input constraint violations have been detected. This could result in a potential infinite loop: ${\mathbf{itask}}=\u27e8\mathit{\text{value}}\u27e9$. Current violation corresponds to exit with ${\mathbf{fail}}\mathbf{.}\mathbf{code}=\u27e8\mathit{\text{value}}\u27e9$.
NE_SINGULAR_POINT
The initial ydot could not be computed. ${\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$. Stepsize $h=\u27e8\mathit{\text{value}}\u27e9$.
7Accuracy
The accuracy of the numerical solution may be controlled by a careful choice of the arguments rtol and atol. You are advised to use scalar error control unless the components of the solution are expected to be poorly scaled. For the type of decaying solution typical of many stiff problems, relative error control with a small absolute error threshold will be most appropriate (that is, you are advised to choose ${\mathbf{vector\_tol}}=\mathrm{Nag\_FALSE}$ with ${\mathbf{atol}}\left[0\right]$ small but positive).
8Parallelism and Performance
d02nec is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
d02nec makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.
9Further Comments
The cost of computing a solution depends critically on the size of the differential system and to a lesser extent on the degree of stiffness of the problem. For banded systems the cost is proportional to ${\mathbf{neq}}\times {({\mathbf{ml}}+{\mathbf{mu}}+1)}^{2}$, while for full systems the cost is proportional to
${{\mathbf{neq}}}^{3}$. Note however that for moderately sized problems which are only mildly nonlinear the cost may be dominated by factors proportional to ${\mathbf{neq}}\times ({\mathbf{ml}}+{\mathbf{mu}}+1)$ and ${{\mathbf{neq}}}^{2}$ respectively.
10Example
This example solves the well-known stiff Robertson problem written in implicit form