Clupeoids: A fish schooling simulator based on Boids

Developed by: 
	Geir Huse (http://www.ifm.uib.no/StaffPages/huse/default.htm)
	Steve Jackson (Jackson3@Humboldt1.com)
	Steve Railsback (LRA@Northcoast.com)

	October, 2000

Clupeoids is a major modification of Eric Werk's Swarm implementation of Boids, developed as a tool for research on schooling behavior and migration in fish like herring (Clupeiadae).

MODEL NOTES:

The clupeoids follow only two rules in moving: match the velocity of the neighboring clupeoids that they detect, and move toward the centroid of the location of the other clupeoids that they detect.

Detected neighbors are the other clupeoids that are (1) within the distance defined by the parameter interactionDist, and (2) within the field of view (defined by the parameter fieldOfView). The field of view is defined as the fraction of a full circle that a clupeoid can see- for example, if fieldOfView is 0.6, then each clupeoid can detect others that are within 130 degrees either side of straight ahead. (The field of view method and code was in Eric Werk's original boids.)

An acceleration vector is calculated each time step for each clupeoid. The vector is calculated by:

a. Determining a flock centering vector: the difference between the centroid of the detected neighbors's location and the clupeoid's location. 

b. Determining a velocity matching vector: the difference between the average velocity (as a vector) of the detected neighbors and the clupeoid's velocity vector. 

c. Multiplying the flock centering and velocity matching vectors by the parameters (centeringStrength, velocityMatchStrength) that determine their relative importance.

d. Adding the two vectors together and (if necessary) limiting the magnitude of the resulting acceleration vector to the value of the parameter maxAcceleration.

e. Adding the acceleration vector to the clupeoid's current velocity vector and (if necessary) limiting the magnitude of the resulting velocity vector to the value of the parameter maxVelocity.

There are no methods active to maintain a minimum distance between clupeoids or to maintain any desired speed. There are no obstacles or predators in clupeoids.

When clupeoids reach the edge of the space, they bounce off. (Boids had an error in its toroidal space implementation that was not easily fixable.)

During a simulation, the user can send a selected number of clupeoids to a chosen location (e.g., to see how many other clupeoids follow along). When these "directed" clupeoids arrive at the chosen location they turn into circles on the display and no longer move. 

CODE NOTES:

There are a number of important code differences between Eric Werk's Boids and Clupeoids. 

1. The canvas space object was replaced with a zoom raster. The clupeoids appear as a line segment pointed in the direction of their velocity, with length proportional to velocity magnitude.

2. The movement parameters can be changed during a simulation using the probe display (this is fun!).

3. The default values of the movement parameters are in an object loader file "Boid.Params".

4. An observer swarm probe display allows the user to start taking pictures (.png snapshots of the zoom raster) at any time during a simulation.

5. The BoidSpace probe display provides access to the method (send: fishToX: Y: ) that sends a selected number of clupeoids to a designated location. This method can be used repeatedly (increasing the number of selected clupeoids each time). These directed clupeoids are taken off the top of the Swarm list object containing the clupeoids; e.g., if 20 clupeoids are sent to location (100,100), these are the first 20 objects on the model swarm's list of clupeoids.

6. Virtually all the code in Boid.m for determining where boids move has been replaced. 
