naginterfaces.library.ode.ivp_stiff_imp_bandjac¶
- naginterfaces.library.ode.ivp_stiff_imp_bandjac(t, tout, y, ydot, comm, rtol, atol, itol, resid, lderiv, itask, itrace, jac=None, monitr=None, data=None, io_manager=None, spiked_sorder='C')[source]¶
ivp_stiff_imp_bandjac
is a direct communication function for integrating stiff systems of implicit ordinary differential equations coupled with algebraic equations when the Jacobian is a banded matrix.For full information please refer to the NAG Library document for d02nh
https://www.nag.com/numeric/nl/nagdoc_29/flhtml/d02/d02nhf.html
- Parameters
- tfloat
, 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
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, array-like, shape
The values of the dependent variables (solution). On the first call the first elements of must contain the vector of initial values.
- ydotfloat, array-like, shape
If , must contain approximations to the time derivatives of the vector .
If , need not be set on entry.
- commdict, communication object, modified in place
Communication structure.
This argument must have been initialized by prior calls to
ivp_stiff_bandjac_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: .
The relative local error tolerance.
- atolfloat, array-like, shape
Note: the required length for this argument is determined as follows: if : ; otherwise: .
The absolute local error tolerance.
- itolint
A value to indicate the form of the local error test. indicates to
ivp_stiff_imp_bandjac
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.
- residcallable (r, ires) = resid(t, y, ydot, ires, data=None)
must evaluate the residual
in one case and
in another.
- Parameters
- tfloat
, the current value of the independent variable.
- yfloat, ndarray, shape
The value of , for .
- ydotfloat, ndarray, shape
The value of , for , at .
- iresint
The form of the residual that must be returned in array .
The residual defined in equation (2) must be returned.
The residual defined in equation (1) must be returned.
- dataarbitrary, optional, modifiable in place
User-communication data for callback functions.
- Returns
- rfloat, array-like, shape
must contain the th component of , for , where
or
and where the definition of is determined by the input value of .
- iresint
Should be unchanged unless one of the following actions is required of the integrator, in which case should be set accordingly.
Indicates to the integrator that control should be passed back immediately to the calling (sub)program with the error indicator set to = 11.
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 = 7.
Indicates to the integrator to stop its current operation and to enter immediately with argument .
- lderivbool, array-like, shape
must be set to if you have supplied both an initial and an initial . must be set to if only the initial has been supplied.
must be set to if the integrator is to use a modified Newton method to evaluate the initial and .
Note that and , if supplied, are used as initial estimates.
This method involves taking a small step at the start of the integration, and if on entry, and will be set to the result of taking this small step. must be set to if the integrator is to use functional iteration to evaluate the initial and , and if this fails a modified Newton method will then be attempted. is recommended if there are implicit equations or the initial and are zero.
- itaskint
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. may be equal to or beyond , but not before it, in the direction of integration.
Take one step only and return, without passing . must be specified as under .
The integrator will solve for the initial values of and only and then return to the calling (sub)program without doing the integration. This option can be used to check the initial values of and . Functional iteration or a ‘small’ backward Euler method used in conjunction with a damped Newton iteration is used to calculate these values (see ). Note that if a backward Euler step is used then the value of will have been advanced a short distance from the initial point.
Note: if
ivp_stiff_imp_bandjac
is recalled with a different value of (and altered), the initialization procedure is repeated, possibly leading to different initial conditions.- itraceint
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 .- jacNone or callable p = jac(t, y, ydot, h, d, ml, mu, p, data=None), optional
Note: if this argument is None then a NAG-supplied facility will be used.
must evaluate the Jacobian of the system.
If this option is not required, the actual argument for must be None. You must indicate to the integrator whether this option is to be used by setting the argument appropriately in a call to the banded linear algebra setup function
ivp_stiff_bandjac_setup()
.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 as follows:
- Parameters
- tfloat
, the current value of the independent variable.
- yfloat, ndarray, shape
, for , the current solution component.
- ydotfloat, ndarray, shape
The derivative of the solution at the current point .
- hfloat
The current step size.
- dfloat
The argument which depends on the integration method.
- mlint
The number of subdiagonals and superdiagonals respectively in the band.
- muint
The number of subdiagonals and superdiagonals respectively in the band.
- pfloat, ndarray, shape
Is set to zero.
- dataarbitrary, optional, modifiable in place
User-communication data for callback functions.
- Returns
- pfloat, array-like, shape
Elements of the Jacobian matrix stored as specified by the following pseudocode:
for i in range(1, neq+1): j1 = max(i-ml, 1) j2 = min(i+mu, neq) for j in range(j1, j2+1): k = min(ml+1-i, 0) + j p[k-1, i-1] = J[i-1, j-1]
See also
lapacklin.dgbtrf
.Only nonzero elements of this array need be set, since it is preset to zero before the call to .
- monitrNone or callable (hnext, y, imon, inln, hmin, hmax) = monitr(t, hlast, hnext, y, ydot, comm, r, acor, imon, hmin, hmax, nqu, data=None), optional
Note: if this argument is None then a NAG-supplied facility will be used.
performs tasks requested by you.
If this option is not required, the actual argument for must be None.
- Parameters
- tfloat
The current value of the independent variable.
- hlastfloat
The last step size successfully used by the integrator.
- hnextfloat
The step size that the integrator proposes to take on the next step.
- yfloat, ndarray, shape
, the values of the dependent variables evaluated at .
- ydotfloat, ndarray, shape
The time derivatives of the vector .
- commdict, communication object, modifiable in place
Communication structure.
This argument may be passed as argument in a call to
ivp_stiff_nat_interp()
or in a call toivp_stiff_c1_interp()
to enable you to carry out interpolation using either of those functions.- rfloat, ndarray, shape
If and , the first elements contain the residual vector .
- acorfloat, ndarray, shape
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
ivp_stiff_errest()
.- imonint
A flag indicating under what circumstances was called:
Entry from the integrator after (set in ) 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 ).
The current step was successful.
- hminfloat
The minimum step size to be taken on the next step.
- hmaxfloat
The maximum step size to be taken on the next step.
- nquint
The order of the integrator used on the last step. This is supplied to enable you to carry out interpolation using either of the functions
ivp_stiff_nat_interp()
orivp_stiff_c1_interp()
.- dataarbitrary, optional, modifiable in place
User-communication data for callback functions.
- Returns
- hnextfloat
The next step size to be used. If this is different from the input value, must be set to .
- yfloat, array-like, shape
These values must not be changed unless is set to .
- imonint
May be reset to determine subsequent action in
ivp_stiff_imp_bandjac
.Integration is to be halted. A return will be made from the integrator to the calling (sub)program with = 12.
Allow the integrator to continue with its own internal strategy. The integrator will try up to three restarts unless on exit.
Return to the internal nonlinear equation solver, where the action taken is determined by the value of (see ).
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 , provided by , 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 . and may be altered if desired.
Continue the integration but using a new value of and possibly new values of and .
- inlnint
The action to be taken by the internal nonlinear equation solver when is exited with . By setting and returning to the integrator, the residual vector is evaluated and placed in the array , and then is called again. At present this is the only option available: must not be set to any other value.
- hminfloat
The minimum step size to be used. If this is different from the input value, must be set to or .
- hmaxfloat
The maximum step size to be used. If this is different from the input value, must be set to or . If is set to zero, no limit is assumed.
- dataarbitrary, optional
User-communication data for callback functions.
- io_managerFileObjManager, optional
Manager for I/O in this routine.
- spiked_sorderstr, optional
If in is spiked (i.e., has unit extent in all but one dimension, or has size ), selects the storage order to associate with it in the NAG Engine:
- spiked_sorder =
row-major storage will be used;
- spiked_sorder =
column-major storage will be used.
- Returns
- tfloat
The value at which the computed solution is returned (usually at ).
- toutfloat
Normally unchanged. However, when , contains the value of at which initial values have been computed without performing any integration. See descriptions of and .
- yfloat, ndarray, shape
The computed solution vector, evaluated at (usually ).
- ydotfloat, ndarray, shape
The time derivatives of the vector at the last integration point.
- lderivbool, ndarray, shape
is normally unchanged. However if and internal initialization was successful then .
, if implicit equations were detected.
Otherwise .
- Raises
- NagValueError
- (errno )
On entry, and for all elements.
Check the evaluation of the residual for this value of .
- (errno )
was set to an illegal value during initialization.
at time .
- (errno )
set .
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 )
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 )
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 )
set .
Constraint: .
- (errno )
appears to have overwritten the solution vector.
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 )
set , which signals that an error condition has occurred in the solution vector, its time derivative or in the value of . It was not possible to remove this condition.
at .
- (errno )
Attempt was made to reduce the step size to a value less than the minimum step size during the calculation of initial values.
Minimum stepsize: .
- (errno )
The residual function returned an error when calculating the initial values of the solution and its time derivative.
- (errno )
Workspace error occurred when trying to form the Jacobian matrix in calculating the initial values of the solution and its time derivative.
- (errno )
A singular Jacobian has been encountered. You should check the problem formulation and Jacobian calculation.
- (errno )
Not enough real store provided for sparse matrix solver.
Units of store needed: . Amount provided: .
- (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 integer store provided for internal storage pointers.
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 .
- (errno )
Either the banded matrix linear algebra setup function was not called first or a communication array has become corrupted.
- 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 )
Nonlinear solver failed to converge using a damped Newton method to solve for initial values.
Damping factor: ; convergence rate: .
- (errno )
The user problem has one or more inconsistencies between the and parts. Integration will not be attempted.
- (errno )
set , 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_imp_bandjac
is a general purpose function for integrating the initial value problem for a stiff system of implicit ordinary differential equations coupled with algebraic equations, written in the formIt is designed specifically for the case where the resulting Jacobian is a banded matrix (see the description of ).
Both interval and step oriented modes of operation are available and also modes designed to permit intermediate output within an interval oriented mode.
A typical calling program for
ivp_stiff_imp_bandjac
would involve calling the banded matrix linear algebra setup functionivp_stiff_bandjac_setup()
, the Backward Differentiation Formula (BDF) integrator setup functionivp_stiff_bdf()
, and its diagnostic counterpartivp_stiff_integ_diag()
as well as the call toivp_stiff_imp_bandjac
. The linear algebra setup functionivp_stiff_bandjac_setup()
and one of the integrator setup functions,ivp_stiff_dassl()
,ivp_stiff_bdf()
orivp_stiff_blend()
, must be called prior to the call ofivp_stiff_imp_bandjac
. The integrator diagnostic functionivp_stiff_integ_diag()
may be called after the call toivp_stiff_imp_bandjac
. There is also a function,ivp_stiff_contin()
, designed to permit you to change step size on a continuation call toivp_stiff_imp_bandjac
without restarting the integration process.