org.gicentre.utils.network.traer.physics

## Class Particle

- java.lang.Object
- - org.gicentre.utils.network.traer.physics.Particle

- All Implemented Interfaces:
    Locatable
  Direct Known Subclasses:
    ChargedParticle

      public class Particle
      extends java.lang.Object
      implements Locatable

  Class for representing a Particle. It contains the Particle's position, velocity, and the force on the Particle. The particle also has a mass, and a fixed vs free state.
  Version:
    3.4, 5th February, 2016.
  Author:
    Jeffrey Traer Bernstein, Carl Pearson and minor modifications by Jo Wood.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected float` | `age` The age of the particle.
    `static float` | `DEFAULT_MASS` The default mass for the no-argument constructor.
    `protected boolean` | `isDead` Whether or not this particle is dead (not attached to any forces or springs).
    `protected boolean` | `isFixed` Whether or not this Particle is fixed.
    `protected Vector3D` | `position` The position of the particle in 3d space.
    `protected Vector3D` | `velocity` The 3d velocity of the particle.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Particle()` Creates a particle with the default mass determined by `DEFAULT_MASS`.
    `Particle(float m)` Creates a particle with a given mass.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `Particle` | `addForce(Vector3D addedForce)` Updates the force on this particle by adding the given extra force.
    `float` | `age()` Reports the age of this particle.
    `Particle` | `clearForce()` Clears the force on this particle.
    `float` | `distanceTo(Particle p)` Calculates the distance between this particle and another.
    `Vector3D` | `force()` Deprecated. Calls to this method should replaced with calls to the more standard `getForce()`.
    `Vector3D` | `getForce()` Reports the force currently applied to this particle.
    `processing.core.PVector` | `getLocation()` Reports the location of this particle.
    `boolean` | `isFixed()` Reports whether or not this particle is fixed.
    `boolean` | `isFree()` Reports whether or not this particle is free.
    `Particle` | `makeFixed()` Fixes the particle.
    `Particle` | `makeFree()` Frees this particle.
    `float` | `mass()` Reports the particle's mass.
    `Vector3D` | `position()` Reports the position of the particle.
    `Particle` | `reset()` Resets this particle by setting its age to 0, dead=false, clears the position, velocity, force Vector3Ds, and mass = DEFAULT_MASS.
    `Particle` | `setFixed(boolean isFixed)` Sets the particle's fixed/free state.
    `Particle` | `setMass(float m)` Sets the particle's mass to the given value.
    `Vector3D` | `velocity()` Reports the velocity of the particle.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### DEFAULT_MASS

          public static final float DEFAULT_MASS

      The default mass for the no-argument constructor.
      See Also:
        Constant Field Values

    - #### isFixed

          protected boolean isFixed

      Whether or not this Particle is fixed.

    - #### position

          protected Vector3D position

      The position of the particle in 3d space. It is automatically allocated to 0,0,0 on creation

    - #### velocity

          protected Vector3D velocity

      The 3d velocity of the particle. It is automatically allocated to 0,0,0 on creation.

    - #### age

          protected float age

      The age of the particle.

    - #### isDead

          protected boolean isDead

      Whether or not this particle is dead (not attached to any forces or springs).

  - ### Constructor Detail

    - #### Particle

          public Particle()

      Creates a particle with the default mass determined by `DEFAULT_MASS`.

    - #### Particle

          public Particle(float m)
                   throws java.lang.IllegalArgumentException

      Creates a particle with a given mass.
      Parameters:
        `m` - the desired mass which must be greater than 0.
      Throws:
        `java.lang.IllegalArgumentException` - via `setMass(float)` if mass is negative or zero.

  - ### Method Detail

    - #### distanceTo

          public final float distanceTo(Particle p)
                                 throws java.lang.NullPointerException

      Calculates the distance between this particle and another.
      Parameters:
        `p` - the other particle
      Returns:
        the distance between the two particles
      Throws:
        `java.lang.NullPointerException` - if p == null

    - #### makeFixed

          public final Particle makeFixed()

      Fixes the particle. That is, it is not subject to forces that may affect its movement.
      Returns:
        this Particle with its new fixed state.

    - #### makeFree

          public final Particle makeFree()

      Frees this particle. That is, it becomes subject to forces in relation to other particles that may affect its movement.
      Returns:
        this particle with is new free state.

    - #### setFixed

          public final Particle setFixed(boolean isFixed)

      Sets the particle's fixed/free state. Has the side-effect of clearing the velocity if fixed==true.
      Parameters:
        `isFixed` - the new fixed/free state, fixed if true, free if false.
      Returns:
        this particle with its new fixed/free state.

    - #### isFixed

          public final boolean isFixed()

      Reports whether or not this particle is fixed.
      Returns:
        the fixed/free state of the particle.

    - #### isFree

          public final boolean isFree()

      Reports whether or not this particle is free. This cqn be seen as a convenience method since it always returns !isFixed().
      Returns:
        the free/fixed state of the particle.

    - #### position

          public final Vector3D position()

      Reports the position of the particle.
      Returns:
        Position of this particle.

    - #### getLocation

          public processing.core.PVector getLocation()

      Reports the location of this particle.
      Specified by:
        `getLocation` in interface `Locatable`
      Returns:
        Location represented of this particle.

    - #### velocity

          public final Vector3D velocity()

      Reports the velocity of the particle.
      Returns:
        Velocity of this particle in 3d coordinates.

    - #### mass

          public final float mass()

      Reports the particle's mass.
      Returns:
        Mass of the particle, which is always greater than 0.

    - #### setMass

          public final Particle setMass(float m)

      Sets the particle's mass to the given value.
      Parameters:
        `m` - the new mass which must be greater than 0.
      Returns:
        this Particle with its new mass.
      Throws:
        `java.lang.IllegalArgumentException` - if its mass is set to less than 0.

    - #### force

          @Deprecated
          public final Vector3D force()

      Deprecated. Calls to this method should replaced with calls to the more standard `getForce()`.
      Reports the force currently applied to the particle. Using this to clear the force is deprecated; use `clearForce()` instead. Using this to add force is deprecated; use `addForce(Vector3D)` instead.
      Returns:
        the force on the Particle

    - #### getForce

          public final Vector3D getForce()

      Reports the force currently applied to this particle.
      Returns:
        the force on the Particle

    - #### addForce

          public final Particle addForce(Vector3D addedForce)

      Updates the force on this particle by adding the given extra force.
      Parameters:
        `addedForce` - The force to add to the current particle force
      Returns:
        this Particle with its new combined force.
      Throws:
        `java.lang.NullPointerException` - via `Vector3D.add(Vector3D)` if added==null

    - #### clearForce

          public final Particle clearForce()

      Clears the force on this particle.
      Returns:
        this particle with its new 0 force.

    - #### age

          public final float age()

      Reports the age of this particle.
      Returns:
        the current Particle age.

    - #### reset

          public Particle reset()

      Resets this particle by setting its age to 0, dead=false, clears the position, velocity, force Vector3Ds, and mass = DEFAULT_MASS.
      Returns:
        the particle in its new reset state.