Initial Value Solver for Systems of Ordinary Differential Equations

DESCRIPTION:

Finds the solution of a system of ordinary differential equations at a point given solution values at another point.

USAGE:

ivp.ab(final.point, initial, derivatives, tolerances=<<see below>>,  
  max.calls=<<see below>>, stepwise=F, safe=T, restart=<<see below>>,  
  aux = NULL) 

REQUIRED ARGUMENTS:

final.point
the point at which the solution is desired.
initial
a vector whose first element is the initial point at which the function values are known, and whose remaining elements are the function values at the initial point, or else a list whose first component is the initial point at which function values are known, and whose second component is a vector giving the function values at the initial point. This argument is not used when restarting.
derivatives
a vector-valued S-PLUS function of the form derivatives(x,y,<>), where x is the variable of differentiation, and y is a vector of function values at x. The function should return the vector of derivatives of each function at x. This argument is not used when restarting.

OPTIONAL ARGUMENTS:

tolerances
relative and absolute error tolerances for local error, expressed as either a numeric value or a list with two components labeled "rel" and "abs". If numeric, then the same values are used for relative and absolute error tolerances. A different tolerance may be assigned to each equation in the system. The default is .0001 for all tolerances.
max.calls
an upper limit on the number of calls to derivatives. Termination occurs prior to reaching final.point if max.calls has been reached or exceeded and the solver is about to begin a new step. The default is 100 times the product of the number of equations and the length of the interval from the initial point to the final point incremented by one.
stepwise
logical variable indicating whether or not the solution at the next intermediate step should be given rather than the solution at final.point. By default, it assumed that the solution at final.point is desired.
safe
logical variable indicating whether or not it is safe to evaluate derivatives beyond final.point. The default is to assume that it is safe to do so.
restart
name of a S-PLUS object created by a call to ivp.ab. Use this argument to continue solving an initial value problem beyond the original final point.
aux
a list of auxiliary arguments for derivatives.

VALUE:

a list containing the following elements :
final.point
the input value of final.point. Used as the default value of final.point when restarting.
values
a vector whose first element is the last point at which an approximate solution has been computed, and whose remaining elements are the computed function values at that point.
derivatives
a vector whose first element is the last point at which an approximate solution has been computed, and whose remaining elements are the computed derivatives values at that point and the computed solution values.
message
a message indicating the reason for termination.
count
a vector whose first element is the total number of calls to derivatives, and whose second element is the total number of intermediate steps taken by the procedure.
attr
the list of attributes returned after the last call to derivatives.
aux
the list of final values for all the auxiliary arguments for derivatives.
other
other information needed for the method to be restarted from last.
call
a copy of the call to ivp.ab.

DETAILS:

The order of functions in the second argument y in derivatives and in the value returned by derivatives should be the same as that of the initial function values given in initial. Users can accumulate information through attributes of the function derivatives . If these attributes include any additional arguments to derivatives , the next call to derivatives uses the new values of those arguments. This feature should not be used to change the definition of the system of differential equations within a call to ivp.ab. Since ivp.ab makes repeated calls to the derivatives, the latter should be made as efficient as possible, e. g., though calls to C or Fortran functions if necessary. Function values at the final point may be interpolated from function values at points beyond that point if safe is set to TRUE. When restarting, input values initial and derivatives are ignored. New values may be supplied for the other arguments; defaults are taken from restart .

METHOD:

The method used is a modification of the Fortran program deabm from CMLIB, written by L. F. Shampine and H. A. Watts, implementing an adaptive Adams-Bashforth predictor-corrector method. This function is suitable for non-stiff and mildly stiff systems of ordinary differential equations. For further background, see Shampine and Gordon (1975) - deabm is a modification of the program ode described in that reference.

REFERENCES:

National Bureau of Standards (1988). Core Mathematical Library (CMLIB). Gaithersburg, MD, USA.

Shampine, L. F., and Watts, H. A. (1979). DEPAC - Design of a User Oriented Package of ODE Solvers. Technical Report SAND-79-2374, Sandia Laboratories, Albuquerque, NM USA.

Shampine, L. F., and Gordon, M. (1975). Computer Solution of Ordinary Differential Equations : The Initial Value Problem. Freeman, San Franciso, USA.

EXAMPLES:

# returns A*c(cos(B*x),sin(B*x)) with initial point 0, initial values = c(0, A) 
fun <- function(x, y, B) c(B * y[2], - B * y[1]) 
out <- ivp.ab( fin=pi/2, init=c( 0, c( 0, 1)), deriv=fun, aux=list(B = 1)) 
out$values[-1] 
c(sin(pi/2), cos(pi/2)) 
# continue solution to pi using the restart feature 
out <- ivp.ab( final = pi, restart = out) 
out$values[-1] 
c(sin(pi), cos(pi))