org.gicentre.utils.network.traer.physics

## Class Spring

- 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.Spring

- All Implemented Interfaces:
    Force

      public class Spring
      extends TwoBodyForce

  Class for representing a physical spring by extending `TwoBodyForce` to calculate the force with a spring constant (`ks`), damping factor (`d`), and an ideal length (`l`). Thus, the positions of the `Particle`s on either end obey the equation:
  `ddot(r) = -k/m * (r-l) - d/m * dot(r)`
  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
    `Spring(Particle oneEnd, Particle theOtherEnd, float ks, float d, float l)` Creates a spring with the given properties between the given particles.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `float` | `currentLength()` Gets the current Spring length; uses the end particle positions to do so.
    `float` | `damping()` Reports the damping constant of the spring `d`; Will always be greater than 0.
    `TwoBodyForce.ForcePair` | `forcePair()` Calculates the spring forces on each of the particles at either end of the spring.
    `float` | `restLength()` Reports the ideal length, `l`; always more than 0.
    `Spring` | `setDamping(float d)` Sets the damping constant of the spring `d`.
    `Spring` | `setRestLength(float l)` Sets the ideal length of the spring.
    `Spring` | `setStrength(float ks)` Sets the strength of the spring `ks`; must be greater than 0.
    `float` | `strength()` Reports the strength of the spring `ks`; always more than 0.

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

    - #### Spring

          public Spring(Particle oneEnd,
                        Particle theOtherEnd,
                        float ks,
                        float d,
                        float l)
                 throws java.lang.NullPointerException,
                        java.lang.IllegalArgumentException

      Creates a spring with the given properties between the given particles.
      Parameters:
        `oneEnd` - the one end `Particle`; cannot be null
        `theOtherEnd` - the other end `Particle`; cannot be null
        `ks` - the spring constant.
        `d` - the damping constant.
        `l` - the ideal length of the spring.
      Throws:
        `java.lang.NullPointerException` - if either Particle is null, via `TwoBodyForce.TwoBodyForce(Particle, Particle)`
        `java.lang.IllegalArgumentException` - if l is not positive, via `setRestLength(float)`.
        `java.lang.IllegalArgumentException` - if ks not positive, via `setStrength(float)`.
        `java.lang.IllegalArgumentException` - if d less than 0, via `setDamping(float)`.

  - ### Method Detail

    - #### currentLength

          public final float currentLength()

      Gets the current Spring length; uses the end particle positions to do so.
      Returns:
        the current Spring length

    - #### restLength

          public final float restLength()

      Reports the ideal length, `l`; always more than 0.
      Returns:
        the ideal length of the spring.

    - #### setRestLength

          public final Spring setRestLength(float l)
                                     throws java.lang.IllegalArgumentException

      Sets the ideal length of the spring.
      Parameters:
        `l` - the new rest length; must be positive.
      Returns:
        This spring with its new rest length.
      Throws:
        `java.lang.IllegalArgumentException` - if rest length is negative

    - #### strength

          public final float strength()

      Reports the strength of the spring `ks`; always more than 0.
      Returns:
        `ks`, the spring constant

    - #### setStrength

          public final Spring setStrength(float ks)
                                   throws java.lang.IllegalArgumentException

      Sets the strength of the spring `ks`; must be greater than 0.
      Parameters:
        `ks` - the new spring constant; must be greater than 0.
      Returns:
        This spring with its new strength.
      Throws:
        `java.lang.IllegalArgumentException` - if ks is not positive.

    - #### damping

          public final float damping()

      Reports the damping constant of the spring `d`; Will always be greater than 0.
      Returns:
        `d`, the damping constant.

    - #### setDamping

          public final Spring setDamping(float d)
                                  throws java.lang.IllegalArgumentException

      Sets the damping constant of the spring `d`.
      Parameters:
        `d` - the new damping constant. Must not be negative but can be 0 for no damping.
      Returns:
        This spring with its new damping constant.
      Throws:
        `java.lang.IllegalArgumentException` - if d is negative.

    - #### forcePair

          public TwoBodyForce.ForcePair forcePair()

      Calculates the spring forces on each of the particles at either end of the spring.
      Specified by:
        `forcePair` in class `TwoBodyForce`
      Returns:
        the spring forces at each end of the spring.