Generators
**********


Abstract Base Generator
=======================

class BaseGenerator

   Base generator from which all generators must inherit to be
   compatible with GloMPO.

   Attributes:
   logger : logging.Logger
      "logging.Logger" instance into which status messages may be
      added.

   abstract generate(manager)

      Returns a vector representing a location in input space. The
      returned array serves as a starting point for an optimizer.

      Parameters:
      manager
         "GloMPOManager" instance which is managing the optimization.
         Its attributes can be accessed when determining the new
         point.


Simple Generators
=================

For convenience, GloMPO comes bundled with several simple generators
already included.

class ExploitExploreGenerator(max_func_calls, focus=1)

   Bases: "BaseGenerator"

   This generator blends a randomly generated point with the location
   of an existing optimizer. The optimizer is chosen based on a
   roulette selection.

   Parameters:
   max_func_calls
      Maximum function calls allowed for the optimization, at and
      beyond this point there is a 100% chance that a previously
      evaluated point will be returned by the generator. If the
      optimization is not limited by the number of function calls,
      provide an estimate.

   focus
      The blend parameter between random point and incumbent points.

   Notes:
   "focus" is used as follows:

      p=(f_calls / max_f_calls) ** focus

   At "p=0" the random point is taken. At "p=1" the incumbent is
   chosen. If "focus < 1" points are more like the incumbent, if
   "focus > 1" points are more like the random. Default is "focus = 1"
   which has a linear growth from random to incumbent. The new point
   is calculated as:

      new_pt = p*incumbent_pt + (1-p)*random_pt.

class IncumbentGenerator

   Bases: "BaseGenerator"

   Starts a new optimizer at "GloMPOManager.result['x']". A random
   vector is generated if this is indeterminate.

class PerturbationGenerator(x0, scale)

   Bases: "BaseGenerator"

   Randomly generates parameter vectors near a given point. Draws
   samples from a truncated multivariate normal distributed centered
   around a provided vector and bound by given bounds. Good for
   parametrisation efforts where a good candidate is already
   available, however, this may drastically limit the exploratory
   nature of GloMPO.

   Parameters:
   x0
      Center point for each parameter

   scale
      Standard deviation of each parameter. Used here to control how
      wide the generator should explore around the mean.

class RandomGenerator

   Bases: "BaseGenerator"

   Generates random points. Points are drawn from a uniform
   distribution within given "bounds".

class SinglePointGenerator(x=None)

   Bases: "BaseGenerator"

   Always returns the same point. Either provided during
   initialisation or otherwise randomly generated.
