net.algart.model3d.common.movement.model
Interface MovementIntegrator

All Known Implementing Classes:

AbstractMovementIntegrator, EulerMovementIntegrator, MovementIntegratorWrapper, RungeKuttaMovementIntegrator

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:

• At the current time moment t, we know the current coordinates and velocities of all items from the given set, 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.
• We know that some items interact, according to the given set of interaction rules, and, therefore, we can calculate the summary force F^k_sum = ∑ F^k,j, acting to each item #k (which has a center and a velocity) from the side of all other items #j, interacting with it.
• Then, we need to find the estimated coordinates and velocities of all 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 F^k,j = (F_x^k,j, F_y^k,j, F_z^k,j) is the force of interaction between the item #k and any other item #j — the sum of results of 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 Runge-Kutta 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 non-standard "pseudo-Newton'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 dr^k/dt = (dx^k/dt, dy^k/dt, dz^k/dt) and dv^k/dt = (dv_x^k/dt, dv_y^k/dt, dv_z^k/dt) are compared with the velocity limit V_max and the acceleration limit A_max, and if the modules are greater than the limits, these vectors are reduced to be equal (by modulus) to these limits. Formally, it means that the real form of motion equations, integrated by this interface, is:

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 w = w_x, w_y, w_z) is |w| = (w_x²+w_y²+w_z²)^½.) Such correction helps to reduce unwanted results of possible instability — the typical problem of integrating Cauchy problem for motion equations. By default, both limits V_max and A_max are infinite (Double.POSITIVE_INFINITY), so they do not affect the equations; but you can set them to another values by setVelocityLimit(double) and setAccelerationLimit(double) methods.

Some implementations of this interface (like RKF-45 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 thread-safe, but are thread-compatible and can be synchronized manually if multithread access is necessary. However, there are the following guarantees (without any additional synchronization):

• the current time t, the time step Δt, the velocity and acceleration limits V_max and A_max and the viscous forces mode are read and written by the corresponding methods atomically, as volatile fields (and they really should be implemented as volatile fields of the implementation class) — so, modification of these parameters from a parallel thread, during executing performIteration() method, can lead to non-obvious behaviour of integration, but will not corrupt the object and will not violate invariants;
• the counters, returned by methods getCounterOfProcessedItems(), getCounterOfCheckedNeighbours(), getCounterOfProcessedInteractions(), getCounterOfProcessedSymmetricInteractions(), are always thread-safe 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

Since:

JDK 1.5

Version:

1.0

Author:

Daniel Alievsky

getItemSet

ItemSet getItemSet()

Returns the item set, processed by this object. Usually it is set while instantiation and cannot be changed in future. But you can change this item set by methods of ItemSet interface.

Returns:

the reference to ItemSet object, processed by this object.

getInteractionRules

java.util.List<InteractionRule> getInteractionRules()

Returns the list of interaction rules, used by this object. Usually it is set while instantiation and cannot be changed in future.

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.

Returns:

the list of interaction rules, used by this object.

getNumberOfParallelTasks

int getNumberOfParallelTasks()

Returns the current number of parallel threads, which is recommended this object to use for optimizing calculations on multiprocessor systems.

The returned value is always positive (>0).

Returns:

the current number of parallel threads for multiprocessor optimization.

setNumberOfParallelTasks

void setNumberOfParallelTasks(int numberOfParallelTasks)

Sets the number of parallel threads, which should be used, if possible, for optimizing calculations on multiprocessor systems. This value should not be greater than the number of available processors or processor kernels.

If this argument is 0, it is automatically replaced with Runtime.getRuntime().availableProcessors(): the number of available processors. Note that in this case getNumberOfParallelTasks() method will return not 0, but the actual number of available processors.

Parameters:

numberOfParallelTasks - the desired number of parallel threads for multiprocessor optimization.

Throws:

java.lang.IllegalArgumentException - if the argument is negative.

getViscousForces

boolean getViscousForces()

Returns true if this object works in the mode of viscous forces. See comments to this interface for more details.

Returns:

whether this object works in the mode of viscous forces.

setViscousForces

void setViscousForces(boolean viscousForces)

Sets the mode of viscous forces ("pseudo-Newton'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.

Parameters:

viscousForces - whether you this object should be switched in the mode of viscous forces.

getAccelerationLimit

double getAccelerationLimit()

Returns the acceleration limit A_max. It can be Double.POSITIVE_INFINITY: it means that the accelerations are not limited. See comments to this interface for more details.

Returns:

the acceleration limit A_max.

setAccelerationLimit

void setAccelerationLimit(double accelerationLimit)

Sets the acceleration limit A_max to the given value. You can pass Double.POSITIVE_INFINITY: it means that the accelerations will be not limited. See comments to this interface for more details.

Parameters:

accelerationLimit - new acceleration limit A_max.

Throws:

java.lang.IllegalArgumentException - if the argument is negative (< 0.0).

getVelocityLimit

double getVelocityLimit()

Returns the velocity limit V_max. It can be Double.POSITIVE_INFINITY: it means that the velocities are not limited. See comments to this interface for more details.

Returns:

the velocity limit A_max.

setVelocityLimit

void setVelocityLimit(double velocityLimit)

Sets the velocity limit V_max to the given value. You can pass Double.POSITIVE_INFINITY: it means that the velocities will be not limited. See comments to this interface for more details.

Parameters:

velocityLimit - new velocity limit V_max.

Throws:

java.lang.IllegalArgumentException - if the argument is negative (< 0.0).

getT

double getT()

Returns the current time t in the physical model. It is usually 0.0 after creating new object and automatically updated (increased by Δt) by performIteration() method.

Returns:

the current time t.

See Also:

getDeltaT()

setT

void setT(double t)

Sets the current time t in the physical model.

Parameters:

t - new value of the current time t.

getDeltaT

double getDeltaT()

Returns the time step Δt for one iteration of integration. It is usually specified while instantiating new object. It cannot be negative.

Returns:

the time step Δt.

setDeltaT

void setDeltaT(double deltaT)

Sets the current time Δt for one iteration of integration.

Parameters:

deltaT - new value of the time step Δt.

Throws:

java.lang.IllegalArgumentException - if the argument is negative (< 0.0).

copyBasicSettings

void copyBasicSettings(MovementIntegrator source)

Copies all basic settings, that can be accessed via getXxx/setXxx methods of this interface, from the specified object. In other words, this method is equivalent to the following calls:

 setNumberOfParallelTasks(source.getNumberOfParallelTasks());
 setViscousForces(source.getViscousForces());
 setAccelerationLimit(source.getAccelerationLimit());
 setVelocityLimit(source.getVelocityLimit());
 setT(source.getT());
 setDeltaT(source.getDeltaT());
 

Parameters:

source - another movement integrator, the basic settings of which should be copied into this one.

Throws:

java.lang.NullPointerException - if the argument is null.

getCounterOfProcessedItems

long getCounterOfProcessedItems()

Returns the internal thread-safe counter of items, which were processed by 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 Runge-Kutta 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.

Returns:

the counter of processed items.

getCounterOfCheckedNeighbours

long getCounterOfCheckedNeighbours()

Returns the internal thread-safe counter of "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 Runge-Kutta 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.

Returns:

the counter of processed "neighbour" item pairs.

getCounterOfProcessedInteractions

long getCounterOfProcessedInteractions()

Returns the internal thread-safe 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.

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 Runge-Kutta 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.

Returns:

the counter of processed really interacted item pairs.

getCounterOfProcessedSymmetricInteractions

long getCounterOfProcessedSymmetricInteractions()

An analog of the counter 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: F'=−F. In this case, the counter, returned by this method, is increased by 2 for each such interaction rule, as well as the counter, returned by 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.

Returns:

the counter of processed really interacted item pairs, for which the interaction force was not calculated twice, because of using symmetric interaction rules.

resetCounters

void resetCounters()

Resets to 0 all internal counters, returned by getCounterOfProcessedItems(), getCounterOfCheckedNeighbours(), getCounterOfProcessedInteractions() and getCounterOfProcessedSymmetricInteractions() methods.

performIteration

void performIteration()

Performs one iteration of integration. This method sets the current time t to t+Δt 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.

isErrorInformationAvailable

boolean isErrorInformationAvailable()

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

Returns:

whether this implementation supports estimating the maximal and mean error of calculating coordinates and velocities.

maxLastCoordinateError

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.

Returns:

the estimation of the maximal error of calculating coordinates while the last integrating iteration.

maxLastVelocityError

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.

Returns:

the estimation of the maximal error of calculating velocities while the last integrating iteration.

meanLastCoordinateError

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.

Returns:

the estimation of the average error of calculating coordinates while the last integrating iteration.

meanLastVelocityError

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.

Returns:

the estimation of the average error of calculating velocities while the last integrating iteration.