Update docs, some cleanup

eo/NEWS

@@ -1,7 +1,8 @@
-* release 0.9.4
+* release 0.9.4 (not yet released)
   - Update introductory pages of documentation and webpage.
   - Remove support for pre-standard C++ compiler (i.e. gcc-2.x), which allows to
     clean up the code considerably. Assume availability of sstream and limits.
+  - Implement CMA-ES.
   
 
 * release 0.9.3z.1 (1. Oct. 2005)

eo/doc/mainpage.html

@@ -102,7 +102,7 @@
         </tr>
         <tr>
           <td class="TITLE" align="right" valign="top" width="100">
-            <h2>Tutorial</h2>
+            <h2>Documentation</h2>
           </td>
           <td bgcolor="#ffcc99">
             <p>
@@ -122,7 +122,6 @@
               href="http://sourceforge.net/project/showfiles.php?group_id=9775">released
               sources</a>.              
             </p>
-            
             <p>
               The latest
               <a
@@ -132,6 +131,12 @@
               href="http://eodev.sourceforge.net/eo/tutorial/pdf/paradiseoJet7.pdf">introduction
               to ParadisEO</a>, the parallel version of EO.
             </p>
+            <p>
+              The complete code is also well documented and you can look at the
+              generated <a
+              href="http://eodev.sourceforge.net/eo/doc/html/index.html">interface
+              documentation</a>.
+            </p>
           </td>
         </tr>
         <tr>

eo/src/utils/eoRNG.h

@@ -51,6 +51,15 @@ number generator MT19937 for generating random numbers. The various
 member functions implement useful functions for evolutionary
 algorithms. Included are: rand(), random(), flip() and normal().
 
+EO provides a global random number generator <tt>rng</tt> that is seeded by the
+current UNIX time at program start. Moreover some global convenience functions
+are provided that use the global random number generator: <tt>random</tt>,
+<tt>normal</tt>.
+
+@warning If you want to repeatedly generated the same sequence of pseudo-random
+numbers, you should always reseed the generator at the beginning of your code.
+
+
 
 <h1>Documentation in original file</h1>
 
@@ -77,19 +86,19 @@ depending on data type sizes, and the code is quite short as well). It generates
 random numbers in batches of 624 at a time, so the caching and pipelining of
 modern systems is exploited. It is also divide- and mod-free.
 
-The code as Shawn received it included the following notice:
+The code as Shawn received it included the following notice: <tt>Copyright (C)
-- Copyright (C) 1997 Makoto Matsumoto and Takuji Nishimura. When you use this,
+1997 Makoto Matsumoto and Takuji Nishimura. When you use this, send an e-mail to
-  send an e-mail to <matumoto@math.keio.ac.jp> with an appropriate reference to
+<matumoto@math.keio.ac.jp> with an appropriate reference to your work.</tt> It
-  your work.
+would be nice to Cc: <Cokus@math.washington.edu> and
-- It would be nice to CC: <Cokus@math.washington.edu> when you write.
+<eodev-main@lists.sourceforge.net> when you write.
 
 
 <h1>Portability</h1>
 
 Note for people porting EO to other platforms: please make sure that the type
-uint32_t in the file eoRng.h is exactly 32 bits long. It may be longer, but not
+uint32_t in the file eoRng.h is exactly 32 bits long. It may in principle be
-shorter. If it is longer, file compatibility between EO on different platforms
+longer, but not shorter. If it is longer, file compatibility between EO on
-may be broken.
+different platforms may be broken.
 */
 class eoRng : public eoObject, public eoPersistent
 {
@@ -130,11 +139,13 @@ public :
 
     /** Re-initializes the Random Number Generator
 
-    This is the traditional seeding procedure.
+    This is the traditional seeding procedure. This version is deprecated and
+    only provided for compatibility with old code. In new projects you should
+    use reseed.
 
     @see reseed for details on usage of the seeding value.
 
-    @version old version
+    @version old version (deprecated)
     */
     void oldReseed(uint32_t s)
         {
@@ -241,7 +252,11 @@ public :
 
     @overload
 
+    Provide a version returning a non-const element reference.
+
     @return Uniformly chosen element from the vector.
+
+    @warning Changing the return value does alter the vector.
     */
     template <typename TYPE>
     TYPE& choice(std::vector<TYPE>& vec)
@@ -278,42 +293,108 @@ public :
     std::string className(void) const { return "Mersenne-Twister"; }
 
 private:
+
     uint32_t restart(void);
+
+
+    /* @brief Initialize state
+
+    We initialize state[0..(N-1)] via the generator
+
+    <tt>x_new = (69069 * x_old) mod 2^32</tt>
+
+    from Line 15 of Table 1, p. 106, Sec. 3.3.4 of Knuth's _The Art of Computer
+    Programming_, Volume 2, 3rd ed.
+
+    Notes (SJC): I do not know what the initial state requirements of the
+    Mersenne Twister are, but it seems this seeding generator could be better.
+    It achieves the maximum period for its modulus (2^30) iff x_initial is odd
+    (p. 20-21, Sec. 3.2.1.2, Knuth); if x_initial can be even, you have
+    sequences like 0, 0, 0, ...; 2^31, 2^31, 2^31, ...; 2^30, 2^30, 2^30, ...;
+    2^29, 2^29 + 2^31, 2^29, 2^29 + 2^31, ..., etc. so I force seed to be odd
+    below.
+
+    Even if x_initial is odd, if x_initial is 1 mod 4 then
+
+    the          lowest bit of x is always 1,
+    the  next-to-lowest bit of x is always 0,
+    the 2nd-from-lowest bit of x alternates      ... 0 1 0 1 0 1 0 1 ... ,
+    the 3rd-from-lowest bit of x 4-cycles        ... 0 1 1 0 0 1 1 0 ... ,
+    the 4th-from-lowest bit of x has the 8-cycle ... 0 0 0 1 1 1 1 0 ... ,
+    ...
+
+    and if x_initial is 3 mod 4 then
+
+    the          lowest bit of x is always 1,
+    the  next-to-lowest bit of x is always 1,
+    the 2nd-from-lowest bit of x alternates      ... 0 1 0 1 0 1 0 1 ... ,
+    the 3rd-from-lowest bit of x 4-cycles        ... 0 0 1 1 0 0 1 1 ... ,
+    the 4th-from-lowest bit of x has the 8-cycle ... 0 0 1 1 1 1 0 0 ... ,
+    ...
+
+    The generator's potency (min. s>=0 with (69069-1)^s = 0 mod 2^32) is 16,
+    which seems to be alright by p. 25, Sec. 3.2.1.3 of Knuth. It also does well
+    in the dimension 2..5 spectral tests, but it could be better in dimension 6
+    (Line 15, Table 1, p. 106, Sec. 3.3.4, Knuth).
+
+    Note that the random number user does not see the values generated here
+    directly since restart() will always munge them first, so maybe none of all
+    of this matters. In fact, the seed values made here could even be
+    extra-special desirable if the Mersenne Twister theory says so-- that's why
+    the only change I made is to restrict to odd seeds.
+    */
     void initialize(uint32_t seed);
 
- uint32_t* state; // the array for the state
+    /** @brief Array for the state */
+    uint32_t* state;
+
     uint32_t* next;
+
     int left;
 
     // for normal distribution
     bool cached;
+
     float cacheValue;
 
     const int N;
+
     const int M;
- const uint32_t K; // a magic constant
+
+    /** @brief Magic constant */
+    const uint32_t K;
 
 
- /**
+    /** @brief Copy constructor
-	Private copy ctor and assignment operator to make sure that
+
-	nobody accidentally copies the random number generator.
+    Private copy ctor and assignment operator to make sure that nobody
-	If you want similar RNG's, make two RNG's and initialize
+    accidentally copies the random number generator. If you want similar RNG's,
-	them with the same seed.
+    make two RNG's and initialize them with the same seed.
+
+    As it cannot be called, we do not provide an implementation.
     */
-  eoRng (const eoRng&);				// no implementation
+    eoRng(const eoRng&);
-  eoRng& operator=(const eoRng&);	// dito
+
+    /** @brief Assignmant operator
+
+    @see Copy constructor eoRng(const eoRng&).
+    */
+    eoRng& operator=(const eoRng&);
 };
 
-/**
+
-	The one and only global eoRng object
+
-*/
 namespace eo
 {
+    /** The one and only global eoRng object */
     extern eoRng rng;
 }
-
 using eo::rng;
 
+
+
+
+
 // Implementation of some eoRng members.... Don't mind the mess, it does work.
 
 
@@ -324,52 +405,6 @@ using eo::rng;
 
 inline void eoRng::initialize(uint32_t seed)
 {
-    //
-    // We initialize state[0..(N-1)] via the generator
-    //
-    //   x_new = (69069 * x_old) mod 2^32
-    //
-    // from Line 15 of Table 1, p. 106, Sec. 3.3.4 of Knuth's
-    // _The Art of Computer Programming_, Volume 2, 3rd ed.
-    //
-    // Notes (SJC): I do not know what the initial state requirements
-    // of the Mersenne Twister are, but it seems this seeding generator
-    // could be better.  It achieves the maximum period for its modulus
-    // (2^30) iff x_initial is odd (p. 20-21, Sec. 3.2.1.2, Knuth); if
-    // x_initial can be even, you have sequences like 0, 0, 0, ...;
-    // 2^31, 2^31, 2^31, ...; 2^30, 2^30, 2^30, ...; 2^29, 2^29 + 2^31,
-    // 2^29, 2^29 + 2^31, ..., etc. so I force seed to be odd below.
-    //
-    // Even if x_initial is odd, if x_initial is 1 mod 4 then
-    //
-    //   the          lowest bit of x is always 1,
-    //   the  next-to-lowest bit of x is always 0,
-    //   the 2nd-from-lowest bit of x alternates      ... 0 1 0 1 0 1 0 1 ... ,
-    //   the 3rd-from-lowest bit of x 4-cycles        ... 0 1 1 0 0 1 1 0 ... ,
-    //   the 4th-from-lowest bit of x has the 8-cycle ... 0 0 0 1 1 1 1 0 ... ,
-    //    ...
-    //
-    // and if x_initial is 3 mod 4 then
-    //
-    //   the          lowest bit of x is always 1,
-    //   the  next-to-lowest bit of x is always 1,
-    //   the 2nd-from-lowest bit of x alternates      ... 0 1 0 1 0 1 0 1 ... ,
-    //   the 3rd-from-lowest bit of x 4-cycles        ... 0 0 1 1 0 0 1 1 ... ,
-    //   the 4th-from-lowest bit of x has the 8-cycle ... 0 0 1 1 1 1 0 0 ... ,
-    //    ...
-    //
-    // The generator's potency (min. s>=0 with (69069-1)^s = 0 mod 2^32) is
-    // 16, which seems to be alright by p. 25, Sec. 3.2.1.3 of Knuth.  It
-    // also does well in the dimension 2..5 spectral tests, but it could be
-    // better in dimension 6 (Line 15, Table 1, p. 106, Sec. 3.3.4, Knuth).
-    //
-    // Note that the random number user does not see the values generated
-    // here directly since restart() will always munge them first, so maybe
-    // none of all of this matters.  In fact, the seed values made here could
-    // even be extra-special desirable if the Mersenne Twister theory says
-    // so-- that's why the only change I made is to restrict to odd seeds.
-    //
-
     left = -1;
 
     register uint32_t x = (seed | 1U) & 0xFFFFFFFFU, *s = state;
@@ -380,6 +415,7 @@ inline void eoRng::initialize(uint32_t seed)
 }
 
 
+
 inline uint32_t eoRng::restart(void)
 {
     register uint32_t *p0=state, *p2=state+2, *pM=state+M, s0, s1;
@@ -400,6 +436,8 @@ inline uint32_t eoRng::restart(void)
     return(s1 ^ (s1 >> 18));
 }
 
+
+
 inline uint32_t eoRng::rand(void)
 {
 
@@ -415,6 +453,8 @@ inline uint32_t eoRng::rand(void)
     return(y ^ (y >> 18));
 }
 
+
+
 inline double eoRng::normal(void)
 {
     if (cached)
@@ -442,20 +482,40 @@ inline double eoRng::normal(void)
     return (var2 * factor);
 }
 
+
+
 namespace eo {
     // a few convenience functions for generating numbers
 
-    /**
+    /** @brief Random function
-     * Templatized random function, works with most basic types such as:
+
-     *	char
+    Templatized random function, returns a random double in the range [0, max).
-     *	int
+
-     *	unsigned
+    @param max Maximum for distribution
-     *	float
+
-     *	double
+    It works with most basic types such as:
+    - char
+    - int
+    - unsigned
+    - float
+    - double
     */
     template <typename T>
-	inline
+    inline T random(const T& max) {
-	T random(const T& mx) { return static_cast<T>(rng.uniform() * mx); }
+        return static_cast<T>(rng.uniform() * max); }
+
+    /** @brief Random function
+
+    Templatized random function, returns a random double in the range [min, max).
+
+    @param min Minimum for distribution
+    @param max Maximum for distribution
+
+    @see random(const T& max)
+    */
+    template <typename T>
+    inline T random(const T& min, const T& max) {
+        return static_cast<T>(rng.uniform() * (max-min)) + min; }
 
     /** Normal distribution */
     inline double normal() { return rng.normal(); }