RungeKuttaMovementIntegrator

Overview

Package

Class

Tree

Deprecated

Index

Help

About this library (home page)

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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 t_n be described by the vector w_n, and we want to find the coordinates and velocities w_n+1 at the next moment t_n+1=t_n+Δt — see comments to MovementIntegrator. This class uses the following formulas:

w_n+1 = w_n + γ₀k₀ + γ₁k₁ + ... + γ_s−1k_s−1
k₀ = Δt f(t_n + α₀Δt, w_n)
k₁ = Δt f(t_n + α₁Δt, w_n + β_1,0k₀)
k₂ = Δt f(t_n + α₂Δt, w_n + β_2,0k₀ + β_2,1k₁)
. . .
k_s−1 = Δt f(t_n + α_s−1Δt, w_n + β_s−1,0k₀ + β_s−1,1k₁ + ... + β_s−1,s−2k_s−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(t_n, w_n) 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, γ₀=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 = w_n + γ'₀k₀ + γ'₁k₁ + ... + γ'_s−1k_s−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 w_n+1. (The w'_n+1 vector is used for this estimation only; the new coordinates and velocities at the next moment will be w_n+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 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)
(β_1,j) = (¹/₂)
(β_2,j) = (0, ¹/₂)
(β_3,j) = (0, 0, 1)
(γ_i) = (¹/₆, ¹/₃, ¹/₃, ¹/₆)

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, ¹/₂)
(β_1,j) = (¹/₄)
(β_2,j) = (³/₃₂, ⁹/₃₂)
(β_3,j) = (¹⁹³²/₂₁₉₇, −⁷²⁰⁰/₂₁₉₇, ⁷²⁹⁶/₂₁₉₇)
(β_4,j) = (⁴³⁹/₂₁₆, −8, ³⁶⁸⁰/₅₁₃, −⁸⁴⁵/₄₁₀₄)
(β_5,j) = (−⁸/₂₇, 2, −³⁵⁴⁴/₂₅₆₅, ¹⁸⁵⁹/₄₁₀₄, −¹¹/₄₀)
(γ_i) = (¹⁶/₁₃₅, 0, ⁶⁶⁵⁶/₁₂₈₂₅, ²⁸⁵⁶¹/₅₆₄₃₀, −⁹/₅₀, ²/₅₅)
(γ'_i) = (²⁵/₂₁₆, 0, ¹⁴⁰⁸/₂₅₆₅, ²¹⁹⁷/₄₁₀₁, −¹/₅, 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 α₀, α₁, ..., α_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 γ₀, γ₁, ..., γ_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 γ'₀, γ'₁, ..., γ'_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.