NAG C Library Function Document

nag_ode_ivp_adams_roots (d02qfc)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:    $\mathbf{neqf}$ – IntegerInput

On entry: the number of differential equations.

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

2:    $\mathbf{fcn}$ – function, supplied by the userExternal 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:

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

1:    $\mathbf{neqf}$ – IntegerInput

On entry: the number of differential equations.

2:    $\mathbf{x}$ – doubleInput

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

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

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]$ – doubleOutput

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 nag_ode_ivp_adams_roots (d02qfc). If your code inadvertently does return any NaNs or infinities, nag_ode_ivp_adams_roots (d02qfc) is likely to produce unexpected results.

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

On entry: after a call to nag_ode_ivp_adams_setup (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]$ – doubleInput/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}$ – doubleInput

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 userExternal Function

g must evaluate a given component of $g\left(x,y,y^{\prime }\right)$ 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:

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

1:    $\mathbf{neqf}$ – IntegerInput

On entry: the number of differential equations.

2:    $\mathbf{x}$ – doubleInput

On entry: the current value of the independent variable.

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

On entry: the current values of the dependent variables.

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

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

5:    $\mathbf{k}$ – IntegerInput

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 nag_ode_ivp_adams_roots (d02qfc). If your code inadvertently does return any NaNs or infinities, nag_ode_ivp_adams_roots (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 nag_ode_ivp_adams_setup (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 nag_ode_ivp_adams_setup (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\left(x,y,y^{\prime }\right)=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]=-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\left(x,y\right)$ 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 nag_ode_ivp_adams_roots (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 nag_ode_ivp_adams_setup (d02qwc) is called, the next call to nag_ode_ivp_adams_roots (d02qfc) is deemed likely to succeed.

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

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

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 nag_ode_ivp_adams_setup (d02qwc) for details of max_step ).

NE_NEQF

The value of neqf supplied is not the same as that given to the setup function nag_ode_ivp_adams_setup (d02qwc). $\mathbf{neqf}=〈\mathit{\text{value}}〉$ but the value given to
nag_ode_ivp_adams_setup (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 nag_ode_ivp_adams_setup (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 nag_ode_ivp_adams_setup (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

Program Text (d02qfce.c)

10.2

Program Data

10.3

Program Results

Program Results (d02qfce.r)