net.algart.model3d.common.movement.model
Class RungeKuttaMovementIntegrator

java.lang.Object
  extended by net.algart.model3d.common.movement.model.AbstractMovementIntegrator
      extended by net.algart.model3d.common.movement.model.RungeKuttaMovementIntegrator
All Implemented Interfaces:
MovementIntegrator

public class RungeKuttaMovementIntegrator
extends AbstractMovementIntegrator

The general implementation of the MovementIntegrator interface, based on the family of explicit Runge-Kutta methods of any order for solving Cauchy problem.

More precisely, let the coordinates and velocities of all items at the current moment tn be described by the vector wn, and we want to find the coordinates and velocities wn+1 at the next moment tn+1=tnt — see comments to MovementIntegrator. This class uses the following formulas:

wn+1 = wn + γ0k0 + γ1k1 + ... + γs−1ks−1
k0 = Δt f(tn + α0Δt, wn)
k1 = Δt f(tn + α1Δt, wn + β1,0k0)
k2 = Δt f(tn + α2Δt, wn + β2,0k0 + β2,1k1)
. . .
ks−1 = Δt f(tn + αs−1Δt, wn + βs−1,0k0 + βs−1,1k1 + ... + βs−1,s−2ks−2)

where s is some positive integer number (usually 4 or 6), f(t, w) is the vector function, calculating the derivatives dw/dt of coordinates and velocities w and, so, describing interaction of items (the product Δt f(tn, wn) is calculated by calculateLeftSide method), and the coefficients αi, βi,j and γi are the parameters of this class. In the case s=1, α0=0, γ0=1, it is equivalent to the Euler algorithm, implemented by EulerMovementIntegrator class.

This class can use an additional set of γ'i coefficients and calculate the 2nd (alternate) set of new coordinates and velocities w'n+1:

w'n+1 = wn + γ'0k0 + γ'1k1 + ... + γ's−1ks−1

In this case, this class uses such alternate result to estimate the maximal and mean errors: isErrorInformationAvailable() method returns true and maxLastCoordinateError(), meanLastCoordinateError(), maxLastVelocityError(), meanLastVelocityError() methods return necessary estimations, based on the difference between w'n+1 and wn+1. (The w'n+1 vector is used for this estimation only; the new coordinates and velocities at the next moment will be wn+1.) This mode is used if and only if this object was created by getGeneralizedRungeKuttaIntegrator(ItemSet, java.util.Collection, double, double[], double[][], double[], double[]), which has an additional alternateGamma argument (containing additional γ'i coefficients), or by getRungeKuttaFehlberg45Integrator(ItemSet, java.util.Collection, double) method.

Please see comments fo MovementIntegrator interface about multithreading usage.

AlgART Laboratory 2010

Since:
JDK 1.5
Version:
1.0
Author:
Daniel Alievsky

Field Summary
Modifier and Type Field and Description
 
Fields inherited from class net.algart.model3d.common.movement.model.AbstractMovementIntegrator
countOfCheckedNeighbours, countOfProcessedInteractions, countOfProcessedItems, countOfProcessedSymmetricInteractions, n
 
Method Summary
Modifier and Type Method and Description
 double[] getAlpha()
          Returns α coefficients of the Runge-Kutta algorithm.
 double[] getAlternateGamma()
          Returns γ' coefficients of the Runge-Kutta algorithm or null, if this object does not use them.
 double[][] getBeta()
          Returns β coefficients of the Runge-Kutta algorithm.
 double[] getGamma()
          Returns γ coefficients of the Runge-Kutta algorithm.
static RungeKuttaMovementIntegrator getGeneralizedRungeKuttaIntegrator(ItemSet itemSet, java.util.Collection<InteractionRule> interactionRules, double deltaT, double[] alpha, double[][] beta, double[] gamma)
          Creates new instance of this class with the specified sets of coefficients αi, βi,j and γi and without additional set of coefficients γ'i.
static RungeKuttaMovementIntegrator getGeneralizedRungeKuttaIntegrator(ItemSet itemSet, java.util.Collection<InteractionRule> interactionRules, double deltaT, double[] alpha, double[][] beta, double[] gamma, double[] alternateGamma)
          Creates new instance of this class with the specified sets of coefficients αi, βi,j, γi and additional set of coefficients γ'i (alternateGamma).
static RungeKuttaMovementIntegrator getRungeKutta4Integrator(ItemSet itemSet, java.util.Collection<InteractionRule> interactionRules, double deltaT)
          Creates new instance of this class with predefined sets of coefficients αi, βi,j and γi, corresponding to the classic 4th order Runge-Kutta method.
static RungeKuttaMovementIntegrator getRungeKuttaFehlberg45Integrator(ItemSet itemSet, java.util.Collection<InteractionRule> interactionRules, double deltaT)
          Creates new instance of this class with predefined sets of coefficients αi, βi,j, γi and γ'i, corresponding to the classic 5th order Runge-Kutta-Fehlberg method (also known as RKF-45).
 boolean isErrorInformationAvailable()
          Returns true if this implementation allows to estimate the maximal and mean error of calculating coordinates and velocities.
 double maxLastCoordinateError()
          Returns the estimation of the maximal error of calculating coordinates while the previous MovementIntegrator.performIteration() call, if this implementation supports this feature, or Double.NaN in other case.
 double maxLastVelocityError()
          Returns the estimation of the maximal error of calculating velocities while the previous MovementIntegrator.performIteration() call, if this implementation supports this feature, or Double.NaN in other case.
 double meanLastCoordinateError()
          Returns the estimation of the average error of calculating coordinates while the previous MovementIntegrator.performIteration() call, if this implementation supports this feature, or Double.NaN in other case.
 double meanLastVelocityError()
          Returns the estimation of the average error of calculating velocities while the previous MovementIntegrator.performIteration() call, if this implementation supports this feature, or Double.NaN in other case.
 void performIteration()
          Performs one iteration of integration.
protected  void preprocess()
          Performs necessary preprocessing before an iteration, in particular, reallocate all necessary work memory.
 java.lang.String toString()
          Returns a brief string description of this object.
 
Methods inherited from class net.algart.model3d.common.movement.model.AbstractMovementIntegrator
calculateLeftSide, calculateLeftSide, copyBasicSettings, getAccelerationLimit, getCounterOfCheckedNeighbours, getCounterOfProcessedInteractions, getCounterOfProcessedItems, getCounterOfProcessedSymmetricInteractions, getDeltaT, getInteractionRules, getItemSet, getNumberOfParallelTasks, getT, getVelocityLimit, getViscousForces, resetCounters, setAccelerationLimit, setDeltaT, setNumberOfParallelTasks, setT, setVelocityLimit, setViscousForces
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getGeneralizedRungeKuttaIntegrator

public static RungeKuttaMovementIntegrator getGeneralizedRungeKuttaIntegrator(ItemSet itemSet,
                                                                              java.util.Collection<InteractionRule> interactionRules,
                                                                              double deltaT,
                                                                              double[] alpha,
                                                                              double[][] beta,
                                                                              double[] gamma)
Creates new instance of this class with the specified sets of coefficients αi, βi,j and γi and without additional set of coefficients γ'i.

More precisely, the created algorithm will work with s=alpha.length coefficients αi=alpha[i], with βi,j=beta[i][j] and with γi=gamma[i], passed via alpha, beta and gamma arrays. The alternative coefficients γ'i will not be used; so, the returned object cannot estimate errors: isErrorInformationAvailable() method returns false.

The itemSet argument is just stored in an internal field, and this reference will be returned by getItemSet() method. Unlike this, the interactionRules collection is copied into a newly created list: no references to it are maintained by the created object. Also, the passed coefficients are deeply cloned — copied into newly created internal arrays: no references to them are maintained by the created object.

Parameters:
itemSet - the item set, which will be processed by this class.
interactionRules - the set of interaction rules, used by this class.
deltaT - the time step Δt.
alpha - α coefficients of the Runge-Kutta algorithm.
beta - β coefficients of the Runge-Kutta algorithm.
gamma - γ coefficients of the Runge-Kutta algorithm.
Returns:
new instance of this class.
Throws:
java.lang.NullPointerException - if one of the arguments is null or if one of interaction rules in the passed collection is null.
java.lang.IllegalArgumentException - if deltaT<0, or if alpha.length==0, or if alpha, beta and gamma lengths are not same, or if beta[k].length<k for some k.

getGeneralizedRungeKuttaIntegrator

public static RungeKuttaMovementIntegrator getGeneralizedRungeKuttaIntegrator(ItemSet itemSet,
                                                                              java.util.Collection<InteractionRule> interactionRules,
                                                                              double deltaT,
                                                                              double[] alpha,
                                                                              double[][] beta,
                                                                              double[] gamma,
                                                                              double[] alternateGamma)
Creates new instance of this class with the specified sets of coefficients αi, βi,j, γi and additional set of coefficients γ'i (alternateGamma).

More precisely, the created algorithm will work with s=alpha.length coefficients αi=alpha[i], with βi,j=beta[i][j], with γi=gamma[i] and with γ'i=alternateGamma[i], passed via alpha, beta, gamma and alternateGamma arrays. The returned object allows to estimate errors: isErrorInformationAvailable() method returns true.

The itemSet argument is just stored in an internal field, and this reference will be returned by getItemSet() method. Unlike this, the interactionRules collection is copied a into newly created list: no references to it are maintained by the created object. Also, the passed coefficients are deeply cloned — copied into newly created internal arrays: no references to them are maintained by the created object.

Parameters:
itemSet - the item set, which will be processed by this class.
interactionRules - the set of interaction rules, used by this class.
deltaT - the time step Δt.
alpha - α coefficients of the Runge-Kutta algorithm.
beta - β coefficients of the Runge-Kutta algorithm.
gamma - γ coefficients of the Runge-Kutta algorithm.
alternateGamma - &gamma'; coefficients, used for error estimation.
Returns:
new instance of this class.
Throws:
java.lang.NullPointerException - if one of the arguments (including alternateGamma) is null or if one of interaction rules in the passed collection is null.
java.lang.IllegalArgumentException - if deltaT<0, or if alpha.length==0, or if alpha, beta, gamma and alternateGamma lengths are not same, or if beta[k].length<k for some k.

getRungeKutta4Integrator

public static RungeKuttaMovementIntegrator getRungeKutta4Integrator(ItemSet itemSet,
                                                                    java.util.Collection<InteractionRule> interactionRules,
                                                                    double deltaT)
Creates new instance of this class with predefined sets of coefficients αi, βi,j and γi, corresponding to the classic 4th order Runge-Kutta method.

More precisely, this method is equivalent to the getGeneralizedRungeKuttaIntegrator(ItemSet, java.util.Collection, double, double[], double[][], double[]) call with the following coefficients (s=4):

i) = (0, 1/2, 1/2, 1)
1,j) = (1/2)
2,j) = (0, 1/2)
3,j) = (0, 0, 1)
i) = (1/6, 1/3, 1/3, 1/6)

The returned object cannot estimate errors: isErrorInformationAvailable() method returns false.

Parameters:
itemSet - the item set, which will be processed by this class.
interactionRules - the set of interaction rules, used by this class.
deltaT - the time step Δt.
Returns:
new instance of this class.
Throws:
java.lang.NullPointerException - if one of the arguments is null or if one of interaction rules in the passed collection is null.
java.lang.IllegalArgumentException - if deltaT<0.

getRungeKuttaFehlberg45Integrator

public static RungeKuttaMovementIntegrator getRungeKuttaFehlberg45Integrator(ItemSet itemSet,
                                                                             java.util.Collection<InteractionRule> interactionRules,
                                                                             double deltaT)
Creates new instance of this class with predefined sets of coefficients αi, βi,j, γi and γ'i, corresponding to the classic 5th order Runge-Kutta-Fehlberg method (also known as RKF-45).

More precisely, this method is equivalent to the getGeneralizedRungeKuttaIntegrator(ItemSet, java.util.Collection, double, double[], double[][], double[], double[]) call with the following coefficients (s=6):

i) = (0, 1/4, 3/8, 12/13, 1, 1/2)
1,j) = (1/4)
2,j) = (3/32, 9/32)
3,j) = (1932/2197, −7200/2197, 7296/2197)
4,j) = (439/216, −8, 3680/513, −845/4104)
5,j) = (−8/27, 2, −3544/2565, 1859/4104, −11/40)
i) = (16/135, 0, 6656/12825, 28561/56430, −9/50, 2/55)
(γ'i) = (25/216, 0, 1408/2565, 2197/4101, −1/5, 0)

The returned object allows to estimate errors: isErrorInformationAvailable() method returns true.

Parameters:
itemSet - the item set, which will be processed by this class.
interactionRules - the set of interaction rules, used by this class.
deltaT - the time step Δt.
Returns:
new instance of this class.
Throws:
java.lang.NullPointerException - if one of the arguments is null or if one of interaction rules in the passed collection is null.
java.lang.IllegalArgumentException - if deltaT<0.

getAlpha

public double[] getAlpha()
Returns α coefficients of the Runge-Kutta algorithm. This method returns a Java array consisting of s numbers α0, α1, ..., αs−1.

The returned array is a clone of the internal array stored in this object. The returned array is never null and never has zero length.

Returns:
α coefficients of the Runge-Kutta algorithm.

getBeta

public double[][] getBeta()
Returns β coefficients of the Runge-Kutta algorithm. This method returns a Java array consisting of s Java arrays: the element #k is an array double[k], consisting of k numbers βk,0, βk,1, ..., βk,k−1. (The first element of the resulting array is always an empty array double[0].

The returned array is a deep clone of the internal array stored in this object. The returned array is never null and never has zero length.

Returns:
β coefficients of the Runge-Kutta algorithm.

getGamma

public double[] getGamma()
Returns γ coefficients of the Runge-Kutta algorithm. This method returns a Java array consisting of s numbers γ0, γ1, ..., γs−1.

The returned array is a clone of the internal array stored in this object. The returned array is never null and never has zero length.

Returns:
γ coefficients of the Runge-Kutta algorithm.

getAlternateGamma

public double[] getAlternateGamma()
Returns γ' coefficients of the Runge-Kutta algorithm or null, if this object does not use them. If the object uses them, this method returns a Java array consisting of s numbers γ'0, γ'1, ..., γ's−1.

The returned array is a clone of the internal array stored in this object. The returned array is never an empty array.

Returns:
γ' coefficients of the Runge-Kutta algorithm.

performIteration

public void performIteration()
Description copied from interface: MovementIntegrator
Performs one iteration of integration. This method sets the current time t to tt and correspondingly corrects the coordinates and velocities of all items in the processed item set, having centers and velocities and having masses, according to the motion equations. See comments to this interface for more details.

Specified by:
performIteration in interface MovementIntegrator
Specified by:
performIteration in class AbstractMovementIntegrator

isErrorInformationAvailable

public boolean isErrorInformationAvailable()
Description copied from interface: MovementIntegrator
Returns true if this implementation allows to estimate the maximal and mean error of calculating coordinates and velocities. In this case, you can use MovementIntegrator.maxLastCoordinateError(), MovementIntegrator.meanLastCoordinateError(), MovementIntegrator.maxLastVelocityError(), MovementIntegrator.meanLastVelocityError() methods after every MovementIntegrator.performIteration() call to get this information. In other case, those methods return Double.NaN.

Specified by:
isErrorInformationAvailable in interface MovementIntegrator
Overrides:
isErrorInformationAvailable in class AbstractMovementIntegrator
Returns:
whether this implementation supports estimating the maximal and mean error of calculating coordinates and velocities.

maxLastCoordinateError

public double maxLastCoordinateError()
Description copied from interface: MovementIntegrator
Returns the estimation of the maximal error of calculating coordinates while the previous MovementIntegrator.performIteration() call, if this implementation supports this feature, or Double.NaN in other case.

Specified by:
maxLastCoordinateError in interface MovementIntegrator
Overrides:
maxLastCoordinateError in class AbstractMovementIntegrator
Returns:
the estimation of the maximal error of calculating coordinates while the last integrating iteration.

maxLastVelocityError

public double maxLastVelocityError()
Description copied from interface: MovementIntegrator
Returns the estimation of the maximal error of calculating velocities while the previous MovementIntegrator.performIteration() call, if this implementation supports this feature, or Double.NaN in other case.

Specified by:
maxLastVelocityError in interface MovementIntegrator
Overrides:
maxLastVelocityError in class AbstractMovementIntegrator
Returns:
the estimation of the maximal error of calculating velocities while the last integrating iteration.

meanLastCoordinateError

public double meanLastCoordinateError()
Description copied from interface: MovementIntegrator
Returns the estimation of the average error of calculating coordinates while the previous MovementIntegrator.performIteration() call, if this implementation supports this feature, or Double.NaN in other case.

Specified by:
meanLastCoordinateError in interface MovementIntegrator
Overrides:
meanLastCoordinateError in class AbstractMovementIntegrator
Returns:
the estimation of the average error of calculating coordinates while the last integrating iteration.

meanLastVelocityError

public double meanLastVelocityError()
Description copied from interface: MovementIntegrator
Returns the estimation of the average error of calculating velocities while the previous MovementIntegrator.performIteration() call, if this implementation supports this feature, or Double.NaN in other case.

Specified by:
meanLastVelocityError in interface MovementIntegrator
Overrides:
meanLastVelocityError in class AbstractMovementIntegrator
Returns:
the estimation of the average error of calculating velocities while the last integrating iteration.

preprocess

protected void preprocess()
Description copied from class: AbstractMovementIntegrator
Performs necessary preprocessing before an iteration, in particular, reallocate all necessary work memory. This method must be called in the beginning of AbstractMovementIntegrator.performIteration() method and before any call of AbstractMovementIntegrator.calculateLeftSide(double[], double[], double[], double[], double[], double[], double) or AbstractMovementIntegrator.calculateLeftSide(double[], double[], double[], double[], double[], double[], double, int, int, int) methods, if the item set was corrected in any way after the last call of this method.

This implementation reallocates a temporary memory, used by AbstractMovementIntegrator.calculateLeftSide(double[], double[], double[], double[], double[], double[], double, int, int, int) method, and calls itemSet.preprocess(). Please don't forget to call it from all overriding implementations.

Overrides:
preprocess in class AbstractMovementIntegrator

toString

public java.lang.String toString()
Returns a brief string description of this object.

The result of this method may depend on implementation.

Overrides:
toString in class java.lang.Object
Returns:
a brief string description of this object.