From 044d1223bb638c63869c5ccaebd6951d8da530bd Mon Sep 17 00:00:00 2001 From: Johann Dreo Date: Mon, 1 Nov 2010 18:20:56 +0100 Subject: [PATCH] Create more doxygen groups for base classes, clean some doc --- eo/src/EO.h | 29 +++++++++++++++++++++++------ eo/src/eoCombinedInit.h | 3 ++- eo/src/eoInit.h | 10 +++++++++- eo/src/eoInitializer.h | 9 +++++++-- eo/src/eoObject.h | 9 +++++---- eo/src/eoOp.h | 23 ++++++++++++++++------- eo/src/eoParticleBestInit.h | 8 +++++++- eo/src/eoParticleFullInitializer.h | 7 ++++++- eo/src/eoPersistent.h | 18 ++++++------------ eo/src/eoPrintable.h | 14 ++++++++------ eo/src/eoSwapMutation.h | 2 ++ eo/src/eoVector.h | 8 ++++++++ eo/src/eoVectorParticle.h | 7 +++++++ eo/src/eoVelocityInit.h | 8 ++++++++ 14 files changed, 114 insertions(+), 41 deletions(-) diff --git a/eo/src/EO.h b/eo/src/EO.h index 07dfb77d..7d8f5f55 100644 --- a/eo/src/EO.h +++ b/eo/src/EO.h @@ -31,15 +31,30 @@ #include // eoObject #include // eoPersistent -//----------------------------------------------------------------------------- -/** EO is a base class for evolvable objects, that is, the subjects of +/** + @defgroup Core Core components + + This are the base classes from which useful objects inherits. + + @{ + */ + +/** EO is the base class for objects with a fitness. + + Those evolvable objects are the subjects of evolution. EOs have only got a fitness, which at the same time needs to be only an object with the operation less than (<) defined. Fitness says how good is the object; evolution or change of these objects is left to the - genetic operators. A fitness less than another means a worse fitness, in + genetic operators. + + A fitness less than another means a worse fitness, in whatever the context; thus, fitness is always maximized; although it can - be minimized with a proper definition of the < operator. The fitness - object must have, besides an void ctor, a copy ctor. + be minimized with a proper definition of the < operator. + + A fitness can be invalid if undefined, trying to read an invalid fitness will raise an error. + @ref Operators that effectively modify EO objects must invalidate them. + + The fitness object must have, besides an void ctor, a copy ctor. */ template class EO: public eoObject, public eoPersistent { @@ -150,6 +165,8 @@ private: bool invalidFitness; // true if the value of fitness is invalid }; -//----------------------------------------------------------------------------- #endif + +/** @} */ + diff --git a/eo/src/eoCombinedInit.h b/eo/src/eoCombinedInit.h index 68f21970..67fa0230 100644 --- a/eo/src/eoCombinedInit.h +++ b/eo/src/eoCombinedInit.h @@ -29,8 +29,9 @@ /** Combined INIT: a proportional recombination of eoInit objects -*/ + @ingroup Initializators +*/ template< class EOT> class eoCombinedInit: public eoInit { public: diff --git a/eo/src/eoInit.h b/eo/src/eoInit.h index 87d38fee..f787b933 100644 --- a/eo/src/eoInit.h +++ b/eo/src/eoInit.h @@ -34,6 +34,14 @@ #include #include // for shuffle method + +/** + @defgroup Initializators Initialization operators + @ingroup Operators + + Initializators are operators that creates initial individuals and populations. +*/ +/** @{*/ /** Base (name) class for Initialization of chromosomes, used in a population contructor. It is derived from eoMonOp, so it can be used @@ -41,7 +49,6 @@ @see eoPop */ - template class eoInit : public eoUF { @@ -202,3 +209,4 @@ class eoInitAdaptor : public eoMonOp }; #endif +/** @}*/ diff --git a/eo/src/eoInitializer.h b/eo/src/eoInitializer.h index 63fbd645..d3190894 100644 --- a/eo/src/eoInitializer.h +++ b/eo/src/eoInitializer.h @@ -33,8 +33,13 @@ #include #include +/** + @addtogroup Initializators + @{ + */ -/* + +/** * Abstract class for initialization of algorithm PSO */ template class eoInitializerBase : public eoFunctorBase @@ -137,5 +142,5 @@ class eoDummy : public eoUF }; #endif - +/** @} */ diff --git a/eo/src/eoObject.h b/eo/src/eoObject.h index 7f603905..2e59f190 100644 --- a/eo/src/eoObject.h +++ b/eo/src/eoObject.h @@ -33,16 +33,16 @@ #include -//----------------------------------------------------------------------------- -// eoObject -//----------------------------------------------------------------------------- -/** +/* eoObject used to be the base class for the whole hierarchy, but this has changed. eoObject is used to define a name (#className#) that is used when loading or saving the state. Previously, this object also defined a print and read interface, but itīs been moved to eoPrintable and eoPersistent. +*/ + +/** Defines a name (#className#), used when loading or saving a state. It is recommended that you only derive from eoObject in concrete classes. Some parts of EO do not implement this yet, but that will change in the future. @@ -51,6 +51,7 @@ framework that is only needed when the classes have state that changes at runtim @see eoPersistent eoPrintable, eoState + @ingroup Core */ class eoObject { diff --git a/eo/src/eoOp.h b/eo/src/eoOp.h index 81c7c9d6..f4277463 100644 --- a/eo/src/eoOp.h +++ b/eo/src/eoOp.h @@ -30,14 +30,13 @@ #include #include /** -\defgroup Operators -Genetic Operators are used for various purposes -*/ +@defgroup Operators Operators -/** @name Genetic operators +in EO, an operator is any functors that modifies objects and inherits from an eoOp. -What is a genetic algorithm without genetic operators? -There is a genetic operator hierarchy, with eoOp as father and +Typically, a mutation is an operator that modifies an individual, and an algorithm is an operator that modifies a population. + +In EO, there is a genetic operator hierarchy, with eoOp as father and eoMonOp (monary or unary operator), eoBinOp and eoQuadOp (binary operators) and eoGenOp (any number of inputs and outputs, see eoGenOp.h) as subclasses. @@ -53,9 +52,19 @@ how to build them from a description in a file. @version 0.9 @see eoGenOp.h eoOpFactory */ - //@{ +/** +@defgroup Variators Variation operators +Variators are operators that modify individuals. + +@defgroup Selectors Selection operators +Selectors are operators that select a subset of a population. + +@defgroup Replacors Replacement operators +Replacors are operators that replace a subset of a population by another set of individuals. +*/ + /** Abstract data types for EO operators. Genetic operators act on chromosomes, changing them. The type to use them on is problem specific. If your genotype diff --git a/eo/src/eoParticleBestInit.h b/eo/src/eoParticleBestInit.h index b847f716..dd6a6a82 100644 --- a/eo/src/eoParticleBestInit.h +++ b/eo/src/eoParticleBestInit.h @@ -30,9 +30,13 @@ //----------------------------------------------------------------------------- /** - * Abstract class for particle best position initialization. + @addtogroup Initializators + @{ */ +/** + * Abstract class for particle best position initialization. + */ template < class POT > class eoParticleBestInit:public eoUF < POT &, void > { public: @@ -75,3 +79,5 @@ public: #endif /*_EOPARTICLEBESTINIT_H */ +/** @} */ + diff --git a/eo/src/eoParticleFullInitializer.h b/eo/src/eoParticleFullInitializer.h index d800db5b..8ec414df 100644 --- a/eo/src/eoParticleFullInitializer.h +++ b/eo/src/eoParticleFullInitializer.h @@ -33,6 +33,11 @@ #include #include +/** + @addtogroup Initializators + @{ + */ + /* * Abstract class for initialization of algorithm PSO @@ -145,5 +150,5 @@ template class eoParticleInitializer : public eoInitializerBase // std::istream, std::ostream #include // para std::string -//----------------------------------------------------------------------------- #include "eoPrintable.h" -//----------------------------------------------------------------------------- -// eoPersistent -//----------------------------------------------------------------------------- +/** + @addtogroup Core + @{ +*/ + /** An persistent object that knows how to write (through functions inherited from #eoPrintable#) and read itself @@ -64,9 +58,9 @@ class eoPersistent: public eoPrintable }; -//----------------------------------------------------------------------------- ///Standard input for all objects in the EO hierarchy std::istream & operator >> ( std::istream& _is, eoPersistent& _o ); #endif +/** @} */ diff --git a/eo/src/eoPrintable.h b/eo/src/eoPrintable.h index 256383dc..4326f09a 100644 --- a/eo/src/eoPrintable.h +++ b/eo/src/eoPrintable.h @@ -30,15 +30,17 @@ #include // std::istream, std::ostream #include // para std::string -//----------------------------------------------------------------------------- -// eoPrintable -//----------------------------------------------------------------------------- +/* +This functionality was separated from eoObject, since it makes no sense to print +some objects (for instance, a #eoFactory# or a random number generator. +*/ + /** Base class for objects that can print themselves (#printOn#). Besides, this file defines the standard output for all the objects; -if the objects define printOn there's no need to define #operator <<#.\\ -This functionality was separated from eoObject, since it makes no sense to print -some objects (for instance, a #eoFactory# or a random number generator. +if the objects define printOn there's no need to define #operator <<#. + + @ingroup Core */ class eoPrintable { diff --git a/eo/src/eoSwapMutation.h b/eo/src/eoSwapMutation.h index 0eda6416..aab729b2 100644 --- a/eo/src/eoSwapMutation.h +++ b/eo/src/eoSwapMutation.h @@ -34,6 +34,8 @@ /** * Swap two components of a chromosome. + * + * @ingroup Variators */ template class eoSwapMutation: public eoMonOp { diff --git a/eo/src/eoVector.h b/eo/src/eoVector.h index ce85391f..8600b62d 100644 --- a/eo/src/eoVector.h +++ b/eo/src/eoVector.h @@ -28,6 +28,12 @@ Old contact: todos@geneura.ugr.es, http://geneura.ugr.es #include #include + +/** + @addtogroup Core + @{ +*/ + /** Base class for fixed length chromosomes It just derives from EO and std::vector and redirects the smaller than @@ -35,6 +41,7 @@ operator to EO (fitness based comparison). GeneType must have the following methods: void ctor (needed for the std::vector<>), copy ctor, + */ template class eoVector : public EO, public std::vector @@ -143,6 +150,7 @@ bool operator>(const eoVector& _eo1, const eoVector + +/** + @addtogroup Core + @{ +*/ + /** * Main class for particle representation of particle swarm optimization. The positions, velocities and the best positions * associated to the particle are stored as vectors. Inheriting from PO and std::vector, @@ -146,3 +152,4 @@ public: }; #endif /*_EOVECTORPARTICLE_H*/ +/** @} */ diff --git a/eo/src/eoVelocityInit.h b/eo/src/eoVelocityInit.h index a8000d6d..4a096f4c 100644 --- a/eo/src/eoVelocityInit.h +++ b/eo/src/eoVelocityInit.h @@ -32,6 +32,11 @@ #include #include +/** + @addtogroup Initializators + @{ + */ + /** Abstract class for velocities initilization of particle swarm optimization.*/ template < class POT > class eoVelocityInit:public eoInit < POT > { @@ -137,3 +142,6 @@ private: }; #endif /*EOVELOCITYINIT_H */ + +/** @} */ +