D02LXF (PDF version)
D02 Chapter Contents
D02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

D02LXF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

 Contents

    1  Purpose
    7  Accuracy
    10  Example

1  Purpose

D02LXF is a setup routine which must be called prior to the first call of the integrator D02LAF and may be called prior to any continuation call to D02LAF.

2  Specification

SUBROUTINE D02LXF ( NEQ, H, TOL, THRES, THRESP, MAXSTP, START, ONESTP, HIGH, RWORK, LRWORK, IFAIL)
INTEGER  NEQ, MAXSTP, LRWORK, IFAIL
REAL (KIND=nag_wp)  H, TOL, THRES(NEQ), THRESP(NEQ), RWORK(LRWORK)
LOGICAL  START, ONESTP, HIGH

3  Description

D02LXF permits you to set optional inputs prior to any call of D02LAF. It must be called before the first call of routine D02LAF and it may be called before any continuation call of routine D02LAF.

4  References

None.

5  Parameters

1:     NEQ – INTEGERInput
On entry: the number of second-order ordinary differential equations to be solved by D02LAF.
Constraint: NEQ1.
2:     H – REAL (KIND=nag_wp)Input
On entry: if START=.TRUE., H may specify an initial step size to be attempted in D02LAF.
If START=.FALSE., H may specify a step size to override the choice of next step attempted made internally to D02LAF.
The sign of H is not important, as the absolute value of H is chosen and the appropriate sign is selected by D02LAF.
If this option is not required then you must set H=0.0.
3:     TOL – REAL (KIND=nag_wp)Input
On entry: must be set to a relative tolerance for controlling the error in the integration by D02LAF. D02LAF has been designed so that, for most problems, a reduction in TOL leads to an approximately proportional reduction in the error in the solution. However the actual relation between TOL and the accuracy of the solution cannot be guaranteed. You are strongly recommended to repeat the integration with a smaller value of TOL and compare the results. See the description of THRES and THRESP for further details of how TOL is used.
Constraint: 10×εTOL1.0 (ε is the machine precision, see X02AJF).
4:     THRESNEQ – REAL (KIND=nag_wp) arrayInput
5:     THRESPNEQ – REAL (KIND=nag_wp) arrayInput
On entry: THRES and THRESP may be set to thresholds for use in the error control of D02LAF. At each step in the numerical integration estimates of the local errors E1i and E2i in the solution, yi, and its derivative, yi, respectively are computed, for i=1,2,,NEQ. For the step to be accepted conditions of the following type must be satisfied:
max1iNEQ E1i maxTHRESi,yi TOL, max1iNEQ E2i maxTHRESPi,yi TOL.  
If one or both of these is not satisfied then the step size is reduced and the solution is recomputed.
If THRES10.0 on entry, then a value of 50.0×ε is used for THRESi, for i=1,2,,NEQ, where ε is machine precision. Similarly for THRESP.
Constraints:
  • THRES10.0 or THRESi>0.0, for i=1,2,,NEQ;
  • THRESP10.0 or THRESPi>0.0, for i=1,2,,NEQ.
6:     MAXSTP – INTEGERInput
On entry: a bound on the number of steps attempted in any one call of D02LAF.
If MAXSTP0 on entry, a value of 1000 is used.
7:     START – LOGICALInput/Output
On entry: specifies whether or not the call of D02LAF is for a new problem. START=.TRUE. indicates that a new problem is to be solved. START=.FALSE. indicates the call of D02LXF is prior to a continuation call of D02LAF.
On exit: START=.FALSE..
8:     ONESTP – LOGICALInput
On entry: the mode of operation for D02LAF.
ONESTP=.TRUE.
D02LAF will operate in one-step mode, that is it will return after each successful step.
ONESTP=.FALSE.
D02LAF will operate in interval mode, that is it will return at the end of the integration interval.
9:     HIGH – LOGICALInput
On entry: if HIGH=.TRUE., a high-order method will be used, whereas if HIGH=.FALSE., a low-order method will be used. (See the specification of D02LAF for further details.)
10:   RWORKLRWORK – REAL (KIND=nag_wp) arrayCommunication Array
This must be the same parameter RWORK supplied to D02LAF. It is used to pass information to D02LAF and therefore the contents of this array must not be changed before calling D02LAF.
11:   LRWORK – INTEGERInput
On entry: the dimension of the array RWORK as declared in the (sub)program from which D02LXF is called.
Constraints:
  • if HIGH=.TRUE., LRWORK16+20×NEQ;
  • if HIGH=.FALSE., LRWORK16+11×NEQ.
12:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and Warnings

If on entry 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:
IFAIL=1
THRES1>0.0 and for some i THRESi0.0, 1iNEQ, and/or, THRESP1>0.0 and for some i THRESPi0.0, 1iNEQ.
IFAIL=2
LRWORK is too small.
IFAIL=3
TOL does not satisfy 10×εTOL1.0 (ε is the machine precision, see X02AJF)
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.8 in the Essential Introduction for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.7 in the Essential Introduction for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.6 in the Essential Introduction for further information.

7  Accuracy

Not applicable.

8  Parallelism and Performance

Not applicable.

9  Further Comments

Prior to a continuation call of D02LAF, you may reset any of the optional parameters by calling D02LXF with START=.FALSE.. You may reset:
H to override the internal step size selection;
TOL, THRES, THRESP to change the error requirements;
MAXSTP to increase or decrease the number of steps attempted before an error exit is returned;
ONESTP to change the mode of operation of D02LAF;
HIGH to change the order of the method being used.

10  Example

See Section 10 in D02LAF.

D02LXF (PDF version)
D02 Chapter Contents
D02 Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2015