org.gicentre.utils.network.traer.physics

## Class ParticleSystem

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

-     public class ParticleSystem
      extends java.lang.Object

  Represents an entire particle system containing particles and forces between them.
  Version:
    3.4, 5th February, 2016.
  Author:
    Jeffrey Traer Bernstein, Carl Pearson and modifications by Jo Wood.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static float` | `DEFAULT_DRAG` Default drag on all particles.
    `protected static float` | `DEFAULT_GRAVITY` The default magnitude for the y-component of gravity.
    `static int` | `MODIFIED_EULER` Deprecated. Use the enum values defined in the `Integrator` class in preference to this.
    `static int` | `RUNGE_KUTTA` Deprecated. Use the enum values defined in the `Integrator` class in preference to this.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ParticleSystem()` Creates a particle system with no gravity and default drag on particles.
    `ParticleSystem(float g, float drag)` Creates a particle system with the given gravitational pull and drag.
    `ParticleSystem(float gx, float gy, float gz, float drag)` Creates a particle system with the given 3d gravitational pull and drag.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `ParticleSystem` | `addCustomForce(AbstractForce customForce)` Adds a custom force to those in this particle system.
    `protected void` | `applyForces()` Applies the forces contained in this particle system to those particles subject to them.
    `java.util.Collection<Attraction>` | `attractions()` Deprecated. Replace in favour of the more consistently named getAttractions().
    `void` | `clear()` Clears the particle system of all particles, springs, attractions and custom forces.
    `void` | `clearAllForces()` Removes all forces, springs and attractions from the particle system.
    `protected void` | `clearForces()` Removes all forces from this particle system.
    `java.util.Collection<AbstractForce>` | `customForces()` Deprecated. Replace in favour of the more consistently named getCustomForces().
    `Attraction` | `getAttraction(int i)` Provides the attraction at the given position in the collection of attractions stored in this particle system.
    `java.util.Collection<Attraction>` | `getAttractions()` Reports a collection of the attractions currently defined as part of this particle system.
    `AbstractForce` | `getCustomForce(int i)` Provides the custom force at the given position in the collection of custom forces stored in this particle system.
    `java.util.Collection<AbstractForce>` | `getCustomForces()` Provides a collection of the custom forces currently defined as part of this particle system.
    `float` | `getDeltaT()` Reports the current time step size used by this ParticleSystem's Integrator.
    `int` | `getNumAttractions()` Reports the number of attractions in this particle system.
    `int` | `getNumCustomForces()` Reports the number of custom forces in this particle system.
    `int` | `getNumParticles()` Reports the number of particles in this particle system.
    `int` | `getNumSprings()` Reports the number of springs in this particle system.
    `Particle` | `getParticle(int i)` Provides the particle at the given position in the collection of particles stored in this particle system.
    `java.util.Collection<Particle>` | `getParticles()` Provides a collection of the particles currently defined as part of this particle system.
    `Spring` | `getSpring(int i)` Provides the spring at the given position in the collection of springs stored in this particle system.
    `java.util.Collection<Spring>` | `getSprings()` Reports a collection of the springs currently defined as part of this particle system.
    `Attraction` | `makeAttraction(Particle a, Particle b, float strength, float minDistance)` Creates an attractive force between the given particles with the given strength.
    `Particle` | `makeParticle()` Creates a Particle with `Particle.DEFAULT_MASS` and position=(0,0,0).
    `Particle` | `makeParticle(float mass, float x, float y, float z)` Creates a particle in the ParticleSystem, and returns that Particle
    `Particle` | `makeParticle(Particle p)` Adds a custom Particle to the ParticleSystem, and returns the ParticleSystem.
    `Spring` | `makeSpring(Particle a, Particle b, float strength, float damping, float restLength)` Creates a spring between the given particles with the given strength, damping and reset length.
    `int` | `numberOfAttractions()` Deprecated. Replace in favour of the more consistently named getNumAttractions().
    `int` | `numberOfCustomForces()` Deprecated. Replace in favour of the more consistently named getNumCustomForces().
    `int` | `numberOfParticles()` Deprecated. Replace in favour of the more consistently named getParticles().
    `int` | `numberOfSprings()` Deprecated. Replace in favour of the more consistently named getNumSprings().
    `java.util.Collection<Particle>` | `particles()` Deprecated. Replace in favour of the more consistently named getParticles().
    `ParticleSystem` | `removeAttraction(Attraction attraction)` Removes the given attraction from the collection of attractions stored in this particle system if it exists.
    `Attraction` | `removeAttraction(int i)` Removes the attraction at the given position in the collection of attractions stored in this particle system.
    `ParticleSystem` | `removeCustomForce(AbstractForce customForce)` Removes the given custom force from the collection of custom forces stored in this particle system if it exists.
    `AbstractForce` | `removeCustomForce(int i)` Removes the custom force at the given position in the collection of custom forces stored in this particle system.
    `ParticleSystem` | `removeParticle(Particle p)` Removes the given particle from the collection of particles stored in this particle system if it exists.
    `Spring` | `removeSpring(int i)` Removes the spring at the given position in the collection of springs stored in this particle system.
    `ParticleSystem` | `removeSpring(Spring spring)` Removes the given spring from the collection of springs stored in this particle system if it exists.
    `ParticleSystem` | `setDeltaT(float t)` Sets the size of the time step used with `Integrator.step(float)` for this ParticleSystem.
    `ParticleSystem` | `setDrag(float d)` Sets the drag component that affects the particles in this system.
    `ParticleSystem` | `setGravity(float g)` Sets the gravity with 0,g,0 components.
    `ParticleSystem` | `setGravity(float x, float y, float z)` Sets the x, y, z components of the gravity vector.
    `ParticleSystem` | `setIntegrator(int integrator)` Deprecated. Consider replacing with `setIntegrator(Integrator.METHOD)`.
    `ParticleSystem` | `setIntegrator(Integrator.METHOD integrator)` Sets the integrator for this particle system based on the specified integrator name.
    `ParticleSystem` | `setIntegrator(Integrator integrator)` Sets the integrator for this particle system based on the specified integrator.
    `java.util.Collection<Spring>` | `springs()` Deprecated. Replace in favour of the more consistently named getSprings().
    `ParticleSystem` | `tick()` Advances this ParticleSystem's Integrator by the local time step.
    `ParticleSystem` | `tick(float t)` Advances this ParticleSystem's Integrator by a user-specified time step.

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

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

- - ### Field Detail

    - #### RUNGE_KUTTA

          @Deprecated
          public static final int RUNGE_KUTTA

      Deprecated. Use the enum values defined in the `Integrator` class in preference to this.
      Indicates a Runge Kutta integrator.

    - #### MODIFIED_EULER

          @Deprecated
          public static final int MODIFIED_EULER

      Deprecated. Use the enum values defined in the `Integrator` class in preference to this.
      Indicates a modified Euler integrator.

    - #### DEFAULT_DRAG

          protected static final float DEFAULT_DRAG

      Default drag on all particles.
      See Also:
        Constant Field Values

    - #### DEFAULT_GRAVITY

          protected static final float DEFAULT_GRAVITY

      The default magnitude for the y-component of gravity.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ParticleSystem

          public ParticleSystem()

      Creates a particle system with no gravity and default drag on particles. By default the system will use Runge Kutta integration to modify particles. Can be set to Euler or other integrators with `setIntegrator()`.

    - #### ParticleSystem

          public ParticleSystem(float g,
                                float drag)

      Creates a particle system with the given gravitational pull and drag. By default the system will use Runge Kutta integration to modify particles. Can be set to Euler or other integrators with `setIntegrator()`.
      Parameters:
        `g` - Gravitational parameter, applied in the 'y' direction only.
        `drag` - The drag associated with particles in this system.

    - #### ParticleSystem

          public ParticleSystem(float gx,
                                float gy,
                                float gz,
                                float drag)

      Creates a particle system with the given 3d gravitational pull and drag. By default the system will use Runge Kutta integration to modify particles. Can be set to Euler or other integrators with `setIntegrator()`.
      Parameters:
        `gx` - Gravitational parameter, applied in the 'x' direction.
        `gy` - Gravitational parameter, applied in the 'y' direction.
        `gz` - Gravitational parameter, applied in the 'z' direction.
        `drag` - The drag associated with particles in this system.

  - ### Method Detail

    - #### setDeltaT

          public final ParticleSystem setDeltaT(float t)
                                         throws java.lang.IllegalArgumentException

      Sets the size of the time step used with `Integrator.step(float)` for this ParticleSystem.
      Parameters:
        `t` - the time step size
      Returns:
        this ParticleSystem with its new time step size.
      Throws:
        `java.lang.IllegalArgumentException` - if t<=0

    - #### getDeltaT

          public final float getDeltaT()

      Reports the current time step size used by this ParticleSystem's Integrator.
      Returns:
        the time step size

    - #### tick

          public final ParticleSystem tick()

      Advances this ParticleSystem's Integrator by the local time step. Uses `tick(float)`.
      Returns:
        this ParticleSystem, post the advance.

    - #### tick

          public final ParticleSystem tick(float t)

      Advances this ParticleSystem's Integrator by a user-specified time step.
      Parameters:
        `t` - the amount of time to advance
      Returns:
        this ParticleSystem, post the advance.
      Throws:
        `java.lang.IllegalArgumentException` - if t<=0

    - #### setIntegrator

          @Deprecated
          public final ParticleSystem setIntegrator(int integrator)
                                                         throws java.lang.IllegalArgumentException

      Deprecated. Consider replacing with `setIntegrator(Integrator.METHOD)`.
      Sets the integrator for this particle system based on the specified integrator ID.
      Parameters:
        `integrator` - the ID corresponding to the desired Integrator
      Returns:
        this ParticleSystem, using the specified Integrator
      Throws:
        `java.lang.IllegalArgumentException` - if the argument does not correspond to defined Integrator

    - #### setIntegrator

          public final ParticleSystem setIntegrator(Integrator.METHOD integrator)

      Sets the integrator for this particle system based on the specified integrator name.
      Parameters:
        `integrator` - Name of integrator to be used by this particle system.
      Returns:
        this ParticleSystem, using the specified integrator.

    - #### setIntegrator

          public final ParticleSystem setIntegrator(Integrator integrator)
                                             throws java.lang.NullPointerException

      Sets the integrator for this particle system based on the specified integrator.
      Parameters:
        `integrator` - the desired integrator.
      Returns:
        this ParticleSystem, using the specified integrator.
      Throws:
        `java.lang.NullPointerException` - if integrator==null

    - #### setGravity

          public final ParticleSystem setGravity(float x,
                                                 float y,
                                                 float z)

      Sets the x, y, z components of the gravity vector.
      Parameters:
        `x` - the x component of the gravity vector.
        `y` - the y component of the gravity vector.
        `z` - the z component of the gravity vector.
      Returns:
        this ParticleSystem with its new gravity.

    - #### setGravity

          public final ParticleSystem setGravity(float g)

      Sets the gravity with 0,g,0 components.
      Parameters:
        `g` - the y component of the gravity vector.
      Returns:
        this ParticleSystem with its new gravity.

    - #### setDrag

          public final ParticleSystem setDrag(float d)

      Sets the drag component that affects the particles in this system.
      Parameters:
        `d` - the drag factor. A positive value corresponds to physical drag.
      Returns:
        this ParticleSystem with its updated drag value.

    - #### makeParticle

          public final Particle makeParticle(float mass,
                                             float x,
                                             float y,
                                             float z)

      Creates a particle in the ParticleSystem, and returns that Particle
      Parameters:
        `mass` - the new Particle mass
        `x` - the x position
        `y` - the y position
        `z` - the z position
      Returns:
        the new Particle

    - #### makeParticle

          public final Particle makeParticle()

      Creates a Particle with `Particle.DEFAULT_MASS` and position=(0,0,0).
      Returns:
        the new Particle

    - #### makeParticle

          public final Particle makeParticle(Particle p)

      Adds a custom Particle to the ParticleSystem, and returns the ParticleSystem.
      Parameters:
        `p` - the custom particle
      Returns:
        p; there are no side-effects to p
      Throws:
        `java.lang.NullPointerException` - if p==null

    - #### makeSpring

          public final Spring makeSpring(Particle a,
                                         Particle b,
                                         float strength,
                                         float damping,
                                         float restLength)
                                  throws java.lang.NullPointerException

      Creates a spring between the given particles with the given strength, damping and reset length. Strength - If they are strong they act like a stick. If they are weak they take a long time to return to their rest length. Rest Length - the spring wants to be at this length and acts on the particles to push or pull them exactly this far apart at all times. Damping - If springs have high damping they don't overshoot and they settle down quickly, with low damping springs oscillate.
      Parameters:
        `a` - First particle to be joined with the spring.
        `b` - Second particle to be joined with the spring.
        `strength` - Strength of the spring.
        `damping` - The damping component of the spring.
        `restLength` - Rest length of the spring.
      Returns:
        Spring with the given properties or null if particles a and b are identical.
      Throws:
        `java.lang.NullPointerException` - if either of the particles are null.

    - #### makeAttraction

          public final Attraction makeAttraction(Particle a,
                                                 Particle b,
                                                 float strength,
                                                 float minDistance)
                                          throws java.lang.NullPointerException

      Creates an attractive force between the given particles with the given strength. If the strength is negative the particles will repel each other, if the strength is positive they attract. The given minimum distance limits how strong this force can get close up.
      Parameters:
        `a` - First particle to be associated with the attraction.
        `b` - Second particle to be associated with the attraction.
        `strength` - Strength of the attraction, positive to bring particles together, negative to repulse.
        `minDistance` - Minimum distance below which the attraction is not applied.
      Returns:
        The new attractive force or null if particles a and b are identical.
      Throws:
        `java.lang.NullPointerException` - if either of the particles is null.

    - #### springs

          @Deprecated
          public final java.util.Collection<Spring> springs()

      Deprecated. Replace in favour of the more consistently named getSprings().
      Reports a collection of the springs currently defined as part of this particle system. While the current implementation will return the collection in insert-order, there is no guarantee that future versions will maintain a fixed order in the returned collection.
      Returns:
        Collection of springs.

    - #### getSprings

          public final java.util.Collection<Spring> getSprings()

      Reports a collection of the springs currently defined as part of this particle system. While the current implementation will return the collection in insert-order, there is no guarantee that future versions will maintain a fixed order in the returned collection.
      Returns:
        Collection of springs.

    - #### numberOfSprings

          @Deprecated
          public final int numberOfSprings()

      Deprecated. Replace in favour of the more consistently named getNumSprings().
      Reports the number of springs in this particle system.
      Returns:
        Number of springs in the system.

    - #### getNumSprings

          public final int getNumSprings()

      Reports the number of springs in this particle system.
      Returns:
        Number of springs in the system.

    - #### getSpring

          public final Spring getSpring(int i)

      Provides the spring at the given position in the collection of springs stored in this particle system.
      Parameters:
        `i` - List index (the ith spring in the collection). While the springs are stored in a fixed insert-order, this is a non-repeating set, and future reliance on set order is not encouraged.
      Returns:
        The spring requested.

    - #### removeSpring

          public final Spring removeSpring(int i)

      Removes the spring at the given position in the collection of springs stored in this particle system.
      Parameters:
        `i` - List index (the ith spring in the collection). While the springs are stored in a fixed insert-order, this is a non-repeating set, and future reliance on set order is not encouraged.
      Returns:
        The spring removed or null if the given position is out of bounds.

    - #### removeSpring

          public final ParticleSystem removeSpring(Spring spring)

      Removes the given spring from the collection of springs stored in this particle system if it exists.
      Parameters:
        `spring` - The spring to remove.
      Returns:
        The particle system updated with the removed spring.

    - #### attractions

          @Deprecated
          public final java.util.Collection<Attraction> attractions()

      Deprecated. Replace in favour of the more consistently named getAttractions().
      Reports a collection of the attractions currently defined as part of this particle system. While the current implementation will return the collection in insert-order, there is no guarantee that future versions will maintain a fixed order in the returned collection.
      Returns:
        Collection of attractions.

    - #### getAttractions

          public final java.util.Collection<Attraction> getAttractions()

      Reports a collection of the attractions currently defined as part of this particle system. While the current implementation will return the collection in insert-order, there is no guarantee that future versions will maintain a fixed order in the returned collection.
      Returns:
        Collection of attractions.

    - #### numberOfAttractions

          @Deprecated
          public final int numberOfAttractions()

      Deprecated. Replace in favour of the more consistently named getNumAttractions().
      Reports the number of attractions in this particle system.
      Returns:
        Number of attractions in the system.

    - #### getNumAttractions

          public final int getNumAttractions()

      Reports the number of attractions in this particle system.
      Returns:
        Number of attractions in the system.

    - #### getAttraction

          public final Attraction getAttraction(int i)

      Provides the attraction at the given position in the collection of attractions stored in this particle system.
      Parameters:
        `i` - List index (the ith attraction in the collection). While the attractions are stored in a fixed insert-order, this is a non-repeating set, and future reliance on set order is not encouraged.
      Returns:
        The attraction requested.

    - #### removeAttraction

          public final Attraction removeAttraction(int i)

      Removes the attraction at the given position in the collection of attractions stored in this particle system.
      Parameters:
        `i` - List index (the ith attraction in the collection). While the attractions are stored in a fixed insert-order, this is a non-repeating set, and future reliance on set order is not encouraged.
      Returns:
        The attraction removed or null if the given position is out of bounds.

    - #### removeAttraction

          public final ParticleSystem removeAttraction(Attraction attraction)

      Removes the given attraction from the collection of attractions stored in this particle system if it exists.
      Parameters:
        `attraction` - The attraction to remove.
      Returns:
        The particle system updated with the removed attraction.

    - #### customForces

          @Deprecated
          public final java.util.Collection<AbstractForce> customForces()

      Deprecated. Replace in favour of the more consistently named getCustomForces().
      Provides a collection of the custom forces currently defined as part of this particle system. While the current implementation will return the collection in insert-order, there is no guarantee that future versions will maintain a fixed order in the returned collection.
      Returns:
        Collection of custom forces.

    - #### getCustomForces

          public final java.util.Collection<AbstractForce> getCustomForces()

      Provides a collection of the custom forces currently defined as part of this particle system. While the current implementation will return the collection in insert-order, there is no guarantee that future versions will maintain a fixed order in the returned collection.
      Returns:
        Collection of custom forces.

    - #### addCustomForce

          public final ParticleSystem addCustomForce(AbstractForce customForce)

      Adds a custom force to those in this particle system.
      Parameters:
        `customForce` - Custom force to add.
      Returns:
        Particle system with the new custom force added.

    - #### numberOfCustomForces

          @Deprecated
          public final int numberOfCustomForces()

      Deprecated. Replace in favour of the more consistently named getNumCustomForces().
      Reports the number of custom forces in this particle system.
      Returns:
        Number of custom forces in the system.

    - #### getNumCustomForces

          public final int getNumCustomForces()

      Reports the number of custom forces in this particle system.
      Returns:
        Number of custom forces in the system.

    - #### getCustomForce

          public final AbstractForce getCustomForce(int i)

      Provides the custom force at the given position in the collection of custom forces stored in this particle system.
      Parameters:
        `i` - List index (the ith attraction in the collection). While the custom forces are stored in a fixed insert-order, this is a non-repeating set, and future reliance on set order is not encouraged.
      Returns:
        The custom force requested.

    - #### removeCustomForce

          public final AbstractForce removeCustomForce(int i)

      Removes the custom force at the given position in the collection of custom forces stored in this particle system.
      Parameters:
        `i` - List index (the ith attraction in the collection). While the custom forces are stored in a fixed insert-order, this is a non-repeating set, and future reliance on set order is not encouraged.
      Returns:
        The custom force removed or null if the given position is out of bounds.

    - #### removeCustomForce

          public final ParticleSystem removeCustomForce(AbstractForce customForce)

      Removes the given custom force from the collection of custom forces stored in this particle system if it exists.
      Parameters:
        `customForce` - The custom force to remove.
      Returns:
        The particle system updated with the removed custom force.

    - #### particles

          @Deprecated
          public final java.util.Collection<Particle> particles()

      Deprecated. Replace in favour of the more consistently named getParticles().
      Provides a collection of the particles currently defined as part of this particle system.
      Returns:
        Collection of particles.

    - #### getParticles

          public final java.util.Collection<Particle> getParticles()

      Provides a collection of the particles currently defined as part of this particle system.
      Returns:
        Collection of particles.

    - #### numberOfParticles

          @Deprecated
          public final int numberOfParticles()

      Deprecated. Replace in favour of the more consistently named getParticles().
      Reports the number of particles in this particle system.
      Returns:
        Number of particles in the system.

    - #### getNumParticles

          public final int getNumParticles()

      Reports the number of particles in this particle system.
      Returns:
        Number of particles in the system.

    - #### getParticle

          public final Particle getParticle(int i)

      Provides the particle at the given position in the collection of particles stored in this particle system.
      Parameters:
        `i` - List index (the ith attraction in the collection). While the particles are stored in a fixed insert-order, this is a non-repeating set, and future reliance on set order is not encouraged.
      Returns:
        The particle requested or null if position out of bounds

    - #### removeParticle

          public final ParticleSystem removeParticle(Particle p)

      Removes the given particle from the collection of particles stored in this particle system if it exists.
      Parameters:
        `p` - The particle to remove.
      Returns:
        The particle system updated with the removed particle.

    - #### clear

          public final void clear()

      Clears the particle system of all particles, springs, attractions and custom forces.

    - #### applyForces

          protected final void applyForces()

      Applies the forces contained in this particle system to those particles subject to them.

    - #### clearForces

          protected final void clearForces()

      Removes all forces from this particle system. Unlike `clearAllForces()`, this will maintain the internal collections of springs, attractions and custom forces, but these remain unattached to any particular particles.

    - #### clearAllForces

          public final void clearAllForces()

      Removes all forces, springs and attractions from the particle system.