


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
public interface MovementIntegrator
Movement integrator: the basic tool for integrating motion equations of the physical model, described by
ItemSet
object.
This class operates with some item set
(an instance of ItemSet
) and with some list of interaction rules (instances of
InteractionRule
), which are usually passed to a constructor or an instantiation method
and cannot be changed in future, and solves the following basic task:
having coordinates of centers and velocities
— 6 numbers
x^{k}, y^{k}, z^{k},
v_{x}^{k}, v_{y}^{k}, v_{z}^{k}
per each item #k,
returned by methods of HavingCenter
and HavingVelocity
interfaces for these items.having coordinates of centers and velocities
and also having masses
,
at the moment t+Δt, according Newton's 2nd law, and to store the
new found coordinates and velocities in this item set by the corresponding methods of
HavingCenter
and HavingVelocity
interfaces.Such operation is called "iteration" and performed by performIteration()
method —
the basic method of this interface.
It is obvious that we've described the classic Cauchy problem:
dw/dt = f(t, w)
the case of the simple motion equations:
dx^{k}/dt = v_{x}^{k}
dy^{k}/dt = v_{y}^{k}
dz^{k}/dt = v_{z}^{k}
dv_{x}^{k}/dt = ∑ F_{x}^{k,j} / m^{k}
dv_{y}^{k}/dt = ∑ F_{y}^{k,j} / m^{k}
dv_{z}^{k}/dt = ∑ F_{z}^{k,j} / m^{k}
where k is an index of some item, implementing HavingVelocity
and HavingMass
,
x^{k}, y^{k}, z^{k} are coordinates ot its center (depending on
the current time t),
v_{x}^{k}, v_{y}^{k}, v_{z}^{k} are
components if its velocity (also depending on the time t), m^{k} is
its mass
and InteractionRule.calculateForce(double[] resultXYZ, Item toItem, Item byItem, double time)
method for all interaction rules, supported by this object (and specified while its creating),
where toItem argument is the item #k, byItem is the item #j
and time=t is the current time.
This package offers two classic solution of this problem: EulerMovementIntegrator
,
based on Euler algorithm, and RungeKuttaMovementIntegrator
,
based on the generalized RungeKutta algorithm.
The current time t and the time step Δt are stored by this object in some internal fields
and can be read or written at any moment by the corresponding methods.
The current time t is automatically increased by Δt by performIteration()
method,
together with correction of coordinates and velocities of items. The Δt step cannot be negative.
Usually, the motion equations are considered according Newton's 2nd law, as described in equations above. But this interface also supports the following nonstandard "pseudoNewton's" form of motion equations:
dx^{k}/dt = v_{x}^{k} = ∑ F_{x}^{k,j} / m^{k}
dy^{k}/dt = v_{y}^{k} = ∑ F_{y}^{k,j} / m^{k}
dz^{k}/dt = v_{z}^{k} = ∑ F_{z}^{k,j} / m^{k}
All implementations of this interface can work in the special mode, corresponding to these motion equations.
This mode is called "the mode of viscous forces" and can be activated at any time by
setViscousForces(boolean)
method.
This interface can perform some additional correction of the left side of motion equations listed above.
Namely, the modules of resulting derivative vectors
dx^{k}/dt = α v_{x}^{k}
dy^{k}/dt = α v_{y}^{k}
dz^{k}/dt = α v_{z}^{k}
dv_{x}^{k}/dt = β ∑ F_{x}^{k,j} / m^{k}
dv_{y}^{k}/dt = β ∑ F_{y}^{k,j} / m^{k}
dv_{z}^{k}/dt = β ∑ F_{z}^{k,j} / m^{k}
α = min(1, V_{max} / v^{k})
β = min(1, A_{max} / ∑ F^{k,j} / m^{k})
in the standard mode and
dx^{k}/dt = α ∑ F_{x}^{k,j} / m^{k}
dy^{k}/dt = α ∑ F_{y}^{k,j} / m^{k}
dz^{k}/dt = α ∑ F_{z}^{k,j} / m^{k}
α = min(1, V_{max} / ∑ F^{k,j} / m^{k})
in the mode of viscous forces. (In the formulas above, the modulus w of a vector setVelocityLimit(double)
and
setAccelerationLimit(double)
methods.
Some implementations of this interface (like
RKF45 algorithm
) allow to estimate the maximal and mean error of calculating coordinates and velocities.
Such implementations return this information via
maxLastCoordinateError()
, meanLastCoordinateError()
,
maxLastVelocityError()
, meanLastVelocityError()
methods.
In other implementations, which do not support error estimation, these methods return Double.NaN.
Sometimes, implementations of this interface can use multithreading for accelerating calculations
on multiprocessor systems. By default, all calculations are performed in a single thread,
but you can set another number of parallel threads by setNumberOfParallelTasks(int)
method —
if the object will be able to use such optimization, it will do it.
Implementations of this interface are usually not threadsafe, but are threadcompatible and can be synchronized manually if multithread access is necessary. However, there are the following guarantees (without any additional synchronization):
performIteration()
method, can lead to nonobvious behaviour of integration,
but will not corrupt the object and will not violate invariants;getCounterOfProcessedItems()
,
getCounterOfCheckedNeighbours()
, getCounterOfProcessedInteractions()
,
getCounterOfProcessedSymmetricInteractions()
, are always threadsafe and can be freely used
from different threads — but their value are correct only if performIteration()
method
is not executed at this moment.AlgART Laboratory 2010
Modifier and Type  Method and Description 

void 
copyBasicSettings(MovementIntegrator source)
Copies all basic settings, that can be accessed via getXxx/setXxx methods of this interface, from the specified object. 
double 
getAccelerationLimit()
Returns the acceleration limit A_{max}. 
long 
getCounterOfCheckedNeighbours()
Returns the internal threadsafe counter of "neighbour" item pairs ,
which were checked by performIteration() method
while calculation of the right side of the motion equations. 
long 
getCounterOfProcessedInteractions()
Returns the internal threadsafe counter of really interacted item pairs, which were really processed by performIteration() method
while calculation of the right side of the motion equations,
that is for which calculateForce method was really called
and returned true. 
long 
getCounterOfProcessedItems()
Returns the internal threadsafe counter of items, which were processed by performIteration() method
while calculation of the right side of the motion equations. 
long 
getCounterOfProcessedSymmetricInteractions()
An analog of the counter getCounterOfProcessedInteractions() , counting only pairs,
which were processed in more efficient way thanks to
symmetric interaction rules . 
double 
getDeltaT()
Returns the time step Δt for one iteration of integration. 
java.util.List<InteractionRule> 
getInteractionRules()
Returns the list of interaction rules, used by this object. 
ItemSet 
getItemSet()
Returns the item set, processed by this object. 
int 
getNumberOfParallelTasks()
Returns the current number of parallel threads, which is recommended this object to use for optimizing calculations on multiprocessor systems. 
double 
getT()
Returns the current time t in the physical model. 
double 
getVelocityLimit()
Returns the velocity limit V_{max}. 
boolean 
getViscousForces()
Returns true if this object works in the mode of viscous forces. 
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 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 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 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 performIteration() call, if this implementation
supports this feature,
or Double.NaN in other case. 
void 
performIteration()
Performs one iteration of integration. 
void 
resetCounters()
Resets to 0 all internal counters, returned by getCounterOfProcessedItems() ,
getCounterOfCheckedNeighbours() , getCounterOfProcessedInteractions()
and getCounterOfProcessedSymmetricInteractions() methods. 
void 
setAccelerationLimit(double accelerationLimit)
Sets the acceleration limit A_{max} to the given value. 
void 
setDeltaT(double deltaT)
Sets the current time Δt for one iteration of integration. 
void 
setNumberOfParallelTasks(int numberOfParallelTasks)
Sets the number of parallel threads, which should be used, if possible, for optimizing calculations on multiprocessor systems. 
void 
setT(double t)
Sets the current time t in the physical model. 
void 
setVelocityLimit(double velocityLimit)
Sets the velocity limit V_{max} to the given value. 
void 
setViscousForces(boolean viscousForces)
Sets the mode of viscous forces ("pseudoNewton's" motion equations), if the argument is true, or the usual mode (standard Newton's laws), if the argument is false See comments to this interface for more details. 
Method Detail 

ItemSet getItemSet()
ItemSet
interface.
ItemSet
object, processed by this object.java.util.List<InteractionRule> getInteractionRules()
The result is an immutable view (Collections.unmodifiableList) or a clone of the internal collection, stored by this object: you cannot modify the set of used interaction rules via the result of this method.
The elements of the returned list are never null.
int getNumberOfParallelTasks()
The returned value is always positive (>0).
void setNumberOfParallelTasks(int numberOfParallelTasks)
If this argument is 0, it is automatically replaced with
getNumberOfParallelTasks()
method will return not 0,
but the actual number of available processors.
numberOfParallelTasks
 the desired number of parallel threads for multiprocessor optimization.java.lang.IllegalArgumentException
 if the argument is negative.boolean getViscousForces()
comments to this interface
for more details.
void setViscousForces(boolean viscousForces)
comments to this interface
for more details.
viscousForces
 whether you this object should be switched in the mode of viscous forces.double getAccelerationLimit()
comments to this interface
for more details.
void setAccelerationLimit(double accelerationLimit)
comments to this interface
for more details.
accelerationLimit
 new acceleration limit A_{max}.java.lang.IllegalArgumentException
 if the argument is negative (< 0.0).double getVelocityLimit()
comments to this interface
for more details.
void setVelocityLimit(double velocityLimit)
comments to this interface
for more details.
velocityLimit
 new velocity limit V_{max}.java.lang.IllegalArgumentException
 if the argument is negative (< 0.0).double getT()
performIteration()
method.
getDeltaT()
void setT(double t)
t
 new value of the current time t.double getDeltaT()
void setDeltaT(double deltaT)
deltaT
 new value of the time step Δt.java.lang.IllegalArgumentException
 if the argument is negative (< 0.0).void copyBasicSettings(MovementIntegrator source)
setNumberOfParallelTasks
(source.getNumberOfParallelTasks()
);setViscousForces
(source.getViscousForces()
);setAccelerationLimit
(source.getAccelerationLimit()
);setVelocityLimit
(source.getVelocityLimit()
);setT
(source.getT()
);setDeltaT
(source.getDeltaT()
);
source
 another movement integrator, the basic settings of which should be copied into this one.java.lang.NullPointerException
 if the argument is null.long getCounterOfProcessedItems()
performIteration()
method
while calculation of the right side of the motion equations.
Note that performIteration()
can calculate the right side of the equations several times
(as in RungeKutta algorithms), and then every item will be also counted several times.
Usually the items, which do not have coordinates of centers and velocities
or do not have masses
, are not counted.
This counter is 0 after creating new instance of this class
and can be set to 0 by resetCounters()
method.
This method is provided for profiling and debugging needs only. It works as described above in the implementations, offered by this package, but there is no guarantee that it will return correct values in all implementations. If the implementation does not provide this counter, this method should return 0 always.
long getCounterOfCheckedNeighbours()
"neighbour" item pairs
,
which were checked by performIteration()
method
while calculation of the right side of the motion equations.
This number depends on the implementation of ItemSet
interface:
good implementations, like GridItemSet
, allow to check only restricted number of items
while finding all "neighbours" of the given item, which can interact with it.
Note that the "neighbour" pair is counted independently for both its elements. In other words, it two items act to each other, their pair is counter twice.
Note that performIteration()
can calculate the right side of the equations several times
(as in RungeKutta algorithms), and then every neighbour item pair will be also counted several times.
This counter is 0 after creating new instance of this class
and can be set to 0 by resetCounters()
method.
This method is provided for profiling and debugging needs only. It works as described above in the implementations, offered by this package, but there is no guarantee that it will return correct values in all implementations. If the implementation does not provide this counter, this method should return 0 always.
long getCounterOfProcessedInteractions()
performIteration()
method
while calculation of the right side of the motion equations,
that is for which calculateForce
method was really called
and returned true.
Note that an interacted pair is counted independently for both items. In other words, it two items act to each other, their pair is counter twice.
Note that an interacted pair is counted again for every interaction rule, applicable for this pair.
So, if there are K>1 rules, in which calculateForce
method
returned true for the given pair, then this pair will be counted K times.
Note that performIteration()
can calculate the right side of the equations several times
(as in RungeKutta algorithms), and then every neighbour item pair will be also counted several times.
This counter is 0 after creating new instance of this class
and can be set to 0 by resetCounters()
method.
This method is provided for profiling and debugging needs only. It works as described above in the implementations, offered by this package, but there is no guarantee that it will return correct values in all implementations. If the implementation does not provide this counter, this method should return 0 always.
long getCounterOfProcessedSymmetricInteractions()
getCounterOfProcessedInteractions()
, counting only pairs,
which were processed in more efficient way thanks to
symmetric interaction rules
.
Namely, some implementations of this interface can use the fact, that some interaction is symmetric
(implements SymmetricInteractionRule
), and calculate the interaction force only once.
The force F' of acting of the 2nd item to the 1st one is produced from
the force F of acting of the 1st item to the 2nd one by changing the sign:
getCounterOfProcessedInteractions()
method.
But some "neighbour" item pairs cannot be processed in such a manner, for example,
when the first item is processed (moved) by one processor in multiprocessor system
and the second one is processed by another processor.
In such situation, this counter is not increased, though the counter,
returned by getCounterOfProcessedInteractions()
method, is increased by 2
(by 1 for each from two items). So, this method can help to measure optimization,
achieved thanks to usage of symmetric interaction rules
.
This counter is 0 after creating new instance of this class
and can be set to 0 by resetCounters()
method.
This method is provided for profiling and debugging needs only. It works as described above in the implementations, offered by this package, but there is no guarantee that it will return correct values in all implementations. If the implementation does not provide this counter, this method should return 0 always.
symmetric interaction rules
.void resetCounters()
getCounterOfProcessedItems()
,
getCounterOfCheckedNeighbours()
, getCounterOfProcessedInteractions()
and getCounterOfProcessedSymmetricInteractions()
methods.
void performIteration()
having centers and velocities
and having masses
,
according to the motion equations.
See comments to this interface
for more details.
boolean isErrorInformationAvailable()
maxLastCoordinateError()
, meanLastCoordinateError()
,
maxLastVelocityError()
, meanLastVelocityError()
methods after
every performIteration()
call to get this information.
In other case, those methods return Double.NaN.
double maxLastCoordinateError()
performIteration()
call, if this implementation
supports
this feature,
or Double.NaN in other case.
double maxLastVelocityError()
performIteration()
call, if this implementation
supports
this feature,
or Double.NaN in other case.
double meanLastCoordinateError()
performIteration()
call, if this implementation
supports
this feature,
or Double.NaN in other case.
double meanLastVelocityError()
performIteration()
call, if this implementation
supports
this feature,
or Double.NaN in other case.


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 