Package ec.gp.build

# Class Uniform

java.lang.Object
ec.gp.GPNodeBuilder
ec.gp.build.Uniform

All Implemented Interfaces:
  `Prototype`, `Setup`, `Serializable`, `Cloneable`

public class Uniform extends GPNodeBuilder
Uniform implements the algorithm described in

Bohm, Walter and Andreas Geyer-Schulz. 1996. "Exact Uniform Initialization for Genetic Programming". In Foundations of Genetic Algorithms IV, Richard Belew and Michael Vose, eds. Morgan Kaufmann. 379-407. (ISBN 1-55860-460-X)

The user-provided requested tree size is either provided directly to the Uniform algorithm, or if the size is NOSIZEGIVEN, then Uniform will pick one at random from the GPNodeBuilder probability distribution system (using either max-depth and min-depth, or using num-sizes).

Further, if the user sets the `true-dist` parameter, the Uniform will ignore the user's specified probability distribution and instead pick from a distribution between the minimum size and the maximum size the user specified, where the sizes are distributed according to the actual number of trees that can be created with that size. Since many more trees of size 10 than size 3 can be created, for example, size 10 will be picked that much more often.

Uniform also prints out the actual number of trees that exist for a given size, return type, and function set. As if this were useful to you. :-)

The algorithm, which is quite complex, is described in pseudocode below. Basically what the algorithm does is this:

1. For each function set and return type, determine the number of trees of each size which exist for that function set and tree type. Also determine all the permutations of tree sizes among children of a given node. All this can be done with dynamic programming. Do this just once offline, after the function sets are loaded.
2. Using these tables, construct distributions of choices of tree size, child tree size permutations, etc.
3. When you need to create a tree, pick a size, then use the distriutions to recursively create the tree (top-down).

Dealing with Zero Distributions

Some domains have NO tree of a certain size. For example, Artificial Ant's function set can make NO trees of size 2. What happens when we're asked to make a tree of (invalid) size 2 in Artificial Ant then? Uniform presently handles it as follows:

1. If the system specifically requests a given size that's invalid, Uniform will look for the next larger size which is valid. If it can't find any, it will then look for the next smaller size which is valid.
2. If a random choice yields a given size that's invalid, Uniform will pick again.
3. If there is *no* valid size for a given return type, which probably indicates an error, Uniform will halt and complain.

### Pseudocode:

        Func NumTreesOfType(type,size)
            If NUMTREESOFTYPE[type,size] not defined,       // memoize
                N[type] = all nodes compatible with type
                NUMTREESOFTYPE[type,size] = Sum(n in N[type], NumTreesRootedByNode(n,size))
                return NUMTREESOFTYPE[type,size]

        Func NumTreesRootedByNode(node,size)
            If NUMTREESROOTEDBYNODE[node,size] not defined,   // memoize
                count = 0
                left = size - 1
                If node.children.length = 0 and left = 0  // a valid terminal
                    count = 1
                Else if node.children.length invalid input: '<'= left  // a valid nonterminal
                    For s is 1 to left inclusive  // yeah, that allows some illegal stuff, it gets set to 0
                        count += NumChildPermutations(node,s,left,0)
                NUMTREESROOTEDBYNODE[node,size] = count
            return NUMTREESROOTEBYNODE[node,size]

        Func NumChildPermutations(parent,size,outof,pickchild)
        // parent is our parent node
        // size is the size of pickchild's tree that we're considering
        // pickchild is the child we're considering
        // outof is the total number of remaining nodes (including size) yet to fill
            If NUMCHILDPERMUTATIONS[parent,size,outof,pickchild] is not defined,        // memoize
                count = 0
                if pickchild = parent.children.length - 1        and outof==size        // our last child, outof must be size
                    count = NumTreesOfType(parent.children[pickchild].type,size)
                else if pickchild invalid input: '<' parent.children.length - 1 and
                                    outof-size >= (parent.children.length - pickchild-1)    // maybe we can fill with terminals
                    cval = NumTreesOfType(parent.children[pickchild].type,size)
                    tot = 0
                    For s is 1 to outof-size // some illegal stuff, it gets set to 0
                        tot += NumChildPermutations(parent,s,outof-size,pickchild+1)
                    count = cval * tot
                NUMCHILDPERMUTATIONS [parent,size,outof,pickchild] = count
            return NUMCHILDPERMUTATIONS[parent,size,outof,pickchild]

        For each type type, size size
            ROOT_D[type,size] = probability distribution of nodes of type and size, derived from
                                NUMTREESOFTYPE[type,size], our node list, and NUMTREESROOTEDBYNODE[node,size]

        For each parent,outof,pickchild
            CHILD_D[parent,outof,pickchild] = probability distribution of tree sizes, derived from
                                NUMCHILDPERMUTATIONS[parent,size,outof,pickchild]

        Func FillNodeWithChildren(parent,pickchild,outof)
            If pickchild = parent.children.length - 1               // last child
                Fill parent.children[pickchild] with CreateTreeOfType(parent.children[pickchild].type,outof)
            Else choose size from CHILD_D[parent,outof,pickchild]
                Fill parent.pickchildren[pickchild] with CreateTreeOfType(parent.children[pickchild].type,size)
                FillNodeWithChildren(parent,pickchild+1,outof-size)
            return

Func CreateTreeOfType(type,size) Choose node from ROOT_D[type,size] If size > 1 FillNodeWithChildren(node,0,size-1) return node

Parameters

base.`true-dist` bool= true or false (default) | (should we use the true numbers of trees for each size as the distribution for picking trees, as opposed to the user-specified distribution?)

Default Base
gp.build.uniform

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `Hashtable`
  `_functionsets`
  `BigInteger[][][]`
  `_truesizes`
  `double[][][][][]`
  `CHILD_D`
  `Hashtable`
  `funcnodes`
  `GPFunctionSet[]`
  `functionsets`
  `int`
  `maxarity`
  `int`
  `maxtreesize`
  `BigInteger[][][][][]`
  `NUMCHILDPERMUTATIONS`
  `int`
  `numfuncnodes`
  `BigInteger[][][]`
  `NUMTREESOFTYPE`
  `BigInteger[][][]`
  `NUMTREESROOTEDBYNODE`
  `static final String`
  `P_TRUEDISTRIBUTION`
  `static final String`
  `P_UNIFORM`
  `ec.gp.build.UniformGPNodeStorage[][][][]`
  `ROOT_D`
  `boolean[][][]`
  `ROOT_D_ZERO`
  `double[][][]`
  `truesizes`
  `boolean`
  `useTrueDistribution`

  ### Fields inherited from class ec.gp.GPNodeBuilder

  `CHECK_BOUNDARY, maxSize, minSize, NOSIZEGIVEN, P_MAXSIZE, P_MINSIZE, P_NUMSIZES, P_SIZE, sizeDistribution`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Uniform()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `computePercentages()`
  `Parameter`
  `defaultBase()`
  Returns the default base for this prototype.
  `final int`
  `intForNode(GPNode node)`
  `GPNode`
  `newRootedTree(EvolutionState state, GPType type, int thread, GPNodeParent parent, GPFunctionSet set, int argposition, int requestedSize)`
  `BigInteger`
  `numChildPermutations(GPInitializer initializer, int functionset, GPNode parent, int size, int outof, int pickchild)`
  `BigInteger`
  `numTreesOfType(GPInitializer initializer, int functionset, int type, int size)`
  `BigInteger`
  `numTreesRootedByNode(GPInitializer initializer, int functionset, GPNode node, int size)`
  `int`
  `pickSize(EvolutionState state, int thread, int functionset, int type)`
  `void`
  `preprocess(EvolutionState state, int _maxtreesize)`
  `void`
  `setup(EvolutionState state, Parameter base)`
  Sets up the object by reading it from the parameters stored in state, built off of the parameter base base.

  ### Methods inherited from class ec.gp.GPNodeBuilder

  `canPick, clone, errorAboutNoNodeWithType, pickSize, warnAboutNonterminal, warnAboutNonTerminalWithType, warnAboutNoTerminalWithType`

  ### Methods inherited from class java.lang.Object

  `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### P_UNIFORM

    public static final String P_UNIFORM
    See Also:
      - Constant Field Values

  - ### P_TRUEDISTRIBUTION

    public static final String P_TRUEDISTRIBUTION
    See Also:
      - Constant Field Values

  - ### functionsets

    public GPFunctionSet[] functionsets

  - ### _functionsets

    public Hashtable _functionsets

  - ### funcnodes

    public Hashtable funcnodes

  - ### numfuncnodes

    public int numfuncnodes

  - ### maxarity

    public int maxarity

  - ### maxtreesize

    public int maxtreesize

  - ### _truesizes

    public BigInteger[][][] _truesizes

  - ### truesizes

    public double[][][] truesizes

  - ### useTrueDistribution

    public boolean useTrueDistribution

  - ### NUMTREESOFTYPE

    public BigInteger[][][] NUMTREESOFTYPE

  - ### NUMTREESROOTEDBYNODE

    public BigInteger[][][] NUMTREESROOTEDBYNODE

  - ### NUMCHILDPERMUTATIONS

    public BigInteger[][][][][] NUMCHILDPERMUTATIONS

  - ### ROOT_D

    public ec.gp.build.UniformGPNodeStorage[][][][] ROOT_D

  - ### ROOT_D_ZERO

    public boolean[][][] ROOT_D_ZERO

  - ### CHILD_D

    public double[][][][][] CHILD_D

- ## Constructor Details

  - ### Uniform

    public Uniform()

- ## Method Details

  - ### defaultBase

    public Parameter defaultBase()
    Description copied from interface: `Prototype`
    Returns the default base for this prototype. This should generally be implemented by building off of the static base() method on the DefaultsForm object for the prototype's package. This should be callable during setup(...).

  - ### setup

    public void setup(EvolutionState state, Parameter base)
    Description copied from interface: `Prototype`
    Sets up the object by reading it from the parameters stored in state, built off of the parameter base base. If an ancestor implements this method, be sure to call super.setup(state,base); before you do anything else.

    For prototypes, setup(...) is typically called once for the prototype instance; cloned instances do not receive the setup(...) call. setup(...) may be called more than once; the only guarantee is that it will get called at least once on an instance or some "parent" object from which it was ultimately cloned.

    Specified by:
      `setup` in interface `Prototype`
    Specified by:
      `setup` in interface `Setup`
    Overrides:
      `setup` in class `GPNodeBuilder`

  - ### pickSize

    public int pickSize(EvolutionState state, int thread, int functionset, int type)

  - ### preprocess

    public void preprocess(EvolutionState state, int _maxtreesize)

  - ### intForNode

    public final int intForNode(GPNode node)

  - ### numTreesOfType

    public BigInteger numTreesOfType(GPInitializer initializer, int functionset, int type, int size)

  - ### numTreesRootedByNode

    public BigInteger numTreesRootedByNode(GPInitializer initializer, int functionset, GPNode node, int size)

  - ### numChildPermutations

    public BigInteger numChildPermutations(GPInitializer initializer, int functionset, GPNode parent, int size, int outof, int pickchild)

  - ### computePercentages

    public void computePercentages()

  - ### newRootedTree

    public GPNode newRootedTree(EvolutionState state, GPType type, int thread, GPNodeParent parent, GPFunctionSet set, int argposition, int requestedSize)
    Specified by:
      `newRootedTree` in class `GPNodeBuilder`