From 1bef1f38888f19f83083d2f5bc1e1a90bb14291f Mon Sep 17 00:00:00 2001 From: =?utf8?q?Rafa=C5=82=20D=C5=82ugo=C5=82=C4=99cki?= Date: Sat, 4 Apr 2015 21:00:37 +0200 Subject: [PATCH] Improve comments and documentation. --- src/algorithm.h | 3 +++ src/chromosome.h | 19 +++++++++++++++- src/crossover/crossover.h | 29 +++++++++++++++++++++++++ src/fitness/example.h | 18 ++++++++++------ src/fitness/fitness.h | 31 +++++++++++++++++++++++---- src/fitness/wsti.h | 30 ++++++++++++++++++++++++++ src/gene.h | 22 ++++++++++++++++++- src/generation.h | 22 ++++++++++++++++++- src/generator/generation.h | 4 ++-- src/mutation/mutation.h | 25 ++++++++++++++++++++++ src/selection/roulette.h | 11 +++++++++- src/selection/selection.h | 44 +++++++++++++++++++++++++++++++++++++- 12 files changed, 241 insertions(+), 17 deletions(-) diff --git a/src/algorithm.h b/src/algorithm.h index fe79938..894f488 100644 --- a/src/algorithm.h +++ b/src/algorithm.h @@ -22,6 +22,9 @@ namespace genetic { template < typename _Chromosome, typename _Selection, typename _Crossover, typename _Mutation > class Algorithm { public: + /** + * Type representing Fitness value + */ typedef typename _Selection::FitnessValueType FitnessValueType; protected: /** diff --git a/src/chromosome.h b/src/chromosome.h index e197f16..7399ea4 100644 --- a/src/chromosome.h +++ b/src/chromosome.h @@ -14,6 +14,9 @@ namespace genetic { template < typename _Gene > class Chromosome { public: + /** + * Type representing Chromosome Gene + */ typedef _Gene GeneType; protected: /** @@ -27,6 +30,11 @@ namespace genetic { */ Chromosome() {} + /** + * Class constructor. Initializes Chromosome with the given Gene's + * + * @param genes vector containing Genes to use in Chromosome + */ Chromosome(vector<_Gene> genes) { this->genes = genes; } @@ -36,11 +44,20 @@ namespace genetic { : genes(chromosome.get()) { } - Chromosome& operator=(const Chromosome& chromosome){ + /** + * Copy operator. + * + * @param chromosome Chromosome from which the Genes should be copied. + * @return Chromosome instance containing copied Genes + */ + Chromosome& operator=(const Chromosome& chromosome) { this->genes = chromosome.get(); return *this; } + /** + * Allows read-only access to Chromosome Genes + */ vector<_Gene> get() const { return this->genes; } diff --git a/src/crossover/crossover.h b/src/crossover/crossover.h index f494b7b..0d9b309 100644 --- a/src/crossover/crossover.h +++ b/src/crossover/crossover.h @@ -11,11 +11,29 @@ namespace genetic { template < typename _Chromosome > class Crossover { public: + /** + * Type of probability of crossover chance + */ typedef double CrossoverChanceType; + + /** + * Type representing Chromosome Gene + */ typedef typename _Chromosome::GeneType GeneType; protected: + /** + * Probability of Crossover (0 = 0%, 1 = 100%) + */ CrossoverChanceType chance; + /** + * Crossover two Chromosome's between themself. + * + * @param first first Chromosome to Crossover + * @param second second Chromosome to Crossover + * @param splitPlace Gene number on which the Genes should be swapped + * @return new Chromosome crossed between given two + */ _Chromosome do_cross(_Chromosome first, _Chromosome second, unsigned int splitPlace) { const unsigned int chromosomeSize = first.get().size(); @@ -57,10 +75,21 @@ namespace genetic { } public: + /** + * Class constructor. Initializes values. + * + * @param chance probability of Crossover (0 = 0%, 1 = 100%) + */ Crossover(CrossoverChanceType chance) : chance(chance) { } + /** + * Invokes Crossover calculations + * + * @param _generation Generation for which the crossover should be applied + * @return new Generation of Chromosome's after the Crossover + */ Generation<_Chromosome> cross(Generation<_Chromosome> _generation) { const unsigned int generationSize = _generation.get().size(); vector<_Chromosome> newGeneration; diff --git a/src/fitness/example.h b/src/fitness/example.h index 46d8907..522b9d3 100644 --- a/src/fitness/example.h +++ b/src/fitness/example.h @@ -11,17 +11,23 @@ namespace genetic { /** * Just an example Fitness function. */ - template < typename _Chromosome > - class FitnessExample { + template + class FitnessExample : public Fitness<_Chromosome, _Value> { protected: - _Chromosome chromosome; + /* + * Chromosome is inherited so you don't have to declare usage of one + */ + /* _Chromosome chromosome; */ public: + /** + * Example class constructor + */ FitnessExample(_Chromosome& _chromosome) - : chromosome(_chromosome.get()) { + : Fitness<_Chromosome>(_chromosome) { } - /* - * Some calculations here... + /** + * Some calculations should be passed here... */ double calculate() { return 0; diff --git a/src/fitness/fitness.h b/src/fitness/fitness.h index 14b6487..66263f1 100644 --- a/src/fitness/fitness.h +++ b/src/fitness/fitness.h @@ -1,7 +1,7 @@ #ifndef __FITNESS_FITNESS_H #define __FITNESS_FITNESS_H -#include "../chromosome.h" +#include "chromosome.h" namespace genetic { /** @@ -10,25 +10,48 @@ namespace genetic { */ template < typename _Chromosome, typename _Value = double > class Fitness { - template friend class Selection ; + template friend class Selection; public: + /** + * Type representing Chromosome Gene + */ typedef typename _Chromosome::GeneType GeneType; + + /** + * Value type returned by the Fitness function + */ typedef _Value ValueType; protected: + /** + * Chromosome on which calculations are made + */ _Chromosome chromosome; - /* - * Some calculations here... + /** + * Calculations should be done here... + * + * @return Fitness value of the current Chromosome */ virtual _Value do_calculate() = 0; public: + /** + * Class constructor + */ Fitness() {} + /** + * Copy constructor + */ Fitness(_Chromosome& _chromosome) : chromosome(_chromosome.get()) { } + /** + * Invokes calculations + * + * @return Fitness value of the current Chromosome + */ _Value calculate() { return this->do_calculate(); } diff --git a/src/fitness/wsti.h b/src/fitness/wsti.h index eaa0538..d99dd18 100644 --- a/src/fitness/wsti.h +++ b/src/fitness/wsti.h @@ -16,9 +16,19 @@ namespace genetic { template class WSTI : public Fitness<_Chromosome, _Value> { protected: + /** + * Value of the begining of the Fitness function domain + */ float span_start; + + /** + * Value of the end of the Fitness function domain + */ float span_end; + /** + * Calculates fenotype of the current Chromosome + */ _Value fenotype() { int _fenotype = 0; int ratio = 1; @@ -30,19 +40,39 @@ namespace genetic { return _fenotype; } + /** + * Calculates fenotype of the current Chromosome + */ _Value calculateFenotype() { const unsigned int power2N = 1 << this->chromosome.get().size(); return span_start + (span_end - span_start) * this->fenotype() / power2N; } + /** + * Calculates fitness value of the current Chromosome + */ _Value do_calculate() { _Value fenotype = this->calculateFenotype(); return (exp(fenotype) * sin(3.1415 * fenotype) + 1) / fenotype; } public: + /** + * Class constructor. Initializes class with requied values. + * + * @param start begining of the Fitness function domain + * @param end end of the Fitness function domain + */ WSTI(float start, float end) : span_start(start), span_end(end) { } + + /** + * Class constructor. Initializes class with requied values. + * + * @param _chromosome Chromosome, for which value will be calculated + * @param start begining of the Fitness function domain + * @param end end of the Fitness function domain + */ WSTI(_Chromosome& _chromosome, float start, float end) : Fitness<_Chromosome>(_chromosome), span_start(start), span_end(end) { } diff --git a/src/gene.h b/src/gene.h index e414281..f3b3c55 100644 --- a/src/gene.h +++ b/src/gene.h @@ -4,15 +4,26 @@ namespace genetic { /** - * Gene. + * Class representing Gene */ template < typename Type > class Gene { protected: + /** + * Value of the Gene + * This for example can be a primitive value such as: int or double, or + * with additional changes complex struct. + */ Type value; public: + /** + * Default constructor + */ Gene() {} + /** + * Class constructor, initializes Gene with default value. + */ Gene(Type value) { this->value = value; } @@ -20,11 +31,20 @@ namespace genetic { /** Copy constructor */ Gene(const Gene& gene) : value(gene.get()) {} + /** + * Copy operator. + * + * @param gene Gene from which the value should be copied. + * @return Gene instance containing copied value + */ Gene& operator=(const Gene& gene) { this->value = gene.get(); return *this; } + /** + * Allows read-only access to Gene value + */ Type get() const { return value; } diff --git a/src/generation.h b/src/generation.h index 39b9577..a376028 100644 --- a/src/generation.h +++ b/src/generation.h @@ -10,16 +10,27 @@ using namespace std; namespace genetic { /** - * Generation of given Chromosomes. + * Class representing Generation of given Chromosomes. */ template < typename _Chromosome > class Generation { protected: + /** + * Chromosomes in the given Generation + */ vector<_Chromosome> chromosomes; public: + /** + * Default constructor + */ Generation() {} + /** + * Class constructor. Initializes generation with the given chromosomes + * + * @param chromosomes vector containing Chromosomes to use in Generation + */ Generation(vector<_Chromosome> chromosomes) { this->chromosomes = chromosomes; } @@ -29,10 +40,19 @@ namespace genetic { : chromosomes(generation.get()) { } + /** + * Allows read-only access to Generation Chromosomes + */ vector<_Chromosome> get() const { return this->chromosomes; } + /** + * Copy operator. + * + * @param generation Generation from which the Chromosomes should be copied. + * @return Generation instance containing copied Chromosomes + */ Generation& operator=(const Generation& generation){ this->chromosomes = generation.get(); return *this; diff --git a/src/generator/generation.h b/src/generator/generation.h index a51e4b3..91e605d 100644 --- a/src/generator/generation.h +++ b/src/generator/generation.h @@ -19,7 +19,7 @@ namespace genetic { class Generation { public: /** - * Type of used Genes in Chromosome + * Type representing Chromosome Gene */ typedef typename _Chromosome::GeneType GeneType; protected: @@ -38,7 +38,7 @@ namespace genetic { * Constructor. Initializes required variables and constants * * @param generationSize Indicates size of the generation - * @param generationSize Indicates size of the chromosome + * @param chromosomeSize Indicates size of the chromosome */ Generation(unsigned int generationSize, unsigned int chromosomeSize) { this->generationSize = generationSize; diff --git a/src/mutation/mutation.h b/src/mutation/mutation.h index 69c23e7..7b626ba 100644 --- a/src/mutation/mutation.h +++ b/src/mutation/mutation.h @@ -10,19 +10,44 @@ using namespace std; namespace genetic { // namespace mutation { + /** + * Mutations class. Applies mutation on Chromosome's. + */ template < typename _Chromosome> class Mutation { public: + /** + * Type of probability of mutation chance + */ typedef double MutationChanceType; + + /** + * Type representing Chromosome Gene + */ typedef typename _Chromosome::GeneType GeneType; protected: + /** + * Chance with which mutation can occur. + */ MutationChanceType chance; public: + /** + * Class constructor. Initializes class variables. + * + * @param chance Chance on which Mutation can occur. + */ Mutation(MutationChanceType chance) : chance(chance) { } + /** + * Applies with defined probability mutation on the given generation + * of Chromosome's. + * + * @param _generation Generation for which the mutation should be applied + * @return new Generation of Chromosome's that passed the mutation + */ Generation<_Chromosome> mutate(Generation<_Chromosome> _generation) { const unsigned int generationSize = _generation.get().size(); const unsigned int chromosomeSize = _generation.get()[0].get().size(); diff --git a/src/selection/roulette.h b/src/selection/roulette.h index 7f2d240..6db71ef 100644 --- a/src/selection/roulette.h +++ b/src/selection/roulette.h @@ -21,7 +21,14 @@ namespace genetic { template < typename _Chromosome > class Roulette : public Selection<_Chromosome> { public: + /** + * Parent Selection class + */ typedef Selection<_Chromosome> BaseType; + + /** + * Value type returned by the Fitness function + */ typedef typename BaseType::FitnessValueType FitnessValueType; protected: /** @@ -92,7 +99,7 @@ namespace genetic { * * @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 + * @return new Generation of Chromosome's that passed the Selection */ Generation<_Chromosome> spinRoulette( multimap normalizedFitness) { @@ -155,6 +162,8 @@ namespace genetic { /** * Draws new Generation using Roulette method + * + * @return new Generation of Chromosome's that passed the Selection */ Generation<_Chromosome> do_draw() { multimap normalizedFitness; diff --git a/src/selection/selection.h b/src/selection/selection.h index f519ca1..dd6e846 100644 --- a/src/selection/selection.h +++ b/src/selection/selection.h @@ -9,27 +9,69 @@ using namespace std; namespace genetic { // namespace selection { + /** + * Base Selection template class. It should be a base class for any + * custom selection functions. + */ template < typename _Chromosome > class Selection { public: + /** + * Type representing Fitness function + */ typedef Fitness<_Chromosome> GeneticFitness; + + /** + * Value type returned by the Fitness function + */ typedef typename GeneticFitness::ValueType FitnessValueType; protected: + /** + * Generation over which the Selection will be applied + */ Generation<_Chromosome> generation; + + /** + * Fitness which will be used in selection + */ GeneticFitness& fitness; - + + /** + * Checks Fitness for the given Chromosome + * + * @param chromosome Chromosome for which the selection fitness is + * checked. + * @return Value of the Fitness function + */ FitnessValueType checkChromosomeFitness(_Chromosome chromosome) { this->fitness.chromosome = chromosome; return fitness.calculate(); } + /** + * Selection calculations should be done here. + * + * @return new Generation of Chromosome's that passed the Selection + */ virtual Generation<_Chromosome> do_draw() = 0; public: + /** + * Class constructor. Initializes required variables and constants + * + * @param _generation Generation over which the Selection will be + * applied + * @param _fitness Fitness function to use in Selection + */ Selection(Generation<_Chromosome> _generation, GeneticFitness& _fitness) : generation(_generation), fitness(_fitness) { } + /** + * Invokes Selection calculations + * + * @return new Generation of Chromosome's that passed the Selection + */ Generation<_Chromosome> draw() { return this->do_draw(); } -- 2.30.2