NAG FL Interface
d02lxf (ivp_​2nd_​rkn_​setup)

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

Fortran Interface
Subroutine d02lxf ( neq, h, tol, thres, thresp, maxstp, start, onestp, high, rwork, lrwork, ifail)
Integer, Intent (In) :: neq, maxstp, lrwork
Integer, Intent (Inout) :: ifail
Real (Kind=nag_wp), Intent (In) :: h, tol, thres(neq), thresp(neq)
Real (Kind=nag_wp), Intent (Inout) :: rwork(lrwork)
Logical, Intent (In) :: onestp, high
Logical, Intent (Inout) :: start
C Header Interface
#include <nag.h>
void  d02lxf_ (const Integer *neq, const double *h, const double *tol, const double thres[], const double thresp[], const Integer *maxstp, logical *start, const logical *onestp, const logical *high, double rwork[], const Integer *lrwork, Integer *ifail)
The routine may be called by the names d02lxf or nagf_ode_ivp_2nd_rkn_setup.

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 Arguments

1: neq Integer Input
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) array Input
5: threspneq Real (Kind=nag_wp) array Input
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, 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 Integer Input
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 Logical Input/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 Logical Input
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 Logical Input
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) array Communication Array
This must be the same argument 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 Integer Input
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 Integer Input/Output
On entry: ifail must be set to 0, -1 or 1 to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of 0 causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of -1 means that an error message is printed while a value of 1 means that it is not.
If halting is not appropriate, the value -1 or 1 is recommended. If message printing is undesirable, then the value 1 is recommended. Otherwise, the value 0 is recommended. 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
On entry, thresvalue=value is not positive.
On entry, threspvalue=value is not positive.
ifail=2
On entry, high=.FALSE. and lrwork=value.
Constraint: if high=.FALSE. then lrworkvalue.
On entry, high=.TRUE. and lrwork=value.
Constraint: if high=.TRUE. then lrworkvalue.
On entry, neq=value.
Constraint: neq1.
ifail=3
On entry, tol=value.
Constraint: value<tol<value.
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.
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.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

d02lxf 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.
d02lxf is not threaded in any implementation.

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.