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

java.lang.Object
  extended by org.gicentre.utils.network.traer.physics.AbstractForce
      extended by org.gicentre.utils.network.traer.physics.TargetedForce
          extended by 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.

Author:
Carl Pearson and minor modifications by Jo Wood.

Nested Class Summary
protected static class TwoBodyForce.ForcePair
          Class that wraps Vector3D forces to apply to the two ends of this TwoBodyForce.
 
Constructor Summary
protected TwoBodyForce(Particle oneEnd, Particle theOtherEnd)
          Creates a two-body force between the two given particles.
 
Method Summary
 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.


giCentre Utilities V.3.3, API documentation generated 6th April, 2013