Example Programs for MOSES
                   --------------------------

This directory contains a set of example programs for MOSES, showing
how to use the MOSES algorithm and assorted infrastructure to solve
various common "textbook" problems with MOSES.

Some of these are better documented then others. A synopsis of the
documented examples are given below.

Most/all of these examples don't demonstrate MOSES at all, but rather
exercise a certain component within MOSES. In most cases, this is the
optimizer, which implements a generic estimation-of-distribution
algorithm.  The MOSES meta-optimizer draws heavily on this component
to perform much of the "heavy lifting".

-- onemax.  This uses a scoring function that counts the number of ones
   in a bit string. The solver is supposed to find the optimal solution,
   which is a string of all ones.

   Usage: onemax <rand-seed> <bit-string-len> <population-size> <num-gens>

-- nmax. This uses a scoring function that totals up the values of a
   set of discrete variables. The solver should find as a solution the
   set where all of the variables have thier maximum value.  The onemax
   problem is a special case of this, with n=2.

   Usage: nmax <rand-seed> <set-size> <population-size> <num-gens> <arity>

   NOTE: There's currently a bug, this fails for n=2, see bug 908230.
   https://bugs.launchpad.net/moses/+bug/908230

-- continmax. This is a variation of the onemax/nmax problems above, but
   with continuous variables in place of discrete variables.

   NOTE: This sort-of works, but not well, I think due to bugs. See
   https://bugs.launchpad.net/moses/+bug/908247

-- termmax. A variation of the continmax problem, but extended for
   arbitrary n-ary term-algebra trees.  term support in MOSES is 
   currently incomplete and non-functional.

-- trap-uni. A variation of the nmax problem, with a so-called 
   "deceptive" scoring function. Such scoring functions will decieve 
   genetic-algorithm and hill-climbing algorithms into searching for
   minima in the wrong places.  For the moses infrastructure, the
   default univariate solver decouples values, and so is not decieved
   at all -- it is treated in exactly the same way as the nmax problem.

-- trap-bits. A variation of the trap-uni problem above. Under
   construction, curently broken.


Artificial Neural Net (ANN) demos:
==================================

-- moses-ann-xor Demo for using ANN to solve the XOR problem.
   The scoring function for this is located in ann_scoring.h

-- moses-ann-pole1
-- moses-ann-pole2
-- moses-ann-pole2-hillclimbing
-- moses-ann-pole2nv
   These are all variations of the classic AI demo problem of balancing
   a pole that is on top of a cart with wheels. The goal is to move the
   cart around so tht the pole doesn't tip over.  The physics for the
   cart and the pole are implemented in pole_balancing.cc pole_balancing.h
   and the required scoring functions (to determine how well the system
   is doing) is implemented in pole_scoring.h.


Performance Measurement
=======================
This directory also contains some minor utilities that are handy for 
measuring perofrmance. These include moses-perf.cc and the python
script scaling.py which measures how well the system distributes
across multiple MPI nodes.