Code commenting in group mechanism
Merge branch 'master' of github.com:marksutton/EvoSim
A new (and finally functional) species tracking system
--------------------------------------------------------

Species tracking is meant to be on permanently (whatever visualisation
mode we are in), and maintains an internal record of the past few time-
time. This does slow things down a bit, and it can be turned off with
the 'species tracking' item in the new species menu if you don't need
it.

Species count is output to the status bar, together with a count of
species with more than 5 and more than 50 squares, to gauge the
preponderance of very small incipient species (which are normally short-

Whether or not it's turned on in the menu, it's also turned on when
species visualisation mode is active

The algorithm it uses works something like this

1. Find top-most critter in each square (or more than one - this is
controlled by Species samps/sq in settings. E.g. setting of 5 takes top-
grids.
2. For the most common genome not yet assigned to a species, compare
with every other genome
     - if they are close (less than the breed difference setting apart),
treat as one species
     - if they close and already assigned to another species, join the
species *1
3. Repeat 2 until everything is assigned to a species
4. Connect species to those recorded from last time slice, so ID numbers
(and colours) are preserved from slice to slice. Where two species seem
to match to one parent, one (the smaller) is declared 'new'.
5. Visualisation looks at top-most genome from each square, finds which
species ID it belongs to, and colours it accordingly. Note that genome-
visualisation look at modal critter - not necessarily the same.

*1 Species joining can cause problems - very rare intermediates can
occasionally join two essentially discrete populations. To get round
this there is a 'connection sensitivity' setting called 'Species
Connect' - this reflects the ratio between population size and join size
needed to create a join, expressed as a percentage. Default value is
100, seems about right. High values (e.g. 10000) result in too many
disconnected small subspecies. Low values (e.g. 1) result in too many
false joins.

*2 Simply looking at last time-slice to work out species continuity can
cause problems - species are sometime not detected or detected
spuriously due to connection issue, so can go spuriously extinct. To
help avoid this the algorithm can match-up species from several time-
number etc. This is Timeslice connect in settings. The default is 5. The
time taken to calculate the species is directly proportional to this
value (roughly anyway).

The algorithm is not parallelised, but is quite fast. In theory
parallelisation is possible, but would be quite a bit of work for not
much gain. With 100x100 grid, 700 or so species, I get execution times
around 80-150ms. As this doesn't take place every iteration but only
every visualisation interval (default 50 iterations) it's only adding
2-3ms to each iteration - and is much faster than any alternative I have
had in the past (I think this is the 4th attempt at a species-spotting
algorithm). It CAN slow down quite a bit if species number rises into
the thousands (it's roughly proportional to species number squared I
think), but this doesn't happen with sensible setups (can happen with
high dispersal settings, whcih actually mean low disperal) - end up with
a lot of local microspecies.

Data held on each species is a unique ID number, an origination time,
the ID number of it's apparent parent, a size (number of genomes
assigned to it) and the modal genome. Size and genome are for last time-
recorded for speed. Perhaps this might include position (recorded as
center of gravity of occurences), average environment found in, average
fitness.

Finally, there is a system to log all this data to a file. If species
logging to file is on (menu item), and a csv file has been chosen, all
species are output to a file - each line is current time, ID, time of
origin, parent, current size, genome, binary genome.

BUG - at present I don't think tracking of parents works. Will try to
fix, but am running out of time!

Note that the grouping system on the report dock is pretty much obsolete
(as are most of the other reports) - at some point I may remove the
report system entirely