naginterfaces.library.ode.ivp_stiff_exp_revcom¶
- naginterfaces.library.ode.ivp_stiff_exp_revcom(t, tout, y, ydot, comm, rtol, atol, itol, wkjac, imon, inln, ires, irevcm, itask, itrace, io_manager=None)[source]¶
ivp_stiff_exp_revcom
is a reverse communication function for integrating stiff systems of explicit ordinary differential equations.For full information please refer to the NAG Library document for d02nm
https://www.nag.com/numeric/nl/nagdoc_29/flhtml/d02/d02nmf.html
- Parameters
- tfloat
On initial entry: , the value of the independent variable. The input value of is used only on the first call as the initial point of the integration.
- toutfloat
On initial entry: the next value of at which a computed solution is desired. For the initial , the input value of is used to determine the direction of integration. Integration is permitted in either direction (see also ).
- yfloat, ndarray, shape , modified in place
On initial entry: the values of the dependent variables (solution). On the first call the first elements of must contain the vector of initial values.
On final exit: the computed solution vector evaluated at (usually ).
- ydotfloat, ndarray, shape , modified in place
On intermediate entry: must be set to the derivatives as defined under the description of .
On final exit: the time derivatives of the vector at the last integration point.
- commdict, communication object, modified in place
Communication structure.
This argument must have been initialized by prior calls to one of
ivp_stiff_fulljac_setup()
,ivp_stiff_bandjac_setup()
orivp_stiff_sparjac_setup()
and one ofivp_stiff_dassl()
,ivp_stiff_bdf()
orivp_stiff_blend()
.- rtolfloat, array-like, shape
Note: the required length for this argument is determined as follows: if : ; otherwise: .
On initial entry: the relative local error tolerance.
- atolfloat, array-like, shape
Note: the required length for this argument is determined as follows: if : ; otherwise: .
On initial entry: the absolute local error tolerance.
- itolint
On initial entry: a value to indicate the form of the local error test. indicates to
ivp_stiff_exp_revcom
whether to interpret either or both of or as a vector or a scalar. The error test to be satisfied is , where is defined as follows:1
scalar
scalar
2
scalar
vector
3
vector
scalar
4
vector
vector
is an estimate of the local error in , computed internally, and the choice of norm to be used is defined by a previous call to an integrator setup function.
- wkjacfloat, ndarray, shape , modified in place
On intermediate entry: elements of the Jacobian as defined under the description of . If a numerical Jacobian was requested then is used for workspace.
On intermediate exit: the Jacobian is overwritten.
- imonint
On intermediate entry: may be reset to determine subsequent action in
ivp_stiff_exp_revcom
.Integration is to be halted. A return will be made from
ivp_stiff_exp_revcom
to the calling (sub)program with = 12.Allow
ivp_stiff_exp_revcom
to continue with its own internal strategy. The integrator will try up to three restarts unless .Return to the internal nonlinear equation solver, where the action taken is determined by the value of .
Normal exit to
ivp_stiff_exp_revcom
to continue integration.Restart the integration at the current time point. The integrator will restart from order when this option is used. The solution , provided by the operation (see Notes), will be used for the initial conditions.
Try to continue with the same step size and order as was to be used before entering the operation (see Notes). and may be altered if desired.
Continue the integration but using a new value of and possibly new values of and .
- inlnint
On intermediate entry: with and , specifies the action to be taken by the internal nonlinear equation solver. By setting and returning to
ivp_stiff_exp_revcom
, the residual vector is evaluated and placed in , for and then the operation (see Notes) is invoked again. At present this is the only option available: must not be set to any other value.- iresint
On intermediate entry: should be unchanged unless one of the following actions is required of
ivp_stiff_exp_revcom
in which case should be set accordingly.Indicates to
ivp_stiff_exp_revcom
that control should be passed back immediately to the calling (sub)program with the error indicator set to = 11.Indicates to
ivp_stiff_exp_revcom
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 possibleivp_stiff_exp_revcom
returns to the calling (sub)program with the error indicator set to = 7.Indicates to
ivp_stiff_exp_revcom
to stop its current operation and to enter the operation (see Notes) immediately.- irevcmint
On initial entry: must contain .
On intermediate entry: should remain unchanged.
- itaskint
On initial 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 . must be specified as an option in one of the integrator setup functions before the first call to the integrator, or specified in the optional input function before a continuation call. (e.g., see
ivp_stiff_bdf()
) may be equal to or beyond , but not before it in the direction of integration.Take one step only and return, without passing (e.g., see
ivp_stiff_bdf()
). must be specified under .- itraceint
On initial entry: the level of output that is printed by the integrator. may take the value , , , or .
is assumed and similarly if , is assumed.
No output is generated.
Only warning messages are printed on the current error message unit (see
FileObjManager
).Warning messages are printed as above, and on the file object associated with the advisory I/O unit (see
FileObjManager
) 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 .- io_managerFileObjManager, optional
Manager for I/O in this routine.
- Returns
- tfloat
On final exit: the value at which the computed solution is returned (usually at ).
- imonint
On intermediate exit: used to pass information between
ivp_stiff_exp_revcom
and the MONITR operation (see Notes). With , contains a flag indicating under what circumstances the return fromivp_stiff_exp_revcom
occurred:Exit from
ivp_stiff_exp_revcom
after caused an early termination (this facility could be used to locate discontinuities).The current step failed repeatedly.
Exit from
ivp_stiff_exp_revcom
after a call to the internal nonlinear equation solver.The current step was successful.
- inlnint
On intermediate exit: contains a flag indicating the action to be taken, if any, by the internal nonlinear equation solver.
- iresint
On intermediate exit: with , , , or , contains the value .
- irevcmint
On intermediate exit: indicates what action you must take before re-entering. The possible exit values of are , , , , , or , which should be interpreted as follows:
, , or
Indicates that an FCN operation (see Notes) is required: must be supplied, where is located in , for .
For or , should be placed in location , for .
For , should be placed in location , for .
For , should be placed in location , for .
Indicates that a JAC operation (see Notes) is required: the Jacobian matrix must be supplied.
If full matrix linear algebra is being used, the th element of the Jacobian must be stored in .
If banded matrix linear algebra is being used then the th element of the Jacobian must be stored in , where and ; here and are the number of subdiagonals and superdiagonals, respectively, in the band.
If sparse matrix linear algebra is being used then
ivp_stiff_sparjac_enq()
must be called to determine which column of the Jacobian is required and where it should be stored.Indicates that a MONITR operation (see Notes) can be performed.
Indicates that the current step was not successful, due to error test failure or convergence test failure. The only information supplied to you on this return is the current value of the independent variable , located in . No values must be changed before re-entering
ivp_stiff_exp_revcom
; this facility enables you to determine the number of unsuccessful steps.On final exit: indicated the user-specified task has been completed or an error has been encountered (see the descriptions for and ).
- Raises
- NagValueError
- (errno )
On re-entry, .
Constraint: .
- (errno )
Failure during internal time interpolation. and the current time are too close.
and and the current time is .
- (errno )
On entry, or and is before the current time in the direction of integration.
, and the current time is .
- (errno )
and is more than an integration step behind the current time.
, current time minus step size: .
- (errno )
The initial stepsize, , is too small.
- (errno )
Weight number used in the local error test is too small. Check the values of and .
and may both be zero.
Weight .
- (errno )
On entry, or and is before in the direction of integration.
, and .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, .
Constraint: .
- (errno )
Either the value of is not the same as the value supplied to the setup function or a communication array has become corrupted.
, (setup) .
- (errno )
Either the value of is not the same as the value supplied to the setup function or a communication array has become corrupted.
, (setup) .
- (errno )
On entry, an illegal (negative) minimum stepsize was provided in a prior call to a setup function. .
- (errno )
On entry, is less than with respect to the direction of integration given by the sign of in a prior call to a setup function.
, and .
- (errno )
On entry, an illegal (negative) maximum number of steps was provided in a prior call to a setup function. .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, and .
Constraint: .
- (errno )
On entry, .
Constraint: .
- (errno )
Either the function was entered on a continuation call without a prior call of this function, or a communication array has become corrupted.
- (errno )
On entry, is too close to to start integration.
and .
- (errno )
On entry, .
Constraint: .
- (errno )
Either the integrator setup function has not been called prior to the first call of this function, or a communication array has become corrupted.
- (errno )
On entry, an illegal (negative) maximum stepsize was provided in a prior call to a setup function. .
- (errno )
Either the linear algebra setup function has not been called prior to the first call of this function, or a communication array has become corrupted.
- (errno )
On re-entry, for the case and .
.
- (errno )
On entry, is invalid: .
- (errno )
On re-entry, the solution vector appears to have been overwritten.
Further integration will not be attempted.
- (errno )
At time the maximum number of allowed steps on this call was taken before reaching the next output point .
Maximum number of steps .
- (errno )
The derivative evaluation procedure set the error flag repeatedly despite attempts by the integrator to avoid this.
- (errno )
A singular Jacobian has been encountered. You should check the problem formulation and Jacobian calculation.
- (errno )
Workspace error occurred when trying to form the Jacobian matrix in calculating the initial values of the solution and its time derivative.
- (errno )
Not enough integer store provided for sparse matrix solver.
Units of store needed: . Amount provided: .
- (errno )
Larger integer workspace required.
Provided: ; required: .
- (errno )
Not enough real store provided for sparse matrix solver.
Units of store needed: . Amount provided: .
- (errno )
On entry, too much accuracy requested for precision of the machine at the start of problem. The tolerances should be checked; the requested accuracy should be reduced by a factor of at least .
- Warns
- NagAlgorithmicWarning
- (errno )
Too much accuracy requested for precision of the machine at time .
The tolerances should be checked; the requested accuracy should be reduced by a factor of at least .
- (errno )
There were repeated error-test failures on an attempted step, before completing the requested task, but the integration was successful as far as . The problem may have a singularity, or the local error requirements may be inappropriate.
- (errno )
There were repeated convergence-test failures on an attempted step, before completing the requested task, but the integration was successful as far as . This may be caused by an inaccurate Jacobian matrix or one which is incorrectly computed.
- (errno )
At time , error weight became zero. Check the values of , and supplied.
- (errno )
On re-entry, , which signals that the integration should terminate. at time .
- (errno )
A return was forced by setting , but the integration was successful as far as .
- (errno )
The requested task has been completed, but it is estimated that a small change in and is unlikely to produce any change in the computed solution. (This ONLY applies when you are NOT operating in one step mode; that is, when or .)
- Notes
No equivalent traditional C interface for this routine exists in the NAG Library.
ivp_stiff_exp_revcom
is a general purpose function for integrating the initial value problem for a stiff system of explicit ordinary differential equations,An outline of a typical calling program is
call the linear algebra setup routine
call the integrator setup routine
set
start looping
call
ivp_stiff_exp_revcom
if then
supply the Jacobian matrix
else if then
perform monitoring tasks requested by the user
else if or then
evaluate the derivative
else if then
indicates an unsuccessful step
else
stop looping
post processing; optional linear algebra diagnostic call (sparse case only), optional integrator diagnostic call
There are three major operations that may be required of the calling function on an intermediate return () from
ivp_stiff_exp_revcom
; these are denoted (i), (ii) and (iii).The following sections describe in greater detail exactly what is required of each of these operations.
Supply the Jacobian matrix
You need only provide this facility if the argument (or if using sparse matrix linear algebra) in a call to the linear algebra setup function (see in
ivp_stiff_fulljac_setup()
). If the Jacobian matrix is to be evaluated numerically by the integrator, then the remainder of section (i) can be ignored.We must define the system of nonlinear equations which is solved internally by the integrator. The time derivative, , 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 is solved in the form
where the function is defined by
It is the Jacobian matrix that you must supply as follows:
where , and are located in , and respectively and the array contains the current values of the dependent variables. Only the nonzero elements of the Jacobian need be set, since the locations where it is to be stored are preset to zero.
In this document this operation is referred to as JAC.
Perform tasks requested by you
This operation is essentially a monitoring function and additionally provides the opportunity of changing the current values of , HNEXT (the step size that the integrator proposes to take on the next step), HMIN (the minimum step size to be taken on the next step), and HMAX (the maximum step size to be taken on the next step). The scaled local error at the end of a timestep may be obtained by calling
ivp_stiff_errest()
.The following gives details of the location within the array [‘rwork’] of variables that may be of interest to you:
Variable
Specification
Location
the current value of the independent variable
last step size successfully used by the integrator
step size that the integrator proposes to take on the next step
minimum step size to be taken on the next step
maximum step size to be taken on the next step
the order of the integrator used on the last step
You are advised to consult the description of in
ivp_stiff_exp_fulljac()
for details on what optional input can be made.If is changed, then must be set to before return to
ivp_stiff_exp_revcom
. If either of the values of HMIN or HMAX are changed, then must be set before return toivp_stiff_exp_revcom
. If HNEXT is changed, then must be set to before return toivp_stiff_exp_revcom
.In addition you can force
ivp_stiff_exp_revcom
to evaluate the residual vectorby setting and and then returning to
ivp_stiff_exp_revcom
; on return to this monitoring operation the residual vector will be stored in , for .In this document this operation is referred to as MONITR.
Evaluate the derivative
This operation must evaluate the derivative vector for the explicit ordinary differential equation system defined by
where is located in .
In this document this operation is referred to as FCN.