D02NBF is a general purpose routine for integrating the initial value problem for a stiff system of explicit ordinary differential equations,
It is designed specifically for the case where the Jacobian is a full matrix.
Both interval and step oriented modes of operation are available and also modes designed to permit intermediate output within an interval oriented mode.
An outline of a typical calling program for D02NBF is given below. It calls the full matrix linear algebra setup routine D02NSF, the Backward Differentiation Formula (BDF) integrator setup routine D02NVF, and its diagnostic counterpart D02NYF.
The linear algebra setup routine D02NSF and one of the integrator setup routines, D02NVF or D02NWF, must be called prior to the call of D02NBF. The integrator diagnostic routine D02NYF may be called after the call to D02NBF. There is also a routine, D02NZF, designed to permit you to change step size on a continuation call to D02NBF without restarting the integration process.
On entry: the number of differential equations to be solved.
2: – INTEGERInput
On entry: a bound on the maximum number of differential equations to be solved during the integration.
3: – REAL (KIND=nag_wp)Input/Output
On entry: , the value of the independent variable. The input value of T is used only on the first call as the initial point of the integration.
On exit: the value at which the computed solution is returned (usually at TOUT).
4: – REAL (KIND=nag_wp)Input
On entry: the next value of at which a computed solution is desired. For the initial , the input value of TOUT is used to determine the direction of integration. Integration is permitted in either direction (see also ITASK).
5: – REAL (KIND=nag_wp) arrayInput/Output
On entry: the values of the dependent variables (solution). On the first call the first NEQ elements of Y must contain the vector of initial values.
On exit: the computed solution vector, evaluated at T (usually ).
6: – REAL (KIND=nag_wp) arrayOutput
On exit: the time derivatives of the vector at the last integration point.
7: – REAL (KIND=nag_wp) arrayCommunication Array
8: – REAL (KIND=nag_wp) arrayInput
Note: the dimension of the array RTOL
must be at least
if or , and at least otherwise.
On entry: a value to indicate the form of the local error test. ITOL indicates to D02NBF whether to interpret either or both of RTOL or ATOL as a vector or a scalar. The error test to be satisfied is , where is defined as follows:
On entry: the number of differential equations being solved.
2: – REAL (KIND=nag_wp)Input
On entry: , the current value of the independent variable.
3: – REAL (KIND=nag_wp) arrayInput
On entry: the value of
, for .
4: – REAL (KIND=nag_wp) arrayOutput
On exit: the value
, given by , for .
5: – INTEGERInput/Output
On entry: .
On exit: you may set IRES as follows to indicate certain conditions in FCN to the integrator:
Indicates a normal return from FCN, that is IRES has not been altered by you and integration continues.
Indicates to the integrator that control should be passed back immediately to the calling (sub)program with the error indicator set to .
Indicates to the integrator that an error condition has occurred in the solution vector, its time derivative or in the value of . The integrator will use a smaller time step to try to avoid this condition. If this is not possible the integrator returns to the calling (sub)program with the error indicator set to .
Indicates to the integrator to stop its current operation and to enter MONITR immediately with argument .
FCN must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which D02NBF is called. Arguments denoted as Input must not be changed by this procedure.
13: – REAL (KIND=nag_wp) arrayCommunication Array
14: – INTEGERInput
On entry: the second dimension of the array YSAV as declared in the (sub)program from which D02NBF is called. An appropriate value for SDYSAV is described in the specification of the integrator setup routines D02NVF and D02NWF. This value must be the same as that supplied to the integrator setup routine.
15: – SUBROUTINE, supplied by the NAG Library or the user.External Procedure
JAC must evaluate the Jacobian of the system. If this option is not required, the actual argument for JAC must be the dummy routine D02NBZ. (D02NBZ is included in the NAG Library.) You must indicate to the integrator whether this option is to be used by setting the argument JCEVAL appropriately in a call to the full linear algebra setup routine D02NSF.
First we must define the system of nonlinear equations which is solved internally by the integrator. The time derivative, , generated internally, has the form
where is the current step size and is an argument that depends on the integration method in use. The vector is the current solution and the vector depends on information from previous time steps. This means that . The system of nonlinear equations that is solved has the form
but it is solved in the form
where is the function defined by
It is the Jacobian matrix that you must supply in JAC as follows:
where is the numerical value of SDYSAV in the call of D02NBF.
1: – INTEGERInput
On entry: the number of differential equations being solved.
2: – INTEGERInput
On entry: an upper bound on the number of differential equations to be solved.
3: – REAL (KIND=nag_wp)Input
On entry: the current value of the independent variable.
4: – REAL (KIND=nag_wp)Input
On entry: the last step size successfully used by the integrator.
5: – REAL (KIND=nag_wp)Input/Output
On entry: the step size that the integrator proposes to take on the next step.
On exit: the next step size to be used. If this is different from the input value, then IMON must be set to .
6: – REAL (KIND=nag_wp) arrayInput/Output
On entry: , the values of the dependent variables evaluated at .
On exit: these values must not be changed unless IMON is set to .
7: – REAL (KIND=nag_wp) arrayInput
On entry: the time derivatives of the vector .
8: – REAL (KIND=nag_wp) arrayInput
On entry: workspace to enable you to carry out interpolation using either of the routines D02XJF or D02XKF.
9: – REAL (KIND=nag_wp) arrayInput
On entry: if and , the first NEQ elements contain the residual vector, .
10: – REAL (KIND=nag_wp) arrayInput
On entry: with , contains the weight used for the th equation when the norm is evaluated, and contains the estimated local error for the th equation. The scaled local error at the end of a timestep may be obtained by calling the real function D02ZAF as follows:
On entry: a flag indicating under what circumstances MONITR was called:
Entry from the integrator after (set in FCN) caused an early termination (this facility could be used to locate discontinuities).
The current step failed repeatedly.
Entry after a call to the internal nonlinear equation solver (see INLN).
The current step was successful.
On exit: may be reset to determine subsequent action in D02NBF.
Integration is to be halted. A return will be made from the integrator to the calling (sub)program with .
Allow the integrator to continue with its own internal strategy. The integrator will try up to three restarts unless IMON is set on exit.
Return to the internal nonlinear equation solver, where the action taken is determined by the value of INLN (see INLN).
Normal exit to the integrator to continue integration.
Restart the integration at the current time point. The integrator will restart from order when this option is used. The solution Y, provided by MONITR, will be used for the initial conditions.
Try to continue with the same step size and order as was to be used before the call to MONITR. HMIN and HMAX may be altered if desired.
Continue the integration but using a new value of HNEXT and possibly new values of HMIN and HMAX.
12: – INTEGEROutput
On exit: the action to be taken by the internal nonlinear equation solver when MONITR is exited with . By setting and returning to the integrator, the residual vector is evaluated and placed in the array R, and then MONITR is called again. At present this is the only option available: INLN must not be set to any other value.
13: – REAL (KIND=nag_wp)Input/Output
On entry: the minimum step size to be taken on the next step.
On exit: the minimum step size to be used. If this is different from the input value, then IMON must be set to or .
14: – REAL (KIND=nag_wp)Input/Output
On entry: the maximum step size to be taken on the next step.
On exit: the maximum step size to be used. If this is different from the input value, then IMON must be set to or . If HMAX is set to zero, no limit is assumed.
15: – INTEGERInput
On entry: the order of the integrator used on the last step. This is supplied to enable you to carry out interpolation using either of the routines D02XJF or D02XKF.
MONITR must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which D02NBF is called. Arguments denoted as Input must not be changed by this procedure.
19: – INTEGERInput
On entry: the task to be performed by the integrator.
Normal computation of output values of at (by overshooting and interpolating).
Take one step only and return.
Stop at the first internal integration point at or beyond and return.
Normal computation of output values of at but without overshooting (e.g., see D02MVF). TCRIT must be specified as an option in one of the integrator setup routines before the first call to the integrator, or specified in the optional input routine before a continuation call. TCRIT may be equal to or beyond TOUT, but not before it, in the direction of integration.
Take one step only and return, without passing TCRIT (e.g., see D02MVF). TCRIT must be specified as under .
, , , or .
20: – INTEGERInput
On entry: the level of output that is printed by the integrator. ITRACE may take the value , , , or .
is assumed and similarly if , then is assumed.
No output is generated.
Only warning messages are printed on the current error message unit (see X04AAF).
Warning messages are printed as above, and on the current advisory message unit (see X04ABF) output is generated which details Jacobian entries, the nonlinear iteration and the time integration. The advisory messages are given in greater detail the larger the value of ITRACE.
21: – INTEGERInput/Output
On entry: IFAIL must be set to , . If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value is recommended. If the output of error messages is undesirable, then the value is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if on exit, the recommended value is . When the value is used it is essential to test the value of IFAIL on exit.
On exit: unless the routine detects an error or a warning has been flagged (see Section 6).
6 Error Indicators and Warnings
If on entry or , explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
An illegal input was detected on entry, or after an internal call to MONITR. If , then the form of the error will be detailed on the current error message unit (see X04AAF).
The maximum number of steps specified has been taken (see the description of optional inputs in the integrator setup routines and the optional input continuation routine, D02NZF).
With the given values of RTOL and ATOL no further progress can be made across the integration range from the current point T. The components contain the computed values of the solution at the current point T.
There were repeated error test failures on an attempted step, before completing the requested task, but the integration was successful as far as T. The problem may have a singularity, or the local error requirements may be inappropriate.
There were repeated convergence test failures on an attempted step, before completing the requested task, but the integration was successful as far as T. This may be caused by an inaccurate Jacobian matrix or one which is incorrectly computed.
Some error weight became zero during the integration (see the description of ITOL). Pure relative error control () was requested on a variable (the th) which has now vanished. The integration was successful as far as T.
FCN set its error flag () continually despite repeated attempts by the integrator to avoid this.
Not used for this integrator.
A singular Jacobian has been encountered. This error exit is unlikely to be taken when solving explicit ordinary differential equations. You should check the problem formulation and Jacobian calculation.
An error occurred during Jacobian formulation or back-substitution (a more detailed error description may be directed to the current error message unit, see X04AAF).
FCN signalled the integrator to halt the integration and return (). Integration was successful as far as T.
MONITR set and so forced a return but the integration was successful as far as T.
The requested task has been completed, but it is estimated that a small change in RTOL and ATOL is unlikely to produce any change in the computed solution. (Only applies when you are not operating in one step mode, that is when or .)
The values of RTOL and ATOL are so small that D02NBF is unable to start the integration.
The linear algebra setup routine D02NSF was not called prior to calling D02NBF.
An unexpected error has been triggered by this routine. Please
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.
The accuracy of the numerical solution may be controlled by a careful choice of the arguments RTOL and ATOL, and to a much lesser extent by the choice of norm. You are advised to use scalar error control unless the components of the solution are expected to be poorly scaled. For the type of decaying solution typical of many stiff problems, relative error control with a small absolute error threshold will be most appropriate (that is, you are advised to choose with small but positive).
8 Parallelism and Performance
D02NBF is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.
D02NBF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
D02NBF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.
9 Further Comments
The cost of computing a solution depends critically on the size of the differential system and to a lesser extent on the degree of stiffness of the problem. For D02NBF the cost is proportional to , though for problems which are only mildly nonlinear the cost may be dominated by factors proportional to except for very large problems.
In general, you are advised to choose the Backward Differentiation Formula option (setup routine D02NVF) but if efficiency is of great importance and especially if it is suspected that has complex eigenvalues near the imaginary axis for some part of the integration, you should try the BLEND option (setup routine D02NWF).
This example solves the well-known stiff Robertson problem
over the range with initial conditions and using scalar error control () and computation of the solution at with TCRIT (e.g., see D02MVF) set to (). D02NBY is used for MONITR, a BDF integrator (setup routine D02NVF) is used and a modified Newton method is selected. This example illustrates the use of both a numerical and an analytical Jacobian.