From: Rafał Długołęcki Date: Sat, 4 Apr 2015 14:27:50 +0000 (+0200) Subject: Add documentation for Algorithm, Condition and Roulette. X-Git-Url: https://git.dlugolecki.net.pl/?p=genetic.git;a=commitdiff_plain;h=58bf4fc9da0dfc4abb33bdc982214cbd2f186b44 Add documentation for Algorithm, Condition and Roulette. --- diff --git a/src/algorithm.h b/src/algorithm.h index f38fff5..fe79938 100644 --- a/src/algorithm.h +++ b/src/algorithm.h @@ -31,6 +31,9 @@ namespace genetic { /** * Fitness function used in selection + * + * It is a reference, because Fitness is purely virtual class and we + * can't have instance of it. It must be one of derived classes. */ Fitness<_Chromosome, FitnessValueType>& fitness; @@ -49,6 +52,12 @@ namespace genetic { */ Generation<_Chromosome> generation; + /** + * Method invoked in each iteration of algorithm. + * + * Applies selection, crossover and mutation on each of the chromosomes + * in generation. + */ void do_search() { _Selection selection(this->generation, fitness); this->generation = selection.draw(); @@ -56,6 +65,15 @@ namespace genetic { this->generation = mutation.mutate(this->generation); } public: + /** + * Class constructor. Initializes class with values and breeds initial + * population using passed generator::Generation. + * + * @param _generator Generator used to generate initial population + * @param _fitness Fitness class used to check fitness of the chromosome + * @param crossoverChance probability of crossover (0 = 0%, 1 = 100%) + * @param mutationChance probability of fitness (0 = 0%, 1 = 100%) + */ Algorithm( generator::Generation<_Chromosome>& _generator, Fitness<_Chromosome, FitnessValueType>& _fitness, @@ -69,6 +87,16 @@ namespace genetic { this->generation = this->generator.breed(); } + /** + * Starts Algorithm in search for result. + * For each generation but initial, condition is checked, if algorithm + * should stop. + * + * Displays separated by space: generation number, generation average + * fitness and best chromosome fitness. + * + * @param condition Condition used to check after breeding new generation + */ void searchForResult(Condition<_Chromosome>& condition) { unsigned int i = 0; cout << "generation avg best\n"; @@ -83,6 +111,10 @@ namespace genetic { } while(condition.check(this->generation) && ++i); } + /** + * Displays entire generation. + * \attention Method is currently not in use. + */ void showGeneration() { for (unsigned int i = 0; i < this->generation.get().size(); i++) { cout << "# " << i << ") "; @@ -93,6 +125,10 @@ namespace genetic { } } + /** + * Displays average fitness value of the entire generation. + * @todo make it more generic + */ void showAvgFitness() { double avg = 0; for (unsigned int i = 0; i < this->generation.get().size(); i++) { @@ -102,6 +138,11 @@ namespace genetic { cout << " " << avg / this->generation.get().size(); } + /** + * Displays best fitness value of the entire generation. + * @todo make it more generic, currently has hardcoded WSTI Fitness + * class, due its additional arguments + */ void showBestFitness() { double best = -100000; for (unsigned int i = 0; i < this->generation.get().size(); i++) { diff --git a/src/condition/condition.h b/src/condition/condition.h index 7448052..be7c798 100644 --- a/src/condition/condition.h +++ b/src/condition/condition.h @@ -17,8 +17,15 @@ namespace genetic { class Condition { public: protected: + /** + * Variable indicating current generation + */ unsigned int currentGeneration = 0; private: + /** + * Variable indicating max number of generations, after which program + * will be stopped + */ const unsigned int maxNumberOfGenerations = 1000; public: Condition() { } diff --git a/src/selection/roulette.h b/src/selection/roulette.h index 8814198..7f2d240 100644 --- a/src/selection/roulette.h +++ b/src/selection/roulette.h @@ -3,7 +3,6 @@ #include #include // std::pair -#include // std::sort #include #include #include @@ -15,12 +14,25 @@ using namespace std; namespace genetic { // namespace selection { + /** + * Selection class Roulette. + * Applies Selection on given Generation using Roulette method. + */ template < typename _Chromosome > class Roulette : public Selection<_Chromosome> { public: typedef Selection<_Chromosome> BaseType; typedef typename BaseType::FitnessValueType FitnessValueType; protected: + /** + * Method used for calculating fitness of each Chromosome in + * Generation. + * + * @param generation Generation for which fitness will be calculated + * @return vector containing fitness value of each Chromosome in + * Generation. Values are set in the same order as they are in + * the Generation. + */ vector calculateGenerationFitness( Generation<_Chromosome> generation) { vector generationFitness; @@ -31,12 +43,26 @@ namespace genetic { return generationFitness; } + + /** + * Normalizes calculated fitness values of the generation. + * + * @param generationFitness fitness values of the generation + * @param chromosomeSize number of Gene's in the Chromosome. + * + * @return multimap containing normalized Fitness as a key and its + * Chromosome as the value + */ multimap normalizeFitness( vector generationFitness, unsigned int chromosomeSize) { FitnessValueType min; FitnessValueType max; FitnessValueType offset; + + /* we use multimap because it stores multiple values with the + * same key + */ multimap normalizedFitness; min = max = generationFitness[0]; @@ -63,6 +89,10 @@ namespace genetic { /** * Spins the Roulette + * + * @param normalizedFitness multimap containing normalized Fitness + * as a key and its Chromosome as the value + * @return new Generation of Chromosome's that passed the selection */ Generation<_Chromosome> spinRoulette( multimap normalizedFitness) { @@ -124,7 +154,7 @@ namespace genetic { } /** - * Draws random + * Draws new Generation using Roulette method */ Generation<_Chromosome> do_draw() { multimap normalizedFitness; @@ -138,6 +168,13 @@ namespace genetic { } public: + /** + * Class constructor. Initializes class with values. + * + * @param _generation Generation that will be checked against this + * Selection + * @param _fitness Fitness method to calculate fitness of Chromosomes + */ Roulette(Generation<_Chromosome> _generation, genetic::Fitness<_Chromosome>& _fitness) : Selection<_Chromosome>(_generation, _fitness) { this->generation = _generation;