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 `Particle`s, 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 `Vector3D`s 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

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    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`.