NAME

flocks — boid visualisation of game theory

SYNOPSIS

flocks

[-M key=val] [-O key=val]

DESCRIPTION

The flocks utility is an OpenGL/GLUT visualisation of evolutionary game theory. It uses birds to represent game-playing individuals, with flocks representing types (strategies). For mechanics and game theory, see flocks(3). By default, flocks opens a 480p window to visualise 100 birds playing the prisoner's dilemma, with selection of a random bird and its nearest neighbour occuring twice per second. Birds are rendered from build/share/flocks/objects.zip and textures drawn from build/share/flocks/textures.zip. The default simulation uses uniform-random matching: all bird flocks will align toward a shared centre for an average of 40 seconds, at which point they'll invert the alignment for another 30 seconds, then beginning again. The camera is looking in the positive z-axis (in OpenGL, the z-axis defines depth of field). There are a number of parameters that may be set on start with the -O argument. These define the game and flight parameters. These may often be re-set during the game.

align

Sets the alignment, or the fractional displacement toward the perceived flock centre or centre of all birds. Defaults to 0.018. Must be greater than zero.

alignflock

Alignment weight toward bird's own flock. Defaults to 0. Must be greater than or equal to zero.

birdsperflock

Number of birds in each flock on each roost. Defaults to 1. Must be greater than zero.

bps

Wing-beats per second. Defaults to 3. Must be greater than or equal to zero.

cohesion

Velocity cohesion. Defaults to 0.15. Must be greater than or equal to zero.

dimensions

Space dimensions in all six directions (positive and negative x, y, and z). Defaults to 100. Must be greater than one.

ground

Fraction of space marking the ground. This is used to bound bird flight. Defaults to 0.5. Must be strictly within the unit interval.

palign

If this and palignflock are >0, the Poisson mean of time to spend with the default align value. Defaults to 40. Note: this is not symmetrical with palignflock because in the transition from flocked to non-flocked, birds are still flocked, giving that unfair weight. This will be addressed in future releases.

palignflock

If this and palign are >0, the Poisson mean of time to spend with an inverted align value. Defaults to 30.

playinterval

Interval (in seconds) at which a game is played. Defaults to 1.0. Must be greater than zero.

payoffs

Comma-separated, real-valued payoffs. These are laid out from top-left to bottom-right of the payoff matrix. Defaults to the prisoner's dilemma, 5, -10, 10, 0. There must be 4, 9, 16, or 25 values.

scattermean

If >0, the Poisson mean of time to scatter when scattering. This defaults to 4.

separation

Separation from other birds (metres). Defaults to two. Must be greater than or equal to zero.

speedmax

Maximum speed (magnitude). Defaults to 15 m/s. Must be greater than zero and the minimum speed.

speedmin

Minimum speed (magnitude). Defaults to 5 m/s. Must be greater than zero and less than the maximum speed.

tendrdest

Tendency of removed birds to the edge of the space. Defaults to 0.01. Must be greater than or equal to zero.

tendroost

Tendency of birds toward the roost. Defaults to 0.001. Must be greater than or equal to zero.

The -M flag, however, is used to set display options.

autotrack

Starts with auto-tracking enabled.

fps

If in record mode, this hard-sets the FPS. If in display mode, however, this sets the delay between frame refreshes, which, depending on the simulation complexity, may lag.

hudmini

Start with the mini-HUD enabled. This can be reset during operation.

hudlastplay

Start with the last-play HUD enabled. This can be reset during operation.

hudbig

Start with the large HUD enabled. This can be reset during operation.

lightpos

A comma-separated three-tuple specifying the light source. Defaults to 0,1000,0, 1000 metres directly overhead.

maxframes

Maximum number of frames to display before exiting. Defaults to infinite. Must be greater than zero.

maxmatches

Maximum number of matches to display before exiting. Defaults to infinite. Must be greater than zero.

noise0

A WAV file that will be continuously played throughout the simulation, with the volume conditioning upon the centre of all birds' mass, adjusted according to the inverse square distance. Note: for the time being, sounds are not encoded into -M output movie files.

objects

The filename of a ZIP file containing bird wire-frame objects. If unreadable, the birds are not rendered. The zip file must contain files bird.%d.obj, with %d numbered 0–24.

output

Output a movie to the given file. You'll need ffmpeg(1) in your PATH for this option to work properly. This will affect system performance quite a lot.

res

Specify a resolution res. May be one of 240p, 360p, 480p, 720p, 1080p, or 1440p. Defaults to 480p.

scale

Scale the bird wireframe size by scale. Defaults to 1.0.

textures

The filename of a ZIP file containing the sky-box textures. If unreadable, the space is drawn without textures. The ZIP file must consist of six textures named according to their orientation: posx.jpg, posy.jpg, posz.jpg, negx.jpg, negy.jpg, and negz.jpg.

The flocks utility responds to several different keys during recording and display mode operation:

a

Toggles auto-tracking. While auto-tracking, you will not be able to pan the camera with the arrow keys.

q

Quits the running system.

s

Causes the flocks to scatter if not already scattering.

p

Toggles the pause state. You will still be able to orient with the orientation keys. The spacebar key is also bound to this event.

h

Enable the HUD (heads-up display), which gives a read-out of system statistics. You won't be able to use the other keys til you've closed the HUD. The lower-left metrics can be changed by clicking on the values, then using the up and down keys to raise and lower the values. Use the escape key to disable the HUD.

H

Enable the mini-HUD. This is a small bar along the bottom with only the minimum facts. You can use the other keys along with the mini-HUD. Use the escape key to disable the HUD.

b

Toggle the background and bird textures. Without textures, the scene is rendered as a space with axes as the focus and birds drawn as spherical wireframse.

l

Set the light source to be in the current direction. Specifically, use the current direction and set it twice the radius of the sphere covering the cubic space.

up

Angle the camera upward.

down

Angle the camera downward.

left

Increase counterclockwise rotation.

right

Increase clockwise rotation.

FILES

Several files are useful, but not required, by flocks. These are in installed into the default data directory build/share/flocks.

objects.zip

A ZIP file consisting of bird wireframes. This may be provided to the -M objects flag.

sound.wav

A sample mono-channel WAV file consisting of bird flight noises. This may be provided to the -M noise0 flag.

textures.zip

An extremely simple “sky-box” texture set, all white. This may be provided to the -M textures flag.

EXIT STATUS

The flocks utility exits 0 on success, and >0 if an error occurs.

AUTHORS

The flocks utility was written by Kristaps Dzonsons <kristaps@kcons.eu>.