d02qgf is a reverse communication routine for integrating a non-stiff system of first-order ordinary differential equations using a variable-order variable-step Adams' method. A root-finding facility is provided.
The routine may be called by the names d02qgf or nagf_ode_ivp_adams_roots_revcom.
3Description
Given the initial values $x,{y}_{1},{y}_{2},\dots ,{y}_{{\mathbf{neqf}}}$d02qgf integrates a non-stiff system of first-order differential equations of the type
from $x={\mathbf{t}}$ to $x={\mathbf{tout}}$ using a variable-order variable-step Adams' method. You define the system by reverse communication, evaluating ${f}_{i}$ in terms of $x$ and ${y}_{1},{y}_{2},\dots ,{y}_{{\mathbf{neqf}}}$, and ${y}_{1},{y}_{2},\dots ,{y}_{{\mathbf{neqf}}}$ are supplied at $x={\mathbf{t}}$ by d02qgf. The routine is capable of finding roots (values of $x$) of prescribed event functions of the form
Each ${g}_{j}$ is considered to be independent of the others so that roots are sought of each ${g}_{j}$ individually. The root reported by the routine will be the first root encountered by any ${g}_{j}$. Two techniques for determining the presence of a root in an integration step are available: the sophisticated method described in Watts (1985) and a simplified method whereby sign changes in each ${g}_{j}$ are looked for at the ends of each integration step. You also define each ${g}_{j}$ by reverse communication. In one-step mode the routine returns an approximation to the solution at each integration point. In interval mode this value is returned at the end of the integration range. If a root is detected this approximation is given at the root. You select the mode of operation, the error control, the root-finding technique and various optional inputs by a prior call to the setup routine d02qwf.
Shampine L F and Gordon M K (1975) Computer Solution of Ordinary Differential Equations – The Initial Value Problem W H Freeman & Co., San Francisco
Shampine L F and Watts H A (1979) DEPAC – design of a user oriented package of ODE solvers Report SAND79-2374 Sandia National Laboratory
Watts H A (1985) RDEAM – An Adams ODE code with root solving capability Report SAND85-1595 Sandia National Laboratory
5Arguments
Note: this routine uses reverse communication. Its use involves an initial entry, intermediate exits and re-entries, and a final exit, as indicated by the argument irevcm. Between intermediate exits and re-entries, all arguments other thangrvcm and rwork must remain unchanged.
1: $\mathbf{neqf}$ – IntegerInput
On initial entry: the number of first-order ordinary differential equations to be solved by d02qgf. It must contain the same value as the argument neqf used in the prior call to d02qwf.
Constraint:
${\mathbf{neqf}}\ge 1$.
2: $\mathbf{t}$ – Real (Kind=nag_wp)Input/Output
On initial entry: that is after a call to d02qwf with ${\mathbf{statef}}=\text{'S'}$, t must be set to the initial value of the independent variable $x$.
On final exit: the value of $x$ at which $y$ has been computed. This may be an intermediate output point, a root, tout or a point at which an error has occurred. If the integration is to be continued, possibly with a new value for tout, t must not be changed.
3: $\mathbf{y}\left({\mathbf{neqf}}\right)$ – Real (Kind=nag_wp) arrayInput/Output
On initial entry: the initial values of the solution ${y}_{1},{y}_{2},\dots ,{y}_{{\mathbf{neqf}}}$.
On final exit: the computed values of the solution at the exit value of t. If the integration is to be continued, possibly with a new value for tout, these values must not be changed.
4: $\mathbf{tout}$ – Real (Kind=nag_wp)Input
On initial entry: the next value of $x$ at which a computed solution is required. For the initial t, the input value of tout is used to determine the direction of integration. Integration is permitted in either direction. If ${\mathbf{tout}}={\mathbf{t}}$ on exit, tout must be reset beyond tin the direction of integration, before any continuation call.
5: $\mathbf{neqg}$ – IntegerInput
On initial entry: the number of event functions which you are defining for root-finding. If root-finding is not required the value for neqg must be $\text{}\le 0$. Otherwise it must be the same value as the argument neqg used in the prior call to d02qwf.
6: $\mathbf{root}$ – LogicalOutput
On final exit: if root-finding was required (${\mathbf{neqg}}>0$ on entry), root specifies whether or not the output value of the argument t is a root of one of the event functions. If ${\mathbf{root}}=\mathrm{.FALSE.}$, no root was detected, whereas ${\mathbf{root}}=\mathrm{.TRUE.}$ indicates a root and you should make a call to d02qyf for further information.
If root-finding was not required (${\mathbf{neqg}}=0$ on entry), ${\mathbf{root}}=\mathrm{.FALSE.}$.
7: $\mathbf{irevcm}$ – IntegerInput/Output
On initial entry: must have the value $0$.
On intermediate exit:
specifies what action you must take before re-entering d02qgfwithirevcmunchanged.
${\mathbf{irevcm}}=1$, $2$, $3$, $4$, $5$, $6$ or $7$
Indicates that you must supply ${y}^{\prime}=f(x,y)$, where $x$ is given by trvcm and
${y}_{\mathit{i}}$ is returned in ${\mathbf{y}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{neqf}}$ when ${\mathbf{yrvcm}}=0$ and
${\mathbf{rwork}}\left({\mathbf{yrvcm}}+\mathit{i}-1\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{neqf}}$ when ${\mathbf{yrvcm}}\ne 0$.
${y}_{\mathit{i}}^{\prime}$ should be placed in location ${\mathbf{rwork}}\left({\mathbf{yprvcm}}+\mathit{i}-1\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{neqf}}$.
${\mathbf{irevcm}}=8$
Indicates that the current step was not successful due to error test failure. The only information supplied to you on this return is the current value of the independent variable t, as given by trvcm. No values must be changed before re-entering d02qgf. This facility enables you to determine the number of unsuccessful steps.
${\mathbf{irevcm}}=9$, $10$, $11$ or $12$
Indicates that you must supply ${g}_{k}(x,y,{y}^{\prime})$, where $k$ is given by kgrvcm, $x$ is given by trvcm, ${y}_{i}$ is given by ${\mathbf{y}}\left(i\right)$ and ${y}_{i}^{\prime}$ is given by ${\mathbf{rwork}}\left({\mathbf{yprvcm}}-1+i\right)$. The result ${g}_{k}$ should be placed in the variable grvcm.
On final exit: has the value $0$, which indicates that an output point or root has been reached or an error has occurred (see ifail).
Note: any values you return to d02qgf as part of the reverse communication procedure should not include floating-point NaN (Not a Number) or infinity values, since these are not handled by d02qgf. If your code does inadvertently return any NaNs or infinities, d02qgf is likely to produce unexpected results.
8: $\mathbf{trvcm}$ – Real (Kind=nag_wp)Output
On intermediate exit:
the current value of the independent variable.
9: $\mathbf{yrvcm}$ – IntegerOutput
On intermediate exit:
with ${\mathbf{irevcm}}=1$, $2$, $3$, $4$, $5$, $6$, $7$, $9$, $10$, $11$ or $12$, yrvcm specifies the locations of the dependent variables $y$ for use in evaluating the differential system or the event functions.
${\mathbf{yrvcm}}=0$
${y}_{\mathit{i}}$ is given by ${\mathbf{y}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{neqf}}$.
${\mathbf{yrvcm}}\ne 0$
${y}_{\mathit{i}}$ is given by ${\mathbf{rwork}}\left({\mathbf{yrvcm}}+\mathit{i}-1\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{neqf}}$.
10: $\mathbf{yprvcm}$ – IntegerOutput
On intermediate exit:
with ${\mathbf{irevcm}}=1$, $2$, $3$, $4$, $5$, $6$ or $7$, yprvcm specifies the positions in rwork at which you should place the derivatives ${y}^{\prime}$.
${y}_{\mathit{i}}^{\prime}$ should be placed in location ${\mathbf{rwork}}\left({\mathbf{yprvcm}}+\mathit{i}-1\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{neqf}}$.
With ${\mathbf{irevcm}}=9$, $10$, $11$ or $12$, yprvcm specifies the locations of the derivatives ${y}^{\prime}$ for use in evaluating the event functions.
${y}_{\mathit{i}}^{\prime}$ is given by ${\mathbf{rwork}}\left({\mathbf{yprvcm}}+\mathit{i}-1\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{neqf}}$.
11: $\mathbf{grvcm}$ – Real (Kind=nag_wp)Input
On initial entry: need not be set.
On intermediate re-entry: with ${\mathbf{irevcm}}=9$, $10$, $11$ or $12$, grvcm must contain the value of ${g}_{k}(x,y,{y}^{\prime})$, where $k$ is given by kgrvcm.
12: $\mathbf{kgrvcm}$ – IntegerInput/Output
On intermediate re-entry: with ${\mathbf{irevcm}}=9$, $10$, $11$ or $12$, kgrvcm must remain unchanged from a previous call to d02qgf.
On intermediate exit:
with ${\mathbf{irevcm}}=9$, $10$, $11$ or $12$, kgrvcm specifies which event function ${g}_{k}(x,y,{y}^{\prime})$ you must evaluate.
13: $\mathbf{rwork}\left({\mathbf{lrwork}}\right)$ – Real (Kind=nag_wp) arrayCommunication Array
This must be the same argument rwork as supplied to d02qwf. It is used to pass information from d02qwf to d02qgf, and from d02qgf to d02qxf,d02qyfandd02qzf. Therefore, the contents of this array mustnot be changed before the call to d02qgf or calling any of the routines d02qxf,d02qyfandd02qzf.
14: $\mathbf{lrwork}$ – IntegerInput
On initial entry: the dimension of the array rwork as declared in the (sub)program from which d02qgf is called.
This must be the same argument lrwork as supplied to d02qwf.
This must be the same argument iwork as supplied to d02qwf. It is used to pass information from d02qwf to d02qgf, and from d02qgf to d02qxf,d02qyfandd02qzf. Therefore, the contents of this array mustnot be changed before the call to d02qgf or calling any of the routines d02qxf,d02qyfandd02qzf.
16: $\mathbf{liwork}$ – IntegerInput
On initial entry: the dimension of the array iwork as declared in the (sub)program from which d02qgf is called.
This must be the same argument liwork as supplied to d02qwf.
17: $\mathbf{ifail}$ – IntegerInput/Output
On initial entry: ifail must be set to $0$, $\mathrm{-1}$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $\mathrm{-1}$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $\mathrm{-1}$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $\mathrm{-1}$ is recommended since useful values can be provided in some output arguments even when ${\mathbf{ifail}}\ne {\mathbf{0}}$ on exit. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On final exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).
6Error Indicators and Warnings
If on entry ${\mathbf{ifail}}=0$ or $\mathrm{-1}$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=1$
On entry, irevcm had an illegal value, $\u27e8\mathit{\text{value}}\u27e9$.
On entry, ${\mathbf{liwork}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{liwork}}=\u27e8\mathit{\text{value}}\u27e9$ in d02qwf.
Constraint: ${\mathbf{liwork}}={\mathbf{liwork}}$ in d02qwf.
On entry, ${\mathbf{lrwork}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{lrwork}}=\u27e8\mathit{\text{value}}\u27e9$ in d02qwf.
Constraint: ${\mathbf{lrwork}}={\mathbf{lrwork}}$ in d02qwf.
On entry, ${\mathbf{neqf}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{neqf}}=\u27e8\mathit{\text{value}}\u27e9$ in d02qwf.
Constraint: ${\mathbf{neqf}}={\mathbf{neqf}}$ in d02qwf.
On entry, ${\mathbf{neqg}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{neqg}}=0$ in d02qwf.
Constraint: if ${\mathbf{neqg}}>0$ then ${\mathbf{neqg}}>0$ in d02qwf.
On entry, ${\mathbf{neqg}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{neqg}}=0$ in d02qwf.
Constraint: if ${\mathbf{neqg}}\le 0$ then ${\mathbf{neqg}}={\mathbf{neqg}}$ in d02qwf.
On entry, ${\mathbf{neqg}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{neqg}}=\u27e8\mathit{\text{value}}\u27e9$ in d02qwf.
Constraint: if ${\mathbf{neqg}}\le 0$ then ${\mathbf{neqg}}\le 0$ in d02qwf.
On entry, ${\mathbf{tout}}=\u27e8\mathit{\text{value}}\u27e9$ but ${\mathbf{crit}}=\mathrm{.TRUE.}$ in d02qwf.
Integration cannot be attempted beyond ${\mathbf{tcrit}}=\u27e8\mathit{\text{value}}\u27e9$.
On entry, ${\mathbf{tout}}={\mathbf{t}}=\u27e8\mathit{\text{value}}\u27e9$.
The call to setup routine d02qwf produced an error.
The value of t has been changed from $\u27e8\mathit{\text{value}}\u27e9$ to $\u27e8\mathit{\text{value}}\u27e9$.
This is not permitted on a continuation call.
The value of tout, $\u27e8\mathit{\text{value}}\u27e9$, indicates a change in the integration direction. This is not permitted on a continuation call.
${\mathbf{ifail}}=2$
The maximum number of steps has been attempted.
If integration is to be continued then the routine may be called again and a further maxstp in d02qwf steps will be attempted.
${\mathbf{ifail}}=3$
The error tolerances are too stringent.
${\mathbf{ifail}}=4$
Error weight $i$ has become zero during the integration. ${\mathbf{atol}}\left(i\right)=0.0$ in d02qwf but ${\mathbf{y}}\left(i\right)$ is now $0.0$. Integration successful as far as t.
${\mathbf{ifail}}=5$
The problem appears to be stiff.
(See the D02 Chapter Introduction for a discussion of the term ‘stiff’). Although it is inefficient to use this integrator to solve stiff problems, integration may be continued by resetting ifail and calling the routine again.
${\mathbf{ifail}}=6$
A change in sign of an event function has been detected but the root-finding process appears to have converged to a singular point of t rather than a root. Integration may be continued by calling the routine again.
${\mathbf{ifail}}=7$
Two successive errors detected at the current value of t, $\u27e8\mathit{\text{value}}\u27e9$.
${\mathbf{ifail}}=-99$
An unexpected error has been triggered by this routine. Please
contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.
7Accuracy
The accuracy of integration is determined by the arguments vectol, rtol and atol in a prior call to d02qwf. Note that only the local error at each step is controlled by these arguments. The error estimates obtained are not strict bounds but are usually reliable over one step. Over a number of steps the overall error may accumulate in various ways, depending on the properties of the differential equation system. The code is designed so that a reduction in the tolerances should lead to an approximately proportional reduction in the error. You are strongly recommended to call d02qgf with more than one set of tolerances and to compare the results obtained to estimate their accuracy.
The accuracy obtained depends on the type of error test used. If the solution oscillates around zero a relative error test should be avoided, whereas if the solution is exponentially increasing an absolute error test should not be used. If different accuracies are required for different components of the solution then a component-wise error test should be used. For a description of the error test see the specifications of the arguments vectol, rtol and atol in the routine document for d02qwf.
The accuracy of any roots located will depend on the accuracy of integration and may also be restricted by the numerical properties of $g(x,y,{y}^{\prime})$. When evaluating $g$ you should try to write the code so that unnecessary cancellation errors will be avoided.
8Parallelism and Performance
Background information to multithreading can be found in the Multithreading documentation.
d02qgf is not thread safe and should not be called from a multithreaded user program. Please see Section 1 in FL Interface Multithreading for more information on thread safety.
d02qgf is not threaded in any implementation.
9Further Comments
If d02qgf fails with ${\mathbf{ifail}}={\mathbf{3}}$ then the combination of atol and rtol may be so small that a solution cannot be obtained, in which case the routine should be called again with larger values for rtol and/or atol (see d02qwf). If the accuracy requested is really needed then you should consider whether there is a more fundamental difficulty. For example:
(a)in the region of a singularity the solution components will usually be of a large magnitude. d02qgf could be used in one-step mode to monitor the size of the solution with the aim of trapping the solution before the singularity. In any case numerical integration cannot be continued through a singularity, and analytical treatment may be necessary;
(b)for ‘stiff’ equations, where the solution contains rapidly decaying components, the routine will require a very small step size to preserve stability. This will usually be exhibited by excessive computing time and sometimes an error exit with ${\mathbf{ifail}}={\mathbf{3}}$, but usually an error exit with ${\mathbf{ifail}}={\mathbf{2}}$ or ${\mathbf{5}}$. The Adams' methods are not efficient in such cases and you should consider using a routine from the Sub-chapter D02M–N. A high proportion of failed steps (see argument nfail in d02qxf) may indicate stiffness but there may be other reasons for this phenomenon.
d02qgf can be used for producing results at short intervals (for example, for graph plotting); you should set ${\mathbf{crit}}=\mathrm{.TRUE.}$ and tcrit to the last output point required in a prior call to d02qwf and then set tout appropriately for each output point in turn in the call to d02qgf.
10Example
This example solves the following system (for a projectile)
over an interval $[0.0,10.0]$ starting with values $y=0.5$, $v=0.5$ and $\varphi =\pi /5$ using scalar error control (${\mathbf{vectol}}=\mathrm{.FALSE.}$) until the first point where $y=0.0$ is encountered.
Also, d02qgf is used to produce output at intervals of $2.0$.