## org.apache.commons.math.ode.nonstiff
Class EmbeddedRungeKuttaIntegrator

    java.lang.Object
      org.apache.commons.math.ode.AbstractIntegrator
          org.apache.commons.math.ode.nonstiff.AdaptiveStepsizeIntegrator
              org.apache.commons.math.ode.nonstiff.EmbeddedRungeKuttaIntegrator

All Implemented Interfaces:
  FirstOrderIntegrator, ODEIntegrator

Direct Known Subclasses:
  DormandPrince54Integrator, DormandPrince853Integrator, HighamHall54Integrator

    public abstract class EmbeddedRungeKuttaIntegrator

extends AdaptiveStepsizeIntegrator

This class implements the common part of all embedded Runge-Kutta integrators for Ordinary Differential Equations.

These methods are embedded explicit Runge-Kutta methods with two sets of coefficients allowing to estimate the error, their Butcher arrays are as follows :

        0  |
       c2  | a21
       c3  | a31  a32
       ... |        ...
       cs  | as1  as2  ...  ass-1
           |--------------------------
           |  b1   b2  ...   bs-1  bs
           |  b'1  b'2 ...   b's-1 b's

In fact, we rather use the array defined by ej = bj - b'j to compute directly the error rather than computing two estimates and then comparing them.

Some methods are qualified as fsal (first same as last) methods. This means the last evaluation of the derivatives in one step is the same as the first in the next step. Then, this evaluation can be reused from one step to the next one and the cost of such a method is really s-1 evaluations despite the method still has s stages. This behaviour is true only for successful steps, if the step is rejected after the error estimation phase, no evaluation is saved. For an fsal method, we have cs = 1 and asi = bi for all i.

Since:
  1.2
Version:
  $Revision: 927202 $ $Date: 2010-03-24 18:11:51 -0400 (Wed, 24 Mar 2010) $

Field Summary
`private double[][]` `a` Internal weights from Butcher array (without the first empty row).
`private double[]` `b` External weights for the high order method from Butcher array.
`private double[]` `c` Time steps from Butcher array (without the first zero).
`private double` `exp` Stepsize control exponent.
`private boolean` `fsal` Indicator for fsal methods.
`private double` `maxGrowth` Maximal growth factor for stepsize control.
`private double` `minReduction` Minimal reduction factor for stepsize control.
`private RungeKuttaStepInterpolator` `prototype` Prototype of the step interpolator.
`private double` `safety` Safety factor for stepsize control.

Fields inherited from class org.apache.commons.math.ode.nonstiff.AdaptiveStepsizeIntegrator
`scalAbsoluteTolerance, scalRelativeTolerance, vecAbsoluteTolerance, vecRelativeTolerance`

Fields inherited from class org.apache.commons.math.ode.AbstractIntegrator
`eventsHandlersManager, stepHandlers, stepSize, stepStart`

Constructor Summary
`protected` `EmbeddedRungeKuttaIntegrator(java.lang.String name, boolean fsal, double[] c, double[][] a, double[] b, RungeKuttaStepInterpolator prototype, double minStep, double maxStep, double[] vecAbsoluteTolerance, double[] vecRelativeTolerance)` Build a Runge-Kutta integrator with the given Butcher array.
`protected` `EmbeddedRungeKuttaIntegrator(java.lang.String name, boolean fsal, double[] c, double[][] a, double[] b, RungeKuttaStepInterpolator prototype, double minStep, double maxStep, double scalAbsoluteTolerance, double scalRelativeTolerance)` Build a Runge-Kutta integrator with the given Butcher array.

Method Summary
`protected abstract double` `estimateError(double[][] yDotK, double[] y0, double[] y1, double h)` Compute the error ratio.
`double` `getMaxGrowth()` Get the maximal growth factor for stepsize control.
`double` `getMinReduction()` Get the minimal reduction factor for stepsize control.
`abstract int` `getOrder()` Get the order of the method.
`double` `getSafety()` Get the safety factor for stepsize control.
`double` `integrate(FirstOrderDifferentialEquations equations, double t0, double[] y0, double t, double[] y)` Integrate the differential equations up to the given time.
`void` `setMaxGrowth(double maxGrowth)` Set the maximal growth factor for stepsize control.
`void` `setMinReduction(double minReduction)` Set the minimal reduction factor for stepsize control.
`void` `setSafety(double safety)` Set the safety factor for stepsize control.

Methods inherited from class org.apache.commons.math.ode.nonstiff.AdaptiveStepsizeIntegrator
`filterStep, getCurrentStepStart, getMaxStep, getMinStep, initializeStep, resetInternalState, sanityChecks, setInitialStepSize`

Methods inherited from class org.apache.commons.math.ode.AbstractIntegrator
`addEndTimeChecker, addEventHandler, addStepHandler, clearEventHandlers, clearStepHandlers, computeDerivatives, getCurrentSignedStepsize, getEvaluations, getEventHandlers, getMaxEvaluations, getName, getStepHandlers, requiresDenseOutput, resetEvaluations, setEquations, setMaxEvaluations`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### fsal

    private final boolean fsal

  Indicator for fsal methods.

### c

    private final double[] c

  Time steps from Butcher array (without the first zero).

### a

    private final double[][] a

  Internal weights from Butcher array (without the first empty row).

### b

    private final double[] b

  External weights for the high order method from Butcher array.

### prototype

    private final RungeKuttaStepInterpolator prototype

  Prototype of the step interpolator.

### exp

    private final double exp

  Stepsize control exponent.

### safety

    private double safety

  Safety factor for stepsize control.

### minReduction

    private double minReduction

  Minimal reduction factor for stepsize control.

### maxGrowth

    private double maxGrowth

  Maximal growth factor for stepsize control.

Constructor Detail

### EmbeddedRungeKuttaIntegrator

    protected EmbeddedRungeKuttaIntegrator(java.lang.String name,
                                           boolean fsal,
                                           double[] c,
                                           double[][] a,
                                           double[] b,
                                           RungeKuttaStepInterpolator prototype,
                                           double minStep,
                                           double maxStep,
                                           double scalAbsoluteTolerance,
                                           double scalRelativeTolerance)

  Build a Runge-Kutta integrator with the given Butcher array.

  Parameters:
    `name` - name of the method
    `fsal` - indicate that the method is an fsal
    `c` - time steps from Butcher array (without the first zero)
    `a` - internal weights from Butcher array (without the first empty row)
    `b` - propagation weights for the high order method from Butcher array
    `prototype` - prototype of the step interpolator to use
    `minStep` - minimal step (must be positive even for backward integration), the last step can be smaller than this
    `maxStep` - maximal step (must be positive even for backward integration)
    `scalAbsoluteTolerance` - allowed absolute error
    `scalRelativeTolerance` - allowed relative error

### EmbeddedRungeKuttaIntegrator

    protected EmbeddedRungeKuttaIntegrator(java.lang.String name,
                                           boolean fsal,
                                           double[] c,
                                           double[][] a,
                                           double[] b,
                                           RungeKuttaStepInterpolator prototype,
                                           double minStep,
                                           double maxStep,
                                           double[] vecAbsoluteTolerance,
                                           double[] vecRelativeTolerance)

  Build a Runge-Kutta integrator with the given Butcher array.

  Parameters:
    `name` - name of the method
    `fsal` - indicate that the method is an fsal
    `c` - time steps from Butcher array (without the first zero)
    `a` - internal weights from Butcher array (without the first empty row)
    `b` - propagation weights for the high order method from Butcher array
    `prototype` - prototype of the step interpolator to use
    `minStep` - minimal step (must be positive even for backward integration), the last step can be smaller than this
    `maxStep` - maximal step (must be positive even for backward integration)
    `vecAbsoluteTolerance` - allowed absolute error
    `vecRelativeTolerance` - allowed relative error

Method Detail

### getOrder

    public abstract int getOrder()

  Get the order of the method.

  Returns:
    order of the method

### getSafety

    public double getSafety()

  Get the safety factor for stepsize control.

  Returns:
    safety factor

### setSafety

    public void setSafety(double safety)

  Set the safety factor for stepsize control.

  Parameters:
    `safety` - safety factor

### integrate

    public double integrate(FirstOrderDifferentialEquations equations,
                            double t0,
                            double[] y0,
                            double t,
                            double[] y)
                     throws DerivativeException,
                            IntegratorException

  Integrate the differential equations up to the given time.

  This method solves an Initial Value Problem (IVP).

  Since this method stores some internal state variables made available in its public interface during integration (`ODEIntegrator.getCurrentSignedStepsize()`), it is not thread-safe.

  Specified by:
    `integrate` in interface `FirstOrderIntegrator`
  Specified by:
    `integrate` in class `AdaptiveStepsizeIntegrator`
  Parameters:
    `equations` - differential equations to integrate
    `t0` - initial time
    `y0` - initial value of the state vector at t0
    `t` - target time for the integration (can be set to a value smaller than `t0` for backward integration)
    `y` - placeholder where to put the state vector at each successful step (and hence at the end of integration), can be the same object as y0
  Returns:
    stop time, will be the same as target time if integration reached its target, but may be different if some `EventHandler` stops it at some point.
  Throws:
    `DerivativeException` - this exception is propagated to the caller if the underlying user function triggers one
    `IntegratorException` - if the integrator cannot perform integration

### getMinReduction

    public double getMinReduction()

  Get the minimal reduction factor for stepsize control.

  Returns:
    minimal reduction factor

### setMinReduction

    public void setMinReduction(double minReduction)

  Set the minimal reduction factor for stepsize control.

  Parameters:
    `minReduction` - minimal reduction factor

### getMaxGrowth

    public double getMaxGrowth()

  Get the maximal growth factor for stepsize control.

  Returns:
    maximal growth factor

### setMaxGrowth

    public void setMaxGrowth(double maxGrowth)

  Set the maximal growth factor for stepsize control.

  Parameters:
    `maxGrowth` - maximal growth factor

### estimateError

    protected abstract double estimateError(double[][] yDotK,
                                            double[] y0,
                                            double[] y1,
                                            double h)

  Compute the error ratio.

  Parameters:
    `yDotK` - derivatives computed during the first stages
    `y0` - estimate of the step at the start of the step
    `y1` - estimate of the step at the end of the step
    `h` - current step
  Returns:
    error ratio, greater than 1 if step should be rejected

Copyright (c) 2003-2010 Apache Software Foundation