org.gicentre.utils.network.traer.physics

## Class Attraction

- java.lang.Object
- - org.gicentre.utils.network.traer.physics.AbstractForce
  - - org.gicentre.utils.network.traer.physics.TargetedForce
    - - org.gicentre.utils.network.traer.physics.TwoBodyForce
      - - org.gicentre.utils.network.traer.physics.Attraction

- All Implemented Interfaces:
    Force

      public class Attraction
      extends TwoBodyForce

  This class implements TwoBodyForce to represent an inverse-square law force with a force constant and minimal distance. The minimal distance is necessary to avoid numerical instability associated with division by very small values. Providing a positive k creates an attractive force, a negative k creates a repulsive force. A typical use of attraction would be to implement planetary gravitation. The gravitational force G*m_1*m_2 / r^2 could be implemented as simply as supplying G (scaled appropriately to mass and distance units used elsewhere in the system), and an appropriate minimal separation to the scale of the problem.
  Version:
    3.4, 5th February, 2016.
  Author:
    Jeffrey Traer Bernstein, Carl Pearson and minor modifications by Jo Wood.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.gicentre.utils.network.traer.physics.TwoBodyForce

      `TwoBodyForce.ForcePair`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Attraction(Particle oneEnd, Particle theOtherEnd, float k, float distanceMin)` Creates an Attraction between oneEnd and theOtherEnd, with scale k and minimum distance distanceMin.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected TwoBodyForce.ForcePair` | `forcePair()` Implements the Attraction force calculation.
    `float` | `getMinimumDistance()` Reports the minimum separation distance above which the attraction is applied.
    `float` | `getStrength()` Reports the strength of this Attraction.
    `Attraction` | `setMinimumDistance(float d)` Sets the minimum separation distance above which the attraction is applied.
    `Attraction` | `setStrength(float k)` Sets the strength of this Attraction.

    - ### Methods inherited from class org.gicentre.utils.network.traer.physics.TwoBodyForce

      `apply, equalAndOpposite, getOneEnd, getTheOtherEnd, setOneEnd, setTheOtherEnd, specifyBoth, turnOff, turnOn, turnOn`

    - ### 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

    - #### Attraction

          public Attraction(Particle oneEnd,
                            Particle theOtherEnd,
                            float k,
                            float distanceMin)
                     throws java.lang.NullPointerException,
                            java.lang.IllegalArgumentException

      Creates an Attraction between oneEnd and theOtherEnd, with scale k and minimum distance distanceMin.
      Parameters:
        `oneEnd` - The particle at one end.
        `theOtherEnd` - The particle at the other end.
        `k` - the force scale between the two particles.
        `distanceMin` - the minimum distance between particles above which the force acts.
      Throws:
        `java.lang.NullPointerException` - if either particle is null.
        `java.lang.IllegalArgumentException` - if distanceMin is <=0.

  - ### Method Detail

    - #### getMinimumDistance

          public final float getMinimumDistance()

      Reports the minimum separation distance above which the attraction is applied.
      Returns:
        the minimum separation distance

    - #### setMinimumDistance

          public final Attraction setMinimumDistance(float d)
                                              throws java.lang.IllegalArgumentException

      Sets the minimum separation distance above which the attraction is applied.
      Parameters:
        `d` - the new minimum distance
      Returns:
        this Attraction with the new minimum distance setting.
      Throws:
        `java.lang.IllegalArgumentException` - if d<=0

    - #### setStrength

          public final Attraction setStrength(float k)

      Sets the strength of this Attraction. Positive k is an attractive force, negative k a repulsive one.
      Parameters:
        `k` - the strength of the Attraction.
      Returns:
        this Attraction with the new attractive force.

    - #### getStrength

          public final float getStrength()

      Reports the strength of this Attraction.
      Returns:
        the strength of this Attraction; positive for attractive forces, negative for repulsive forces.

    - #### forcePair

          protected TwoBodyForce.ForcePair forcePair()

      Implements the Attraction force calculation.
      Specified by:
        `forcePair` in class `TwoBodyForce`
      Returns:
        the ForcePair to act on oneEnd and theOtherEnd