Package org.jscience.mathematics.analysis.ode

This package provides classes to solve Ordinary Differential Equations problems.

See:
          Description

Interface Summary
FirstOrderDifferentialEquations This interface represents a first order differential equations set.
FirstOrderIntegrator This interface represents a first order integrator for differential equations.
FixedStepHandler This interface represents a handler that should be called after each successful fixed step.
SecondOrderDifferentialEquations This interface represents a second order differential equations set.
SecondOrderIntegrator This interface represents a second order integrator for differential equations.
StepHandler This interface represents a handler that should be called after each successful step.
StepInterpolator This interface represents an interpolator over the last step during an ODE integration.
SwitchingFunction This interface represents a switching function.
 

Class Summary
AbstractStepInterpolator This abstract class represents an interpolator over the last step during an ODE integration.
AdaptiveStepsizeIntegrator This abstract class holds the common part of all adaptive stepsize integrators for Ordinary Differential Equations.
ClassicalRungeKuttaIntegrator This class implements the classical fourth order Runge-Kutta integrator for Ordinary Differential Equations (it is the most often used Runge-Kutta method).
ContinuousOutputModel This class stores all information provided by an ODE integrator during the integration process and build a continuous model of the solution from this.
DormandPrince54Integrator This class implements the 5(4) Dormand-Prince integrator for Ordinary Differential Equations.
DormandPrince853Integrator This class implements the 8(5,3) Dormand-Prince integrator for Ordinary Differential Equations.
DummyStepHandler This class is a step handler that do nothing.
DummyStepInterpolator This class is a step interpolator that does nothing.
EulerIntegrator This class implements a simple Euler integrator for Ordinary Differential Equations.
FirstOrderConverter This class converts second order differential equations to first order ones.
GillIntegrator This class implements the Gill fourth order Runge-Kutta integrator for Ordinary Differential Equations .
GraggBulirschStoerIntegrator This class implements a Gragg-Bulirsch-Stoer integrator for Ordinary Differential Equations.
HighamHall54Integrator This class implements the 5(4) Higham and Hall integrator for Ordinary Differential Equations.
MidpointIntegrator This class implements a second order Runge-Kutta integrator for Ordinary Differential Equations.
RungeKuttaFehlbergIntegrator This class implements the common part of all Runge-Kutta-Fehlberg integrators for Ordinary Differential Equations.
RungeKuttaIntegrator This class implements the common part of all fixed step Runge-Kutta integrators for Ordinary Differential Equations.
StepNormalizer This class wraps an object implementing FixedStepHandler into a StepHandler.
SwitchingFunctionsHandler This class handles several switching functions during integration.
ThreeEighthesIntegrator This class implements the 3/8 fourth order Runge-Kutta integrator for Ordinary Differential Equations.
 

Exception Summary
DerivativeException This exception is made available to users to report the error conditions that are trigegred while computing the differential equations.
IntegrationException This exception is made available to users to report the error conditions that are triggered during integration
 

Package org.jscience.mathematics.analysis.ode Description

This package provides classes to solve Ordinary Differential Equations problems.

This package solves Initial Value Problems of the form y'=f(t,y) with t0 and y(t0)=y0 known. The provided integrators compute an estimate of y(t) from t=t0 to t=t1.

All integrators provide dense output. This means that besides computing the state vector at discrete times, they also provide a cheap mean to get the state between the time steps. They do so through classes extending the StepInterpolator abstract class, which are made available to the user at the end of each step.

All integrators handle multiple switching functions. This means that the integrator can be driven by discrete events (occurring when the signs of user-supplied switching functions change). The steps are shortened as needed to ensure the events occur at step boundaries (even if the integrator is a fixed-step integrator). When the events are triggered, integration can be stopped (this is called a G-stop facility), the state vector can be changed, or integration can simply go on. The latter case is useful to handle discontinuities in the differential equations gracefully and get accurate dense output even close to the discontinuity. The events are detected when the functions signs are different at the beginning and end of the current step, or at several equidistant points inside the step if its length becomes larger than the maximal checking interval specified for the given switching function. This time interval should be set appropriately to avoid missing some switching function sign changes (it is possible to set it to Double.POSITIVE_INFINITY if the sign changes cannot be missed).

The user should describe his problem in his own classes (UserProblem in the diagram below) which should implement the FirstOrderDifferentialEquations interface. Then he should pass it to the integrator he prefers among all the classes that implement the FirstOrderIntegrator interface. In order to simplify the mapping between domain objects and the flat arrays needed in order to implement the FirstOrderDifferentialEquations interface, the ArraySliceMappable interface and ArrayMapper class provided by the utilities package can be used.

The solution of the integration problem is provided by two means. The first one is aimed towards simple use: the state vector at the end of the integration process is copied in the y array of the FirstOrderIntegrator.integrate method. The second one should be used when more in-depth information is needed throughout the integration process. The user can register an object implementing the StepHandler interface or a StepNormalizer object wrapping a user-specified object implementing the FixedStepHandler interface into the integrator before calling the FirstOrderIntegrator.integrate method. The user object will be called appropriately during the integration process, allowing the user to process intermediate results. The default step handler does nothing.

ContinuousOutputModel is a special-purpose step handler that is able to store all steps and to provide transparent access to any intermediate result once the integration is over. An important feature of this class is that it implements the Serializable interface. This means that a complete continuous model of the integrated function througout the integration range can be serialized and reused later (if stored into a persistent medium like a filesystem or a database) or elsewhere (if sent to another application). Only the result of the integration is stored, there is no reference to the integrated problem by itself.

Other default implementations of the StepHandler interface are available for general needs (DummyStepHandler, StepNormalizer) and custom implementations can be developped for specific needs. As an example, if an application is to be completely driven by the integration process, then most of the application code will be run inside a step handler specific to this application.

Some integrators (the simple ones) use fixed steps that are set at creation time. The more efficient integrators use variable steps that are handled internally in order to control the integration error with respect to a specified accuracy (these integrators extend the AdaptiveStepsizeIntegrator abstract class). In this case, the step handler which is called after each successful step shows up the variable stepsize. The StepNormalizer class can be used to convert the variable stepsize into a fixed stepsize that can be handled by classes implementing the FixedStepHandler interface. Adaptive stepsize integrators can automatically compute the initial stepsize by themselves, however the user can specify it if he prefers to retain full control over the integration or if the automatic guess is wrong.

Fixed Step Integrators
Name Order
Euler 1
Midpoint 2
Classical Runge-Kutta 4
Gill 4
3/8 4

Adaptive Stepsize Integrators
Name Integration Order Error Estimation Order
Higham and Hall 5 4
Dormand-Prince 5(4) 5 4
Dormand-Prince 8(5,3) 8 5 and 3
Gragg-Bulirsch-Stoer variable (up to 18 by default) variable

The class diagram below shows a typical example use of this package. The orange boxes are the classes the user should develop, the white boxes are the interfaces and classes already provided by the library. The main application build an ODE problem that involve several domain objects (for example the orbit of a spacecraft and its attitude) which are mapped into one flat array representing the state vector using an ArrayMapper object. The UserProblem object is provided by the main application to an integrator (in this exemple the Gragg-Bulirsch-Stoer integrator has been chosen) together with a step handler (in this exemple the already existing ContinuousOutputModel class has been chosen). In this case, the user waits until the end of integration before continuing his own processing, and uses the ContinuousOutputModel object to navigate throughout the integration interval once it has been filled up by the integrator.