NAG Library Routine Document

d02qgf (ivp_adams_roots_revcom)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

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 t in 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 $\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 d02qgf with irevcm unchanged.

$\mathbf{irevcm}=1$, $2$, $3$, $4$, $5$, $6$ or $7$

Indicates that you must supply $y^{\prime }=f\left(x,y\right)$, 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\left(x,y,y^{\prime }\right)$, 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\left(x,y,y^{\prime }\right)$, 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\left(x,y,y^{\prime }\right)$ 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, d02qyf and d02qzf. Therefore the contents of this array must not be changed before the call to d02qgf or calling any of the routines d02qxf, d02qyf and d02qzf.

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.

15:   $\mathbf{iwork}\left(\mathbf{liwork}\right)$ – Integer arrayCommunication Array

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, d02qyf and d02qzf. Therefore the contents of this array must not be changed before the call to d02qgf or calling any of the routines d02qxf, d02qyf and d02qzf.

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$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if $\mathbf{ifail}\ne \mathbf{0}$ on exit, the recommended value is $-1$. When the value $-\mathbf{1}\text{ or }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).

6

Error Indicators and Warnings

$\mathbf{ifail}=1$

On entry, irevcm had an illegal value, $〈\mathit{\text{value}}〉$.

On entry, $\mathbf{liwork}=〈\mathit{\text{value}}〉$ and $\mathbf{liwork}=〈\mathit{\text{value}}〉$ in d02qwf.
Constraint: $\mathbf{liwork}=\mathbf{liwork}$ in d02qwf.

On entry, $\mathbf{lrwork}=〈\mathit{\text{value}}〉$ and $\mathbf{lrwork}=〈\mathit{\text{value}}〉$ in d02qwf.
Constraint: $\mathbf{lrwork}=\mathbf{lrwork}$ in d02qwf.

On entry, $\mathbf{neqf}=〈\mathit{\text{value}}〉$ and $\mathbf{neqf}=〈\mathit{\text{value}}〉$ in d02qwf.
Constraint: $\mathbf{neqf}=\mathbf{neqf}$ in d02qwf.

On entry, $\mathbf{neqg}=〈\mathit{\text{value}}〉$ and $\mathbf{neqg}=0$ in d02qwf.
Constraint: if $\mathbf{neqg}>0$ then $\mathbf{neqg}>0$ in d02qwf.

On entry, $\mathbf{neqg}=〈\mathit{\text{value}}〉$ and $\mathbf{neqg}=0$ in d02qwf.
Constraint: if $\mathbf{neqg}\le 0$ then $\mathbf{neqg}=\mathbf{neqg}$ in d02qwf.

On entry, $\mathbf{neqg}=〈\mathit{\text{value}}〉$ and $\mathbf{neqg}=〈\mathit{\text{value}}〉$ in d02qwf.
Constraint: if $\mathbf{neqg}\le 0$ then $\mathbf{neqg}\le 0$ in d02qwf.

On entry, $\mathbf{tout}=〈\mathit{\text{value}}〉$ but $\mathbf{crit}=\mathrm{.TRUE.}$ in d02qwf.
Integration cannot be attempted beyond $\mathbf{tcrit}=〈\mathit{\text{value}}〉$.

On entry, $\mathbf{tout}=\mathbf{t}=〈\mathit{\text{value}}〉$.

The call to setup routine d02qwf produced an error.

The setup routine d02qwf has not been called.

The value of t has been changed from $〈\mathit{\text{value}}〉$ to $〈\mathit{\text{value}}〉$.
This is not permitted on a continuation call.

The value of tout, $〈\mathit{\text{value}}〉$, 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$ 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, $〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 3.9 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (d02qgfe.f90)

10.2

Program Data

Program Data (d02qgfe.d)

10.3

Program Results

Program Results (d02qgfe.r)