Class RungeKutta<P>

java.lang.Object
org.bzdev.math.RungeKutta<P>

public abstract class RungeKutta<P> extends Object
Implementation of the Runge Kutta algorithm for first-order differential equations. For an independent variable t (which will be called the "parameter" mainly so that a method with a short name getParam() can be used to obtain its current value), and a dependent variable y(t), the Runge Kutta algorithm numerically solves the differential equation
y'(t) = f(t, y(t))
The method getParam() returns the independent variable while the methods getValue() and getDeriv() return the dependent variable and its first derivative respectively. The independent variable is changed, and the dependent variable updated, by using the methods update(double), update(double,int), adaptiveUpdate(double), updateTo(double), or updateTo(double,double). The methods update(double), update(double,int), and updateTo(double,double) use the 4th order Runge-Kutta method, while the methods adaptiveUpdate(double) and update(double) use the Runge-Kutta-Fehlberg method (RK45), which adaptively adjusts the step size given a specified tolerance. The method minStepSize() will report the minimum step size used by the Runge-Kutta-Fehlberg method. This is useful if one wants an estimate of the number of knots needed for a spline that will fit the solution to a differential equation. Before the Runge-Kutta-Fehlberg method is used, the method setTolerance(double) must be called.

When parameters are provided (via a generic type), the parameters are used to adjust the behavior of the class' function, typically by providing various constants that it needs. This can reduce the number of classes created by an application in some instances. The parameters are represented by a Java class typically used as a container to hold a set of values.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructor.
    RungeKutta(double t0, double y0)
    Constructor with initial values.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    adaptiveUpdate(double tincr)
    Update the independent and dependent variables adaptively, increasing the parameter by a specified amount.
    protected abstract double
    function(double t, double y)
    Function to compute the derivative of y given an independent variable t and a dependent variable y.
    final double
    Get the current value of the deriviative of the dependent variable
    final double
    Get the current value of the independent variable.
    Get a RungeKuttaMV's parameters.
    double
    Get the current tolerance.
    final double
    Get the current value of the dependent variable.
    double
    Get the minimum step size used since the last time the initial values were set, the tolerance was changed, or this method was called.
    static RungeKutta
    Create a new instance of RungeKutta that uses an instance of RealValuedFunctionTwo as its function.
    static RungeKutta
    newInstance(RealValuedFunctionTwo f, double t0, double y0)
    Create a new instance of RungeKutta that uses an instance of RealValuedFunctionTwo as its function, providing initial values.
    static RungeKutta
    Create a new instance of RungeKutta that uses an instance of RealValuedFunctionVA as its function.
    static RungeKutta
    newInstance(RealValuedFunctionVA f, double t0, double y0)
    Create a new instance of RungeKutta that uses an instance of RealValuedFunctionVA as its function, providing initial values.
    static RungeKutta
    Create a new instance of RungeKutta that uses an instance of RealValuedFunctTwoOps as its function.
    static RungeKutta
    newInstance(RealValuedFunctTwoOps f, double t0, double y0)
    Create a new instance of RungeKutta that uses an instance of RealValuedFunctTwoOps as its function and providing the initial conditions.
    void
    setInitialValues(double t0, double y0)
    Set initial conditions.
    void
    setParameters(P parameters)
    Set a RungeKuttaMV's parameters.
    void
    setTolerance(double tol)
    Set the tolerance.
    final void
    update(double h)
    Update the independent and dependent variables.
    final void
    update(double tincr, int n)
    Multi-step update of the independent and dependent variables.
    final void
    updateTo(double t)
    Update the independent and dependent variables so that the independent variable will have a specified value.
    final void
    updateTo(double t, double h)
    Update the independent and dependent variables so that the independent variable will have a specified value and so that the step size is a specified value or lower.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • RungeKutta

      public RungeKutta()
      Constructor. The initial values and parameters (if any) must be set before the class is used.
    • RungeKutta

      public RungeKutta(double t0, double y0)
      Constructor with initial values.
      Parameters:
      t0 - the initial value of the independent variable
      y0 - the initial value of the dependent variable
  • Method Details

    • setParameters

      public void setParameters(P parameters)
      Set a RungeKuttaMV's parameters. Parameters are used to provide values that will be constant while the Runge-Kutta algorithm is running and may be used by the method named 'function'.
      Parameters:
      parameters - the parameters
    • getParameters

      public P getParameters()
      Get a RungeKuttaMV's parameters. Parameters are used to provide values that will be constant while the Runge-Kutta algorithm is running and may be used by the method named 'function'.
      Returns:
      an instance of the class representing a Runge-Kutta class' parameters (this will be the same instance passed to setParameters)
    • function

      protected abstract double function(double t, double y)
      Function to compute the derivative of y given an independent variable t and a dependent variable y.
      Parameters:
      t - the value of the independent variable, with respect to which one differentiates
      y - the value of the dependent variable for the specified parameter
      Returns:
      the value of dy/dt as given by the differential equation
    • setInitialValues

      public void setInitialValues(double t0, double y0) throws IllegalArgumentException
      Set initial conditions. This is also done in the constructor.
      Parameters:
      t0 - the initial value of the independent variable
      y0 - the value of the dependent variable
      Throws:
      IllegalArgumentException - the initial values are not in the domain of this instance's function
    • getValue

      public final double getValue()
      Get the current value of the dependent variable.
      Returns:
      the value of the variable
    • getDeriv

      public final double getDeriv()
      Get the current value of the deriviative of the dependent variable
      Returns:
      the derivative of the dependent variable.
    • getParam

      public final double getParam()
      Get the current value of the independent variable.
      Returns:
      the value of the independent variable
    • update

      public final void update(double h)
      Update the independent and dependent variables.
      Parameters:
      h - the amount by which the independent variable changes
    • update

      public final void update(double tincr, int n)
      Multi-step update of the independent and dependent variables.
      Parameters:
      tincr - the amount by which the independent variable changes
      n - the number of steps to use in changing the independent variable
    • minStepSize

      public double minStepSize()
      Get the minimum step size used since the last time the initial values were set, the tolerance was changed, or this method was called.

      After this method is called, subsequent calls will return 0.0 unless either adaptiveUpdate(double) or updateTo(double) was called with an argument that would change the current value of the independent variable. Changing the initial value or the tolerance will also result in this method returning 0.0 until either adaptiveUpdate(double) or updateTo(double) is called with an argument that would change the current value of the independent variable.

      Returns:
      the minimum step size; 0.0 if the minimum cannot yet be determined
    • setTolerance

      public void setTolerance(double tol)
      Set the tolerance. When the independent variable is updated, changing it by an amount t, the error is bounded by the absolute value of the change in the parameter multiplied by the tolerance. A tolerance applies to the methods adaptiveUpdate(double) and updateTo(double).

      The class SimObject had a public method named SimObject.update() that by default calls a protected method named SimObject.update(double,long). A simulation object whose behavior is determined by a differential equation may contain a field whose value is an instance of RungeKutta, and the implementation of these update methods may call adaptiveUpdate(double) or updateTo(double). When this is the case, the tolerance(s) must typically be set before the simulation object's update method is called. The exception is when the the simulation time matches the value of the independent variable so that adaptiveUpdate will be called with an argument of 0.0.

      Parameters:
      tol - the tolerance
      Throws:
      IllegalArgumentException - the argument was less than or equal to zero
    • getTolerance

      public double getTolerance()
      Get the current tolerance.
      Returns:
      the tolerance; zero if the tolerance has not been set
    • adaptiveUpdate

      public void adaptiveUpdate(double tincr) throws IllegalStateException
      Update the independent and dependent variables adaptively, increasing the parameter by a specified amount.
      Parameters:
      tincr - the increment for the independent variable.
      Throws:
      IllegalStateException - the method setTolerance(double) has not been called
    • updateTo

      public final void updateTo(double t) throws IllegalStateException
      Update the independent and dependent variables so that the independent variable will have a specified value. The step size will be determined by this method.
      Parameters:
      t - the new value of the independent variable
      Throws:
      IllegalStateException - the method setTolerance(double) has not been called
    • updateTo

      public final void updateTo(double t, double h) throws IllegalArgumentException
      Update the independent and dependent variables so that the independent variable will have a specified value and so that the step size is a specified value or lower.

      Note, regardless of the value of h, the maximum number of steps used will be no greater than Integer.MAX_VALUE.

      Parameters:
      t - the new value of the independent variable
      h - the step size limit
      Throws:
      IllegalArgumentException - an argument was out of range (e.g, h was 0 or negative)
    • newInstance

      public static RungeKutta newInstance(RealValuedFunctionVA f) throws IllegalArgumentException
      Create a new instance of RungeKutta that uses an instance of RealValuedFunctionVA as its function. This function's first argument is the Runge-Kutta algorithm's parameter (t) and its second argument is the initial value the Runge-Kutta algorithm's variable (y).

      Note: Usually f will be an instance of RealValuedFunctionTwo. If f is not, it must except a minimum of 2 arguments and it will be passed exactly two arguments when this instance is updated.

      Parameters:
      f - the function, which must take two arguments
      Returns:
      a new instance of RungeKutta
      Throws:
      IllegalArgumentException - the function f cannot take two arguments
    • newInstance

      public static RungeKutta newInstance(RealValuedFunctionVA f, double t0, double y0)
      Create a new instance of RungeKutta that uses an instance of RealValuedFunctionVA as its function, providing initial values. This function's first argument is the Runge-Kutta algorithm's parameter (t) and its second argument is the initial value the Runge-Kutta algorithm's variable (y).

      Note: Usually f will be an instance of RealValuedFunctionTwo. If f is not, it must except a minimum of 2 arguments and it will be passed exactly two arguments when this instance is updated.

      Parameters:
      f - the function, which must take exactly two arguments
      t0 - the initial value of the independent variable with respect to which one differentiates
      y0 - the initial value of the variable for the specified parameter
      Returns:
      a new instance of RungeKutta
      Throws:
      IllegalArgumentException - the function f cannot take two arguments
    • newInstance

      public static RungeKutta newInstance(RealValuedFunctionTwo f) throws IllegalArgumentException
      Create a new instance of RungeKutta that uses an instance of RealValuedFunctionTwo as its function. This function's first argument is the Runge-Kutta algorithm's parameter (t) and its second argument is the initial value the Runge-Kutta algorithm's variable (y).
      Parameters:
      f - the function, which must take two arguments
      Returns:
      a new instance of RungeKutta
      Throws:
      IllegalArgumentException - the function f cannot take two arguments
    • newInstance

      public static RungeKutta newInstance(RealValuedFunctionTwo f, double t0, double y0)
      Create a new instance of RungeKutta that uses an instance of RealValuedFunctionTwo as its function, providing initial values. This function's first argument is the Runge-Kutta algorithm's parameter (t) and its second argument is the initial value the Runge-Kutta algorithm's variable (y).
      Parameters:
      f - the function, which must take exactly two arguments
      t0 - the initial value of the independent variable with respect to which one differentiates
      y0 - the initial value of the variable for the specified parameter
      Returns:
      a new instance of RungeKutta
      Throws:
      IllegalArgumentException - the function f cannot take two arguments
    • newInstance

      public static RungeKutta newInstance(RealValuedFunctTwoOps f)
      Create a new instance of RungeKutta that uses an instance of RealValuedFunctTwoOps as its function. This function's first argument is the Runge-Kutta algorithm's parameter (t) and its second argument is the initial value the Runge-Kutta algorithm's variable (y). A lambda expression may be used as the first argument.
      Parameters:
      f - the function, which must take two arguments
      Returns:
      a new instance of RungeKutta
      Throws:
      IllegalArgumentException - the function f cannot take two arguments
    • newInstance

      public static RungeKutta newInstance(RealValuedFunctTwoOps f, double t0, double y0)
      Create a new instance of RungeKutta that uses an instance of RealValuedFunctTwoOps as its function and providing the initial conditions. This function's first argument is the Runge-Kutta algorithm's parameter (t) and its second argument is the initial value the Runge-Kutta algorithm's variable (y). A lambda expression may be used as the first argument.
      Parameters:
      f - the function, which must take two arguments
      t0 - the initial value of the independent variable with respect to which one differentiates
      y0 - the initial value of the variable for the specified parameter
      Returns:
      a new instance of RungeKutta
      Throws:
      IllegalArgumentException - the function f cannot take two arguments