org.gicentre.utils.network.traer.physics

Class TwoBodyForce

java.lang.Object

org.gicentre.utils.network.traer.physics.AbstractForce

org.gicentre.utils.network.traer.physics.TargetedForce

org.gicentre.utils.network.traer.physics.TwoBodyForce

All Implemented Interfaces:

Force

Direct Known Subclasses:

Attraction, Spring

public abstract class TwoBodyForce
extends TargetedForce

TwoBodyForce is Force between two specified Particles, which extends TargetedForce and simplifies implementation of custom Forces. A TwoBodyForce deals with all of the mechanics of getting at the two "ends" of Force and reduces the details of what a user needs to specify down to creating the force Vector3Ds that act on the ends. If the forces are of the standard equal-and-opposite variety, only the force on one end needs to be provided.

Version:

3.4, 5th February, 2016.

Author:

Carl Pearson and minor modifications by Jo Wood.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	TwoBodyForce.ForcePair Class that wraps Vector3D forces to apply to the two ends of this TwoBodyForce.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TwoBodyForce(Particle oneEnd, Particle theOtherEnd) Creates a two-body force between the two given particles.

Method Summary

Modifier and Type	Method and Description
TwoBodyForce	apply() Applies this Force to oneEnd and theOtherEnd, which modifies their Particle.force values.
protected static TwoBodyForce.ForcePair	equalAndOpposite(Vector3D forceOnOneEnd) Creates a force pair for when the forces to be applied are equal and opposite.
protected abstract TwoBodyForce.ForcePair	forcePair() Should apply the force to the pair of particles.
Particle	getOneEnd() Reports the particle at oneEnd.
Particle	getTheOtherEnd() Reports the particle at theOtherEnd.
protected TwoBodyForce	setOneEnd(Particle p) Sets oneEnd to the give particle.
protected TwoBodyForce	setTheOtherEnd(Particle p) Sets theOtherEnd to the give particle.
protected static TwoBodyForce.ForcePair	specifyBoth(Vector3D forceOnOneEnd, Vector3D forceOnTheOtherEnd) Creates a TwoBodyForce.ForcePair from two not necessarily equal and opposite forces.
TwoBodyForce	turnOff() Turns this force off.
TwoBodyForce	turnOn() Turns this force on.
TwoBodyForce	turnOn(boolean isOn) Turns this force on or off.

Methods inherited from class org.gicentre.utils.network.traer.physics.TargetedForce

apply

Methods inherited from class org.gicentre.utils.network.traer.physics.AbstractForce

isOff, isOn

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TwoBodyForce

protected TwoBodyForce(Particle oneEnd,
                       Particle theOtherEnd)
                throws java.lang.NullPointerException

Creates a two-body force between the two given particles. Turns on by default. Neither Particle is mutated by this operation, though later use of the apply() method will mutate the Particle.force vector.

Parameters:

oneEnd - the one end Particle, cannot be null

theOtherEnd - the other end Particle, cannot be null

Throws:

java.lang.NullPointerException - if either Particle is null.

Method Detail

getOneEnd

public final Particle getOneEnd()

Reports the particle at oneEnd. Mutating this Particle is permitted.

Returns:

oneEnd

getTheOtherEnd

public final Particle getTheOtherEnd()

Reports the particle at theOtherEnd. Mutating this Particle is permitted.

Returns:

theOtherEnd

apply

public TwoBodyForce apply()

Applies this Force to oneEnd and theOtherEnd, which modifies their Particle.force values. Users extending this class to create custom Forces need only implement forcePair(), taking advantage of the static packaging method equalAndOpposite(Vector3D) or specifyBoth(Vector3D, Vector3D) to create the TwoBodyForce.ForcePair.

Returns:

This two body force.

turnOff

public TwoBodyForce turnOff()

Turns this force off.

Specified by:

turnOff in interface Force

Overrides:

turnOff in class AbstractForce

Returns:

this TwoBodyForce

turnOn

public TwoBodyForce turnOn()

Turns this force on.

Specified by:

turnOn in interface Force

Overrides:

turnOn in class AbstractForce

Returns:

this TwoBodyForce

turnOn

public TwoBodyForce turnOn(boolean isOn)

Turns this force on or off.

Specified by:

turnOn in interface Force

Overrides:

turnOn in class AbstractForce

Parameters:

isOn - This force is turned on if true, otherwise it is turned off.

Returns:

this TwoBodyForce

setOneEnd

protected TwoBodyForce setOneEnd(Particle p)
                          throws java.lang.NullPointerException

Sets oneEnd to the give particle.

Parameters:

p - The particle at one end of this Force; cannot be null

Returns:

This force.

Throws:

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

setTheOtherEnd

protected TwoBodyForce setTheOtherEnd(Particle p)
                               throws java.lang.NullPointerException

Sets theOtherEnd to the give particle.

Parameters:

p - The particle at the other end of this Force; cannot be null

Returns:

This force.

Throws:

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

specifyBoth

protected static TwoBodyForce.ForcePair specifyBoth(Vector3D forceOnOneEnd,
                                                    Vector3D forceOnTheOtherEnd)
                                             throws java.lang.NullPointerException

Creates a TwoBodyForce.ForcePair from two not necessarily equal and opposite forces.

Parameters:

forceOnOneEnd - the force to be applied to oneEnd

forceOnTheOtherEnd - the force to be applied to theOtherEnd

Returns:

the appropriate ForcePair

Throws:

java.lang.NullPointerException - if either Vector3D==null

equalAndOpposite

protected static TwoBodyForce.ForcePair equalAndOpposite(Vector3D forceOnOneEnd)
                                                  throws java.lang.NullPointerException

Creates a force pair for when the forces to be applied are equal and opposite. Only the force on oneEnd needs to be specified.

Parameters:

forceOnOneEnd - the force on oneEnd

Returns:

the ForcePair

Throws:

java.lang.NullPointerException - if forceOnOneEnd is null

forcePair

protected abstract TwoBodyForce.ForcePair forcePair()

Should apply the force to the pair of particles. This is the method which must be overridden by implementing classes allowing the force to be customised. Static methods for constructing a TwoBodyForce.ForcePair are provided within this class: equalAndOpposite(Vector3D) or specifyBoth(Vector3D, Vector3D).

Returns:

a TwoBodyForce.ForcePair specifying the forces to apply to oneEnd and theOtherEnd.