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:

4.1, 16th August, 2012.

Author:

Jeffrey Traer Bernstein, Carl Pearson and modifications by Jo Wood.

Field Summary

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

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

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

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

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

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

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

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

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

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

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

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

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.