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

```java.lang.Object
net.algart.model3d.common.movement.model.AbstractMovementIntegrator
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.