NAG CL Interface
d02qfc (ivp_​adams_​roots)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{neqf}$ – Integer Input

On entry: the number of differential equations.

Constraint: $\mathbf{neqf}\ge 1$.

2: $\mathbf{fcn}$ – function, supplied by the user External Function

fcn must evaluate the functions $f_i$ (that is the first derivatives $y_i^{\prime }$) for given values of its arguments $x,y_1,y_2,\dots ,y_{\mathbf{neqf}}$.

The specification of fcn is:

copy

void  fcn (Integer neqf, double x, const double y[], double f[], Nag_User *comm)

1: $\mathbf{neqf}$ – Integer Input

On entry: the number of differential equations.

2: $\mathbf{x}$ – double Input

On entry: the current value of the argument $x$.

3: $\mathbf{y}\left[\mathbf{neqf}\right]$ – const double Input

On entry: $\mathbf{y}\left[\mathit{i}-1\right]$ contains the current value of the argument $y_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,\mathbf{neqf}$.

4: $\mathbf{f}\left[\mathbf{neqf}\right]$ – double Output

On exit: $\mathbf{f}\left[\mathit{i}-1\right]$ must contain the value of $f_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,\mathbf{neqf}$.

5: $\mathbf{comm}$ – Nag_User *

Pointer to a structure of type Nag_User with the following member:

p – Pointer 

On entry/exit: the pointer $\mathbf{comm}\mathbf{\to }\mathbf{p}$ should be cast to the required type, e.g., struct user *s = (struct user *)comm → p, to obtain the original object's address with appropriate type.

Note: fcn should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02qfc. If your code inadvertently does return any NaNs or infinities, d02qfc is likely to produce unexpected results.

3: $\mathbf{t}$ – double * Input/Output

On entry: after a call to d02qwc with $\mathbf{state}=\mathrm{Nag\_NewStart}$ (i.e., an initial entry), t must be set to the initial value of the independent variable $x$.

On 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.

4: $\mathbf{y}\left[\mathbf{neqf}\right]$ – double Input/Output

On entry: the initial values of the solution $y_1,y_2,\dots ,y_{\mathbf{neqf}}$.

On 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.

5: $\mathbf{tout}$ – double Input

On 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.

6: $\mathbf{g}$ – function, supplied by the user External Function

g must evaluate a given component of $g(x,y,y^{\prime })$ at a specified point.

If root-finding is not required the actual argument for g must be the NAG defined null double function pointer NULLDFN.

The specification of g is:

copy

double  g (Integer neqf, double x, const double y[], const double yp[], Integer k, Nag_User *comm)

1: $\mathbf{neqf}$ – Integer Input

On entry: the number of differential equations.

2: $\mathbf{x}$ – double Input

On entry: the current value of the independent variable.

3: $\mathbf{y}\left[\mathbf{neqf}\right]$ – const double Input

On entry: the current values of the dependent variables.

4: $\mathbf{yp}\left[\mathbf{neqf}\right]$ – const double Input

On entry: the current values of the derivatives of the dependent variables.

5: $\mathbf{k}$ – Integer Input

On entry: the component of $g$ which must be evaluated.

6: $\mathbf{comm}$ – Nag_User *

Pointer to a structure of type Nag_User with the following member:

p – Pointer 

On entry/exit: the pointer $\mathbf{comm}\mathbf{\to }\mathbf{p}$ should be cast to the required type, e.g., struct user *s = (struct user *)comm → p, to obtain the original object's address with appropriate type.

Note: g should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02qfc. If your code inadvertently does return any NaNs or infinities, d02qfc is likely to produce unexpected results.

7: $\mathbf{comm}$ – Nag_User *

Pointer to a structure of type Nag_User with the following member:

p – Pointer 

On entry/exit: the pointer $\mathbf{comm}\mathbf{\to }\mathbf{p}$, of type Pointer, allows you to communicate information to and from fcn and g. An object of the required type should be declared, e.g., a structure, and its address assigned to the pointer $\mathbf{comm}\mathbf{\to }\mathbf{p}$ by means of a cast to Pointer in the calling program. E.g. comm.p = (Pointer)&s.

8: $\mathbf{opt}$ – Nag_ODE_Adams *

Pointer to a structure of type Nag_ODE_Adams as initialized by the setup function d02qwc with the following members:

root – Nag_BooleanOutput

On exit: if root-finding was required ($\mathbf{neqg}>0$ in a call to the setup function d02qwc ), then $\mathbf{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{Nag\_FALSE}$, then no root was detected, whereas $\mathbf{root}=\mathrm{Nag\_TRUE}$ indicates a root.

If root-finding was not required ($\mathbf{neqg}=0$) then on exit $\mathbf{root}=\mathrm{Nag\_FALSE}$.

If $\mathbf{root}=\mathrm{Nag\_FALSE}$, then $\mathbf{opt}\mathbf{\to }\mathbf{index}$, $\mathbf{opt}\mathbf{\to }\mathbf{type}$, $\mathbf{opt}\mathbf{\to }\mathbf{events}$ and $\mathbf{opt}\mathbf{\to }\mathbf{resids}$ are indeterminate.

index – IntegerOutput

On exit: the index $k$ of the event equation $g_k(x,y,y^{\prime })=0$ for which the root has been detected.

type – IntegerOutput

On exit: information about the root detected for the event equation defined by $\mathbf{opt}\mathbf{\to }\mathbf{index}$. The possible values of $\mathbf{type}$ with their interpretations are as follows:

• If $\mathbf{type}=1$, a simple root, or lack of distinguishing information available.
• If $\mathbf{type}=2$, a root of even multiplicity is believed to have been detected, that is no change in sign of the event function was found.
• If $\mathbf{type}=3$, a high order root of odd multiplicity.
• If $\mathbf{type}=4$, a possible root, but due to high multiplicity or a clustering of roots accurate evaluation of the event function was prohibited by round-off error and/or cancellation.

In general, the accuracy of the root is less reliable for values of $\mathbf{type}>1$.

events – Integer *Output

On exit: array pointer containing information about the $k$th event function on a very small interval containing the root, t. All roots lying in this interval are considered indistinguishable numerically and, therefore, should be regarded as defining a root at t. The possible values of $\mathbf{events}\left[j-1\right]$, $j=1,2,\dots ,$neqg, with their interpretations are as follows:

• $\mathbf{events}\left[j-1\right]=0$, the $j$th event function did not have a root;
• $\mathbf{events}\left[j-1\right]=\mathrm{-1}$, the $j$th event function changed sign from positive to negative about a root, in the direction of integration;
• $\mathbf{events}\left[j-1\right]=1$, the $j$th event function changed sign from negative to positive about a root, in the direction of integration;
• $\mathbf{events}\left[j-1\right]=2$, a root was identified, but no change in sign was observed.

resids – doubleOutput

On exit: array pointer, $\mathbf{opt}\mathbf{\to }\mathbf{resids}\left[j-1\right]$, $j=1,2,\dots ,$neqg, contains value of the $j$th event function computed at the root, t.

yp – doubleOutput

On exit: array pointer to the approximate derivative of the solution component $y_i$ at the output value of t. These values are obtained by the evaluation of $y^{\prime }=f(x,y)$ except when the output value of the argument t is tout and $\mathbf{opt}\mathbf{\to }\mathbf{tcurr}\ne \mathbf{tout}$, in which case they are obtained by interpolation.

tcurr – doubleOutput

On exit: the value of the independent variable which the integrator has actually reached. $\mathbf{tcurr}$ will always be at least as far as the output value of the argument t in the direction of integration, but may be further.

hlast – doubleOutput

On exit: the last successful step size used in the integration.

hnext – doubleOutput

On exit: the next step size which the integration would attempt.

ord_last – IntegerOutput

On exit: the order of the method last used (successfully) in the integration.

ord_next – IntegerOutput

On exit: the order of the method which the integration would attempt on the next step.

nsuccess – IntegerOutput

On exit: the number of integration steps attempted that have been successful since the start of the current problem.

nfail – IntegerOutput

On exit: the number of integration steps attempted that have failed since the start of the current problem.

tolfac – doubleOutput

On exit: a tolerance scale factor, $\mathbf{tolfac}\ge 1.0$, returned when d02qfc exits with $\mathbf{fail}\mathbf{.}\mathbf{code}=\mathbf{NE\_ODE\_TOL}$. If rtol and atol are uniformly scaled up by a factor of $\mathbf{tolfac}$ and d02qwc is called, the next call to d02qfc is deemed likely to succeed.

9: $\mathbf{fail}$ – NagError * Input/Output

The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_DIRECTION_CHANGE

The value of tout, $⟨\mathit{\text{value}}⟩$, indicates a change in the integration direction. This is not permitted on a continuation call.

NE_MAX_STEP

The maximum number of steps have been attempted.

If integration is to be continued then the function may be called again and a further max_step steps will be attempted (see d02qwc for details of max_step ).

NE_NEQF

The value of neqf supplied is not the same as that given to the setup function d02qwc. $\mathbf{neqf}=⟨\mathit{\text{value}}⟩$ but the value given to
d02qwc was $⟨\mathit{\text{value}}⟩$.

NE_NO_G_FUN

Root finding has been requested by setting $\mathbf{neqg}>0$, $\mathbf{neqg}=⟨\mathit{\text{value}}⟩$, but argument g is a null function.

NE_NO_SETUP

The setup function d02qwc has not been called.

NE_ODE_TOL

The error tolerances are too stringent. rtol and atol should be scaled up by the factor $\mathbf{opt}\mathbf{\to }\mathbf{tolfac}$ and the integration function re-entered. $\mathbf{opt}\mathbf{\to }\mathbf{tolfac}=⟨\mathit{\text{value}}⟩$ (see Section 9).

NE_SETUP_ERROR

The call to setup function d02qwc produced an error.

NE_SINGULAR_POINT

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 function again.

NE_STIFF_PROBLEM

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 fail and calling the function again.

NE_T_CHANGED

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

NE_T_SAME_TOUT

On entry, $\mathbf{tout}=\mathbf{t}$, t is $⟨\mathit{\text{value}}⟩$.

NE_TOUT_TCRIT

$\mathbf{tout}=⟨\mathit{\text{value}}⟩$ but crit was set Nag_TRUE in setup call and integration cannot be attempted beyond $\mathbf{tcrit}=⟨\mathit{\text{value}}⟩$.

NE_WEIGHT_ZERO

An error weight has become zero during the integration, see d02qwc document; $\mathbf{atol}\left[⟨\mathit{\text{value}}⟩\right]$ was set to $0.0$ but $\mathbf{y}\left[⟨\mathit{\text{value}}⟩\right]$ is now $0.0$. Integration successful as far as $\mathbf{t}=⟨\mathit{\text{value}}⟩$.

The value of the array index is returned in $\mathbf{fail}\mathbf{.}\mathbf{errnum}$.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results