NAG FL Interface
d02laf (ivp_2nd_rkn)
1
Purpose
d02laf is a routine for integrating a nonstiff system of secondorder ordinary differential equations using Runge–Kutta–Nystrom techniques.
2
Specification
Fortran Interface
Integer, Intent (In) 
:: 
neq, lrwork 
Integer, Intent (Inout) 
:: 
ifail 
Real (Kind=nag_wp), Intent (In) 
:: 
tend 
Real (Kind=nag_wp), Intent (Inout) 
:: 
t, y(neq), yp(neq), ydp(neq), rwork(lrwork) 
External 
:: 
fcn 

C Header Interface
#include <nag.h>
void 
d02laf_ ( void (NAG_CALL *fcn)(const Integer *neq, const double *t, const double y[], double f[]), const Integer *neq, double *t, const double *tend, double y[], double yp[], double ydp[], double rwork[], const Integer *lrwork, Integer *ifail) 

C++ Header Interface
#include <nag.h> extern "C" {
void 
d02laf_ ( void (NAG_CALL *fcn)(const Integer &neq, const double &t, const double y[], double f[]), const Integer &neq, double &t, const double &tend, double y[], double yp[], double ydp[], double rwork[], const Integer &lrwork, Integer &ifail) 
}

The routine may be called by the names d02laf or nagf_ode_ivp_2nd_rkn.
3
Description
Given the initial values
$x,{y}_{1},{y}_{2},\dots ,{y}_{{\mathbf{neq}}},{y}_{1}^{\prime},{y}_{2}^{\prime},\dots ,{y}_{{\mathbf{neq}}}^{\prime}$ d02laf integrates a nonstiff system of secondorder differential equations of the type
from
$x={\mathbf{t}}$ to
$x={\mathbf{tend}}$ using a Runge–Kutta–Nystrom formula pair. The system is defined by
fcn, which evaluates
${f}_{i}$ in terms of
$x$ and
${y}_{1},{y}_{2},\dots ,{y}_{{\mathbf{neq}}}$, where
${y}_{1},{y}_{2},\dots ,{y}_{{\mathbf{neq}}}$ are supplied at
$x$.
There are two Runge–Kutta–Nystrom formula pairs implemented in this routine. The lower order method is intended if you have moderate accuracy requirements and may be used in conjunction with the interpolation routine
d02lzf to produce solutions and derivatives at userspecified points. The higher order method is intended if you have high accuracy requirements.
In onestep mode the routine returns approximations to the solution, derivative and
${f}_{i}$ at each integration point. In interval mode these values are returned at the end of the integration range. You select the order of the method, the mode of operation, the error control and various optional inputs by a prior call to
d02lxf.
For a description of the Runge–Kutta–Nystrom formula pairs see
Dormand et al. (1986a) and
Dormand et al. (1986b) and for a description of their practical implementation see
Brankin et al. (1989).
4
References
Brankin R W, Dormand J R, Gladwell I, Prince P J and Seward W L (1989) Algorithm 670: A Runge–Kutta–Nystrom Code ACM Trans. Math. Software 15 31–40
Dormand J R, El–Mikkawy M E A and Prince P J (1986a) Families of Runge–Kutta–Nystrom formulae Mathematical Report TPMR 861 Teesside Polytechnic
Dormand J R, El–Mikkawy M E A and Prince P J (1986b) High order embedded Runge–Kutta–Nystrom formulae Mathematical Report TPMR 862 Teesside Polytechnic
5
Arguments

1:
$\mathbf{fcn}$ – Subroutine, supplied by the user.
External Procedure

fcn must evaluate the functions
${f}_{i}$ (that is the second derivatives
${y}_{i}^{\prime \prime}$) for given values of its arguments
$x$,
${y}_{1},{y}_{2},\dots ,{y}_{{\mathbf{neq}}}$.
The specification of
fcn is:
Fortran Interface
Subroutine fcn ( 
neq, t, y, f) 
Integer, Intent (In) 
:: 
neq 
Real (Kind=nag_wp), Intent (In) 
:: 
t, y(neq) 
Real (Kind=nag_wp), Intent (Out) 
:: 
f(neq) 

C Header Interface
void 
fcn_ (const Integer *neq, const double *t, const double y[], double f[]) 

C++ Header Interface
#include <nag.h> extern "C" {
void 
fcn_ (const Integer &neq, const double &t, const double y[], double f[]) 
}


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

On entry: the number of differential equations.

2:
$\mathbf{t}$ – Real (Kind=nag_wp)
Input

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

3:
$\mathbf{y}\left({\mathbf{neq}}\right)$ – Real (Kind=nag_wp) array
Input

On entry: ${y}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{\mathbf{neq}}$, the value of the argument.

4:
$\mathbf{f}\left({\mathbf{neq}}\right)$ – Real (Kind=nag_wp) array
Output

On exit: the value of
${f}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{\mathbf{neq}}$.
fcn must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which
d02laf is called. Arguments denoted as
Input must
not be changed by this procedure.
Note: fcn should not return floatingpoint NaN (Not a Number) or infinity values, since these are not handled by
d02laf. If your code inadvertently
does return any NaNs or infinities,
d02laf is likely to produce unexpected results.

2:
$\mathbf{neq}$ – Integer
Input

On entry: the number of secondorder ordinary differential equations to be solved by
d02laf. It must contain the same value as the argument
neq used in a prior call to
d02lxf.
Constraint:
${\mathbf{neq}}\ge 1$.

3:
$\mathbf{t}$ – Real (Kind=nag_wp)
Input/Output

On entry: the initial value of the independent variable $x$.
Constraint:
${\mathbf{t}}\ne {\mathbf{tend}}$.
On exit: the value of the independent variable, which is usually
tend, unless an error has occurred or the code is operating in onestep mode. If the integration is to be continued, possibly with a new value for
tend,
t must not be changed.

4:
$\mathbf{tend}$ – Real (Kind=nag_wp)
Input

On entry: the end point of the range of integration. If
${\mathbf{tend}}<{\mathbf{t}}$ on initial entry, integration will proceed in the negative direction.
tend may be reset, in the direction of integration, before any continuation call.

5:
$\mathbf{y}\left({\mathbf{neq}}\right)$ – Real (Kind=nag_wp) array
Input/Output

On entry: the initial values of the solution ${y}_{1},{y}_{2},\dots ,{y}_{{\mathbf{neq}}}$.
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
tend, these values must not be changed.

6:
$\mathbf{yp}\left({\mathbf{neq}}\right)$ – Real (Kind=nag_wp) array
Input/Output

On entry: the initial values of the derivatives ${y}_{1}^{\prime},{y}_{2}^{\prime},\dots ,{y}_{{\mathbf{neq}}}^{\prime}$.
On exit: the computed values of the derivatives at the exit value of
t. If the integration is to be continued, possibly with a new value for
tend, these values must not be changed.

7:
$\mathbf{ydp}\left({\mathbf{neq}}\right)$ – Real (Kind=nag_wp) array
Input/Output

On entry: must be unchanged from a previous call to d02laf.
On exit: the computed values of the second derivative at the exit value of
t, unless illegal input is detected, in which case the elements of
ydp may not have been initialized. If the integration is to be continued, possibly with a new value for
tend, these values must not be changed.

8:
$\mathbf{rwork}\left({\mathbf{lrwork}}\right)$ – Real (Kind=nag_wp) array
Communication Array

This
must be the same argument
rwork as supplied to
d02lxf. It is used to pass information from
d02lxf to
d02laf, and from
d02laf to both
d02lyf and
d02lzf. Therefore the contents of this array
must not be changed before the call to
d02laf or calling either of the routines
d02lyf and
d02lzf.

9:
$\mathbf{lrwork}$ – Integer
Input

On entry: the dimension of the array
rwork as declared in the (sub)program from which
d02laf is called.
This must be the same argument
lrwork as supplied to
d02lxf.

10:
$\mathbf{ifail}$ – Integer
Input/Output

On entry:
ifail must be set to
$0$,
$1\text{or}1$. If you are unfamiliar with this argument you should refer to
Section 4 in the Introduction to the NAG Library FL Interface 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 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
If on entry
${\mathbf{ifail}}=0$ or
$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, ${\mathbf{lrwork}}=\u2329\mathit{\text{value}}\u232a$, but in the previous call to the setup routine ${\mathbf{lrwork}}=\u2329\mathit{\text{value}}\u232a$.
On entry, ${\mathbf{neq}}=\u2329\mathit{\text{value}}\u232a$, but in the previous call to the setup routine ${\mathbf{neq}}=\u2329\mathit{\text{value}}\u232a$.
On entry, ${\mathbf{t}}=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{tend}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{t}}\ne {\mathbf{tend}}$.
tend has been reset such that the direction of integration is reversed.
The previous call to the setup routine resulted in the error exit $\u2329\mathit{\text{value}}\u232a$.
The setup routine
d02lxf has not been called.
 ${\mathbf{ifail}}=2$

The maximum number of steps, $\u2329\mathit{\text{value}}\u232a$, has been attempted.
 ${\mathbf{ifail}}=3$

To satisfy the accuracy requirements the step size, $\u2329\mathit{\text{value}}\u232a$, at ${\mathbf{t}}=\u2329\mathit{\text{value}}\u232a$, is too small for the machine precision.
 ${\mathbf{ifail}}=4$

Two successive errors detected at the current value of ${\mathbf{t}}=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{ifail}}=5$

Inefficiency detected in integrating exactly to values of
tend.
 ${\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.
7
Accuracy
The accuracy of integration is determined by the arguments
tol,
thres and
thresp in a prior call to
d02lxf. 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 system. The code is designed so that a reduction in
tol should lead to an approximately proportional reduction in the error. You are strongly recommended to call
d02laf with more than one value for
tol 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. For a description of the error test see the specifications of the arguments
tol,
thres and
thresp in routine document
d02lxf.
8
Parallelism and Performance
d02laf 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.
d02laf is not threaded in any implementation.
If
d02laf fails with
${\mathbf{ifail}}={\mathbf{3}}$ then the value of
tol may be so small that a solution cannot be obtained, in which case the routine should be called again with a larger value for
tol. 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. d02laf could be used in onestep 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)if the solution contains fast oscillatory 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}}$. The Runge–Kutta–Nystrom methods are not efficient in such cases and you should consider reposing your problem as a system of firstorder ordinary differential equations and then using a routine from Subchapter D02MN with the Blend formulae (see d02mvf).
d02laf can be used for producing results at short intervals (for example, for tabulation), in two ways. By far the less efficient is to call
d02laf successively over short intervals,
$t+\left(i1\right)\times h$ to
$t+i\times h$, although this is the only way if the higher order method has been selected and precisely
not what it is intended for. A more efficient way,
only for use when the lower order method has been selected, is to use
d02laf in onestep mode. The output values of arguments
y,
yp,
ydp,
t and
rwork are set correctly for a call to
d02lzf to compute the solution and derivative at the required points.
10
Example
This example solves the following system (the two body problem)
over the range
$\left[0,20\right]$ with initial conditions
${y}_{1}=1.0\epsilon $,
${y}_{2}=0.0$,
${y}_{1}^{\prime}=0.0$ and
${y}_{2}^{\prime}=\sqrt{\left(\frac{1+\epsilon}{1\epsilon}\right)}$ where
$\epsilon $, the eccentricity, is
$0.5$. The system is solved using the lower order method with relative local error tolerances
$\text{1.0E\u22124}$ and
$\text{1.0E\u22125}$ and default threshold tolerances.
d02laf is used in onestep mode (
${\mathbf{onestp}}=\mathrm{.TRUE.}$) and
d02lzf provides solution values at intervals of
$2.0$.
10.1
Program Text
10.2
Program Data
10.3
Program Results