Merge pull request #24 from MaxHalford/hall-of-fame

Hall of fame

Author: MaxHalford

README.md

@@ -266,11 +266,14 @@ Let's have a look at the GA struct.
 
 ```go
 type GA struct {
-    // Fields that are provided by the user
+    // Required fields
     NewGenome   NewGenome
     NPops        int
     PopSize      int
     Model        Model
+
+    // Optional fields
+    NBest        int
     Migrator     Migrator
     MigFrequency int
     Speciator    Speciator
@@ -279,32 +282,37 @@ type GA struct {
     RNG          *rand.Rand
     ParallelEval bool
 
-    // Fields that are generated at runtime
+    // Fields generated at runtime
     Populations        Populations
-    Best               Individual
-    CurrentBest        Individual
+    HallOfFame         Individuals
     Age                time.Duration
     Generations        int
 }
 ```
 
 You have to fill in the first set of fields, the rest are generated when calling the `GA`'s `Initialize()` method. Check out the examples in `presets.go` to get an idea of how to fill them out.
 
-- `NewGenome` is a method that returns a random genome that you defined in the previous step. gago will use this method to produce an initial population. Again, gago provides some methods for common random genome generation.
-- `NPops` determines the number of populations that will be used.
-- `PopSize` determines the number of individuals inside each population.
-- `Model` determines how to use the genetic operators you chose in order to produce better solutions, in other words it's a recipe. A dedicated section is available in the [model section](#models).
-- `Migrator` and `MigFrequency` should be provided if you want to exchange individuals between populations in case of a multi-population GA. If not the populations will be run independently. Again this is an advanced concept in the genetic algorithms field that you shouldn't deal with at first.
-- `Speciator` will split each population in distinct species at each generation. Each specie will be evolved separately from the others, after all the species has been evolved they are regrouped.
-- `Logger` is optional and provides basic population statistics, you can read more about it in the [logging section](#logging-population-statistics).
-- `Callback` is optional will execute any piece of code you wish every time `ga.Enhance()` is called. `Callback` will also be called when `ga.Initialize()` is. Using a callback can be useful for many things:
+- Required fields
+  - `NewGenome` is a method that returns a random genome that you defined in the previous step. gago will use this method to produce an initial population. Again, gago provides some methods for common random genome generation.
+  - `NPops` determines the number of populations that will be used.
+  - `PopSize` determines the number of individuals inside each population.
+  - `Model` determines how to use the genetic operators you chose in order to produce better solutions, in other words it's a recipe. A dedicated section is available in the [model section](#models).
+- Optional fields
+  - `NBest` determines how many of the best individuals encountered should be regarded in the `HallOfFame` field. This defaults to 1.
+  - `Migrator` and `MigFrequency` should be provided if you want to exchange individuals between populations in case of a multi-population GA. If not the populations will be run independently. Again this is an advanced concept in the genetic algorithms field that you shouldn't deal with at first.
+  - `Speciator` will split each population in distinct species at each generation. Each specie will be evolved separately from the others, after all the species has been evolved they are regrouped.
+  - `Logger` is optional and provides basic population statistics, you can read more about it in the [logging section](#logging-population-statistics).
+  - `Callback` is optional will execute any piece of code you wish every time `ga.Enhance()` is called. `Callback` will also be called when `ga.Initialize()` is. Using a callback can be useful for many things:
     - Calculating specific population statistics that are not provided by the logger
     - Changing parameters of the GA after a certain number of generations
     - Monitoring for converging populations
-- `RNG` can be set to make results reproducible. If it is not provided then a default `rand.New(rand.NewSource(time.Now().UnixNano()))` will be used. If you want to make your results reproducible use a constant source, e.g. `rand.New(rand.NewSource(42))`.
-- `ParallelEval` determines if a population is evaluated in parallel. The rule of thumb is to set this to `true` if your `Evaluate` method is expensive, if not it won't be worth the overhead. Refer to the [section on parallelism](#a-note-on-parallelism) for a more comprehensive explanation.
-
-Essentially, only `NewGenome`, `NPops`, `PopSize` and `Model` are required to initialize and run a GA. The other fields are optional.
+  - `RNG` can be set to make results reproducible. If it is not provided then a default `rand.New(rand.NewSource(time.Now().UnixNano()))` will be used. If you want to make your results reproducible use a constant source, e.g. `rand.New(rand.NewSource(42))`.
+  - `ParallelEval` determines if a population is evaluated in parallel. The rule of thumb is to set this to `true` if your `Evaluate` method is expensive, if not it won't be worth the overhead. Refer to the [section on parallelism](#a-note-on-parallelism) for a more comprehensive explanation.
+- Fields populated at runtime
+  - `Populations` is where all the current populations and individuals are kept.
+  - `HallOfFame` contains the `NBest` individuals ever encountered. This slice is always sorted, meaning that the first element of the slice will be the best individual ever encountered.
+  - `Age` indicates the duration the GA has spent calling the `Enhance` method.
+  - `Generations` indicates how many times the `Enhance` method has been called.
 
 
 ### Running a GA

ga.go

@@ -5,18 +5,22 @@ import (
 	"log"
 	"math"
 	"math/rand"
+	"sort"
 	"time"
 
 	"golang.org/x/sync/errgroup"
 )
 
 // A GA contains population which themselves contain individuals.
 type GA struct {
-	// Fields that are provided by the user
-	NewGenome    NewGenome    `json:"-"`
-	NPops        int          `json:"-"` // Number of Populations
-	PopSize      int          `json:"-"` // Number of Individuls per Population
-	Model        Model        `json:"-"`
+	// Required fields
+	NewGenome NewGenome `json:"-"`
+	NPops     int       `json:"-"` // Number of Populations
+	PopSize   int       `json:"-"` // Number of Individuls per Population
+	Model     Model     `json:"-"`
+
+	// Optional fields
+	NBest        int          `json:"-"` // Length of HallOfFame
 	Migrator     Migrator     `json:"-"`
 	MigFrequency int          `json:"-"` // Frequency at which migrations occur
 	Speciator    Speciator    `json:"-"`
@@ -25,12 +29,11 @@ type GA struct {
 	RNG          *rand.Rand   `json:"-"`
 	ParallelEval bool         `json:"-"`
 
-	// Fields that are generated at runtime
-	Populations Populations   `json:"pops"`
-	Best        Individual    `json:"overall_best"`
-	CurrentBest Individual    `json:"generation_best"`
-	Age         time.Duration `json:"duration"`
-	Generations int           `json:"generations"`
+	// Fields generated at runtime
+	Populations Populations   `json:"populations"`
+	HallOfFame  Individuals   `json:"hall_of_fame"` // Sorted best Individuals ever encountered
+	Age         time.Duration `json:"duration"`     // Duration during which the GA has been evolved
+	Generations int           `json:"generations"`  // Number of generations the GA has been evolved
 }
 
 // Validate the parameters of a GA to ensure it will run correctly; some
@@ -71,23 +74,25 @@ func (ga GA) Validate() error {
 	return nil
 }
 
-// Find the best current Individual in each Population and then compare the best
-// overall Individual to the current best Individual.
-func (ga *GA) findBest() {
+// Find the best current Individual in each population and then compare the best
+// overall Individual to the current best Individual. The Individuals in each
+// population are expected to be sorted.
+func updateHallOfFame(hof Individuals, indis Individuals) {
+	var k = len(hof)
 	// Start by finding the current best Individual
-	ga.CurrentBest = Individual{Fitness: math.Inf(1)}
-	for _, pop := range ga.Populations {
-		if !pop.Individuals.IsSortedByFitness() {
-			pop.Individuals.SortByFitness()
-		}
-		if pop.Individuals[0].Fitness < ga.CurrentBest.Fitness {
-			ga.CurrentBest = pop.Individuals[0].Clone(pop.rng)
+	for _, indi := range indis[:min(k, len(indis))] {
+		// Find if and where the Individual should fit in the hall of fame
+		var (
+			f = func(i int) bool { return indi.Fitness < hof[i].Fitness }
+			i = sort.Search(k, f)
+		)
+		if i < k {
+			// Shift the hall of fame to the right
+			copy(hof[i+1:], hof[i:])
+			// Insert the new Individual
+			hof[i] = indi
 		}
 	}
-	// Compare the current best Individual to the overall Individual
-	if ga.CurrentBest.Fitness < ga.Best.Fitness {
-		ga.Best = ga.CurrentBest.Clone(ga.RNG)
-	}
 }
 
 // Initialized indicates if the GA has been initialized or not.
@@ -102,26 +107,35 @@ func (ga GA) Initialized() bool {
 // individual in each population. Running Initialize after running Enhance will
 // reset the GA entirely.
 func (ga *GA) Initialize() {
+	// Check the NBest field
+	if ga.NBest < 1 {
+		ga.NBest = 1
+	}
 	// Initialize the random number generator if it hasn't been set
 	if ga.RNG == nil {
 		ga.RNG = rand.New(rand.NewSource(time.Now().UnixNano()))
 	}
 	ga.Populations = make([]Population, ga.NPops)
 	for i := range ga.Populations {
-		// Generate a population
+		// Generate a Population
 		ga.Populations[i] = newPopulation(ga.PopSize, ga.NewGenome, ga.RNG)
-		// Evaluate its individuals
+		// Evaluate its Individuals
 		ga.Populations[i].Individuals.Evaluate(ga.ParallelEval)
-		// Sort its individuals
+		// Sort it's Individuals
 		ga.Populations[i].Individuals.SortByFitness()
 		// Log current statistics if a logger has been provided
 		if ga.Logger != nil {
 			ga.Populations[i].Log(ga.Logger)
 		}
 	}
-	// Find the initial best Individual
-	ga.Best = ga.Populations[0].Individuals[0]
-	ga.findBest()
+	// Initialize HallOfFame
+	ga.HallOfFame = make(Individuals, ga.NBest)
+	for i := range ga.HallOfFame {
+		ga.HallOfFame[i] = Individual{Fitness: math.Inf(1)}
+	}
+	for _, pop := range ga.Populations {
+		updateHallOfFame(ga.HallOfFame, pop.Individuals)
+	}
 	// Execute the callback if it has been set
 	if ga.Callback != nil {
 		ga.Callback(ga)
@@ -177,13 +191,15 @@ func (ga *GA) Enhance() error {
 	if err := g.Wait(); err != nil {
 		return err
 	}
-	// Check if there is an individual that is better than the current one
-	ga.findBest()
-	ga.Age += time.Since(start)
+	// Update HallOfFame
+	for _, pop := range ga.Populations {
+		updateHallOfFame(ga.HallOfFame, pop.Individuals)
+	}
 	// Execute the callback if it has been set
 	if ga.Callback != nil {
 		ga.Callback(ga)
 	}
+	ga.Age += time.Since(start)
 	// No error
 	return nil
 }

ga_test.go

@@ -123,29 +123,57 @@ func TestRandomNumberGenerators(t *testing.T) {
 func TestBest(t *testing.T) {
 	for _, pop := range ga.Populations {
 		for _, indi := range pop.Individuals {
-			if ga.Best.Fitness > indi.Fitness {
+			if ga.HallOfFame[0].Fitness > indi.Fitness {
 				t.Error("The current best individual is not the overall best")
 			}
 		}
 	}
 }
 
-func TestFindBest(t *testing.T) {
-	// Check sure the findBest method works as expected
-	var fitness = ga.Populations[0].Individuals[0].Fitness
-	ga.Populations[0].Individuals[0].Fitness = math.Inf(-1)
-	ga.findBest()
-	if ga.Best.Fitness != math.Inf(-1) {
-		t.Error("findBest didn't work")
-	}
-	ga.Populations[0].Individuals[0].Fitness = fitness
-	// Check the best individual doesn't a share a pointer with anyone
-	fitness = ga.Best.Fitness
-	ga.Best.Fitness = 42
-	if ga.Populations[0].Individuals[0].Fitness == 42 {
-		t.Error("Best individual shares a pointer with an individual in the populations")
+func TestUpdateHallOfFame(t *testing.T) {
+	var (
+		testCases = []struct {
+			hofIn  Individuals
+			indis  Individuals
+			hofOut Individuals
+		}{
+			{
+				hofIn: Individuals{
+					Individual{Fitness: math.Inf(1)},
+				},
+				indis: Individuals{
+					Individual{Fitness: 0},
+				},
+				hofOut: Individuals{
+					Individual{Fitness: 0},
+				},
+			},
+			{
+				hofIn: Individuals{
+					Individual{Fitness: 0},
+					Individual{Fitness: math.Inf(1)},
+				},
+				indis: Individuals{
+					Individual{Fitness: 1},
+				},
+				hofOut: Individuals{
+					Individual{Fitness: 0},
+					Individual{Fitness: 1},
+				},
+			},
+		}
+	)
+	for i, tc := range testCases {
+		t.Run(fmt.Sprintf("TC %d", i), func(t *testing.T) {
+			updateHallOfFame(tc.hofIn, tc.indis)
+			// Compare the obtained hall of fame to the expected one)
+			for i, indi := range tc.hofIn {
+				if indi.Fitness != tc.hofOut[i].Fitness {
+					t.Errorf("Expected %v, got %v", tc.hofOut[i], indi)
+				}
+			}
+		})
 	}
-	ga.Best.Fitness = fitness
 }
 
 // TestDuration verifies the sum of the duration of each population is higher
@@ -329,8 +357,8 @@ func TestGAConsistentResults(t *testing.T) {
 	}
 
 	// Compare best individuals
-	if ga1.Best.Fitness != ga2.Best.Fitness {
-		t.Errorf("Expected %f, got %f", ga1.Best.Fitness, ga2.Best.Fitness)
+	if ga1.HallOfFame[0].Fitness != ga2.HallOfFame[0].Fitness {
+		t.Errorf("Expected %f, got %f", ga1.HallOfFame[0].Fitness, ga2.HallOfFame[0].Fitness)
 	}
 
 }