NAG FL Interface
d02qwf (ivp_​adams_​setup)

Settings help

FL Name Style:


FL Specification Language:


1 Purpose

d02qwf is a setup routine which must be called prior to the first call of either of the integrators d02qff and d02qgf and may be called prior to any continuation call to these routines.

2 Specification

Fortran Interface
Integer, Intent (In) :: neqf, latol, lrtol, maxstp, neqg, lrwork, liwork
Integer, Intent (Inout) :: iwork(liwork), ifail
Real (Kind=nag_wp), Intent (In) :: atol(latol), rtol(lrtol), tcrit, hmax
Real (Kind=nag_wp), Intent (Inout) :: rwork(lrwork)
Logical, Intent (In) :: vectol, onestp, crit, sophst
Logical, Intent (Inout) :: alterg
Character (1), Intent (InOut) :: statef
C Header Interface
#include <nag.h>
void  d02qwf_ (char *statef, const Integer *neqf, const logical *vectol, const double atol[], const Integer *latol, const double rtol[], const Integer *lrtol, const logical *onestp, const logical *crit, const double *tcrit, const double *hmax, const Integer *maxstp, const Integer *neqg, logical *alterg, const logical *sophst, double rwork[], const Integer *lrwork, Integer iwork[], const Integer *liwork, Integer *ifail, const Charlen length_statef)
The routine may be called by the names d02qwf or nagf_ode_ivp_adams_setup.

3 Description

d02qwf permits initialization of the integration method and setting of optional inputs prior to any call of d02qff or d02qgf. It must be called before the first call of either of the routines d02qff or d02qgf and it may be called before any continuation call of either of the routines d02qff or d02qgf.

4 References

None.

5 Arguments

1: statef Character(1) Input/Output
On entry: specifies whether the integration routine (d02qff or d02qgf) is to start a new system of ordinary differential equations, restart a system or continue with a system.
statef='S'
Start integration with a new differential system.
statef='R'
Restart integration with the current differential system.
statef='C'
Continue integration with the current differential system.
Constraint: statef='S', 'R' or 'C'.
On exit: is set to 'C', except that if an error is detected, statef is unchanged.
2: neqf Integer Input
On entry: the number of ordinary differential equations to be solved by the integration routine. neqf must remain unchanged on subsequent calls to d02qwf with statef='C' or 'R'.
Constraint: neqf1.
3: vectol Logical Input
On entry: specifies whether vector or scalar error control is to be employed for the local error test in the integration.
If vectol=.TRUE., vector error control will be used and you must specify values of rtol(i) and atol(i), for i=1,2,,neqf.
Otherwise scalar error control will be used and you must specify values of just rtol(1) and atol(1).
The error test to be satisfied is of the form
i=1neqf (eiwi) 21.0.  
where wi is defined as follows:
vectol wi
.TRUE. rtol(i)×|yi|+atol(i)
.FALSE. rtol(1)×|yi|+atol(1)
and ei is an estimate of the local error in yi, computed internally. vectol must remain unchanged on subsequent calls to d02qwf with statef='C' or 'R'.
4: atol(latol) Real (Kind=nag_wp) array Input
On entry: the absolute local error tolerance (see vectol).
Constraint: atol(i)0.0.
5: latol Integer Input
On entry: the dimension of the array atol as declared in the (sub)program from which d02qwf is called.
Constraints:
  • if vectol=.TRUE., latolneqf;
  • if vectol=.FALSE., latol1.
6: rtol(lrtol) Real (Kind=nag_wp) array Input
On entry: the relative local error tolerance (see vectol).
Constraints:
  • rtol(i)0.0;
  • if atol(i)=0.0, rtol(i)4.0×machine precision.
7: lrtol Integer Input
On entry: the dimension of the array rtol as declared in the (sub)program from which d02qwf is called.
Constraints:
  • if vectol=.TRUE., lrtolneqf;
  • if vectol=.FALSE., lrtol1.
8: onestp Logical Input
On entry: the mode of operation of the integration routine. If onestp=.TRUE., the integration routine will operate in one-step mode, that is it will return after each successful step. Otherwise the integration routine will operate in interval mode, that is it will return at the end of the integration interval.
9: crit Logical Input
On entry: specifies whether or not there is a value for the independent variable beyond which integration is not to be attempted. Setting crit=.TRUE. indicates that there is such a point, whereas crit=.FALSE. indicates that there is no such restriction.
10: tcrit Real (Kind=nag_wp) Input
On entry: with crit=.TRUE., tcrit must be set to a value of the independent variable beyond which integration is not to be attempted. Otherwise tcrit is not referenced.
11: hmax Real (Kind=nag_wp) Input
On entry: if hmax0.0, a bound on the absolute step size during the integration is taken to be |hmax|.
If hmax=0.0, no bound is assumed on the step size during the integration.
A bound may be required if there are features of the solution on very short ranges of integration which may be missed. You should try hmax=0.0 first.
Note:  this argument only affects the step size if the option crit=.TRUE. is being used.
12: maxstp Integer Input
On entry: a bound on the number of attempted steps in any one call to the integration routine. If maxstp0 on entry, a value of 1000 is used.
13: neqg Integer Input
On entry: specifies whether or not root-finding is required in d02qff or d02qgf.
neqg0
No root-finding is attempted.
neqg>0
Root-finding is required and neqg event functions will be specified for the integration routine.
14: alterg Logical Input/Output
On entry: specifies whether or not the event functions have been redefined. alterg need not be set if statef='S'. On subsequent calls to d02qwf, if neqg has been set positive, alterg=.FALSE. specifies that the event functions remain unchanged, whereas alterg=.TRUE. specifies that the event functions have changed. Because of the expense in reinitializing the root searching procedure, alterg should be set to .TRUE. only if the event functions really have been altered. alterg need not be set if the root-finding option is not used.
On exit: is set to .FALSE..
15: sophst Logical Input
On entry: the type of search technique to be used in the root-finding. If sophst=.TRUE. then a sophisticated and reliable but expensive technique will be used, whereas for sophst=.FALSE. a simple but less reliable technique will be used. If neqg0, sophst is not referenced.
16: rwork(lrwork) Real (Kind=nag_wp) array Communication Array
This must be the same argument rwork supplied to the integration routine. It is used to pass information to the integration routine and, therefore, the contents of this array must not be changed before calling the integration routine.
17: lrwork Integer Input
On entry: the dimension of the array rwork as declared in the (sub)program from which d02qwf is called.
Constraint: lrwork21×(1+neqf)+2×J+K×neqg+2, where
J={ neqf if ​vectol=.TRUE. 1 if ​vectol=.FALSE.  
and
K={ 14 if ​ sophst=.TRUE. 5 if ​ sophst=.FALSE..  
18: iwork(liwork) Integer array Communication Array
This must be the same argument iwork supplied to the integration routine. It is used to pass information to the integration routine and, therefore, the contents of this array must not be changed before calling the integration routine.
19: liwork Integer Input
On entry: the dimension of the array iwork as declared in the (sub)program from which d02qwf is called.
Constraints:
  • if sophst=.TRUE., liwork21+4×neqg;
  • if sophst=.FALSE., liwork21+neqg.
20: 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, atol(value)=value.
Constraint: atol(i)0.0 for all i.
On entry, for i=value, atol(i)=0.0, rtol(i)=value and 4×eps=value.
Constraint: if atol(i)=0.0 then rtol(i)4×eps for all i.
On entry, latol=value.
Constraint: latol1.
On entry, liwork=value.
Constraint: liworkvalue.
On entry, lrtol=value.
Constraint: lrtol1.
On entry, lrwork=value.
Constraint: lrworkvalue.
On entry, neqf=value.
Constraint: neqf1.
On entry, rtol(value)=value.
Constraint: rtol(i)0.0 for all i.
On entry, statef=value.
Constraint: statef='S', 'R' or 'C'.
On entry, statef='R' or 'C', alterg=.FALSE. and neqg=value.
Constraint: if statef='R' or 'C' and alterg=.FALSE. then neqg must retain its value from the prior call with statef='S'.
On entry, statef='R' or 'C' and neqf=value.
Constraint: if statef='R' or 'C' then neqf must retain its value, value, from the prior call with statef='S'.
On entry, statef='R' or 'C' and vectol=.FALSE..
Constraint: if statef='R' or 'C' then vectol must retain its value from the prior call with statef='S'.
On entry, statef='R' or 'C' and vectol=.TRUE..
Constraint: if statef='R' or 'C' then vectol must retain its value from the prior call with statef='S'.
On entry, vectol=.TRUE., latol=value and neqf=value.
Constraint: if vectol=.TRUE. then latolneqf.
On entry, vectol=.TRUE., lrtol=value and neqf=value.
Constraint: if vectol=.TRUE. then lrtolneqf.
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

Background information to multithreading can be found in the Multithreading documentation.
d02qwf 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.
d02qwf is not threaded in any implementation.

9 Further Comments

Prior to a continuation call of the integration routine, you may reset any of the optional parameters by calling d02qwf with statef='C'. You may reset:
hmax to alter the maximum step size selection;
rtol, atol to change the error requirements;
maxstp to increase or decrease the number of attempted steps before an error exit is returned;
onestp to change the operation mode of the integration routine;
crit, tcrit to alter the point beyond which integration must not be attempted; and
neqg, alterg, sophst to alter the number and type of event functions, and also the search method.
If the behaviour of the system of differential equations has altered and you wish to restart the integration method from the value of t output from the integration routine (see d02qff and d02qgf), then statef should be set to statef='R' and any of the optional parameters may be reset also. If you want to redefine the system of differential equations or start a new integration problem, then statef should be set to statef='S'. Resetting statef='R' or 'S' on normal continuation calls causes a restart in the integration process, which is very inefficient when not needed.

10 Example

See Section 10 in d02qff and d02qgf.