Package ec.gp

# Class GPTree

java.lang.Object
ec.gp.GPTree

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

public class GPTree extends Object implements GPNodeParent, Prototype
GPTree is a GPNodeParent which holds the root GPNode of a tree of GPNodes. GPTrees typically fill out an array held in a GPIndividual (their "owner") and their roots are evaluated to evaluate a Genetic programming tree. GPTrees also have constraints, which are shared, and define items shared among several GPTrees.

In addition to serialization for checkpointing, GPTrees may read and write themselves to streams in three ways.

- writeTree(...,DataOutput)/readTree(...,DataInput) This method transmits or receives a GPTree in binary. It is the most efficient approach to sending GPTrees over networks, etc. The default versions of writeTree/readTree call writeRootedTree/readRootedTree on their respective GPNode roots.
- printTree(...,PrintWriter)/readTree(...,LineNumberReader) This approach transmits or receives a GPTree in text encoded such that the GPTree is largely readable by humans but can be read back in 100% by ECJ as well. To do this, these methods will typically encode numbers using the `ec.util.Code` class. These methods are mostly used to write out populations to files for inspection, slight modification, then reading back in later on. readTree largely calls readRootedTree on the GPNode root. Likewise, printTree calls printRootedTree
- printTreeForHumans(...,PrintWriter) This approach prints a GPTree in a fashion intended for human consumption only. printTreeForHumans calls either makeCTree and prints the result, calls makeLatexTree and prints the result, or calls printRootedTreeForHumans on the root. Which one is called depends on the kind of tree you have chosen to print for humans, as is discussed next.

GPTrees can print themselves for humans in one of four styles:

1. A GPTree can print the tree as a Koza-style Lisp s-expression, which is the default.
2. A GPTree can print itself in pseudo-C format:
   1. Terminals can be printed either as variables "a" or as zero-argument functions "a()"
   2. One-argument nonterminals are printed as functions "a(b)"
   3. Two-argument nonterminals can be printed either as operators "b a c" or as functions "a(b, c)"
   4. Nonterminals with more arguments are printed as functions "a(b, c, d, ...)"
3. A GPTree can print the tree AT&T's Graphviz format. You can snip the code out and save it as a ".dot" file to render in any Graphviz renderer (for example, use this MacOS X front end to the renderer).
4. A GPTree can print the tree as a LaTeX2e code snippet, which can be inserted into a LaTeX2e file and will result in a picture of the tree! Cool, no?

You turn the C-printing feature on with the c parameter, plus certain optional parameters (c-operators, c-variables) as described below. You turn the latex-printing latex parameter below. The C-printing parameter takes precedence.

Here's how the latex system works. To insert the code, you'll need to include the `epic`,`ecltree`, and probably the `fancybox` packages, in that order. You'll also need to define the command `\gpbox`, which takes one argument (the string name for the GPNode) and draws a box with that node. Lastly, you might want to set a few parameters dealing with the `ecltree` package.

Here's an example which looks quite good (pardon the double-backslashes in front of the usepackage statements -- javadoc is freaking out if I put a single backslash. So you'll need to remove the extra backslash in order to try out this example):

`
     \documentclass[]{article}
     \\usepackage{epic}     % required by ecltree and fancybox packages
     \\usepackage{ecltree}  % to draw the GP trees
     \\usepackage{fancybox} % required by \Ovalbox

     \begin{document}

     % minimum distance between nodes on the same line
     \setlength{\GapWidth}{1em}

     % draw with a thick dashed line, very nice looking
     \thicklines \drawwith{\dottedline{2}}

     % draw an oval and center it with the rule.  You may want to fool with the
     % rule values, though these seem to work quite well for me.  If you make the
     % rule smaller than the text height, then the GP nodes may not line up with
     % each other horizontally quite right, so watch out.
     \newcommand{\gpbox}[1]{\Ovalbox{#1\rule[-.7ex]{0ex}{2.7ex}}}

     % Here's the tree which the GP system spat out
     \begin{bundle}{\gpbox{progn3}}\chunk{\begin{bundle}{\gpbox{if-food-ahead}}
     \chunk{\begin{bundle}{\gpbox{progn3}}\chunk{\gpbox{right}}
     \chunk{\gpbox{left}}\chunk{\gpbox{move}}\end{bundle}}
     \chunk{\begin{bundle}{\gpbox{if-food-ahead}}\chunk{\gpbox{move}}
     \chunk{\gpbox{left}}\end{bundle}}\end{bundle}}\chunk{\begin{bundle}{\gpbox{progn2}}
     \chunk{\begin{bundle}{\gpbox{progn2}}\chunk{\gpbox{move}}
     \chunk{\gpbox{move}}\end{bundle}}\chunk{\begin{bundle}{\gpbox{progn2}}
     \chunk{\gpbox{right}}\chunk{\gpbox{left}}\end{bundle}}\end{bundle}}
     \chunk{\begin{bundle}{\gpbox{if-food-ahead}}\chunk{\begin{bundle}{\gpbox{if-food-ahead}}
     \chunk{\gpbox{move}}\chunk{\gpbox{left}}\end{bundle}}
     \chunk{\begin{bundle}{\gpbox{if-food-ahead}}\chunk{\gpbox{left}}\chunk{\gpbox{right}}
     \end{bundle}}\end{bundle}}\end{bundle}

     \end{document}
`

Parameters

base.`tc` String | (The tree's constraints)
base.`print-style` String, one of: c, dot, latex, lisp | (specifies the print style of the tree)
base.`c-operators` bool = `true` (default) or `false` | (when printing using c, print two-argument functions operators "b a c"? The alternative is functions "a(b, c)."
base.`c-variables` bool = `true` (default) or `false` | (when printing using c, print zero-argument functions as variables "a"? The alternative is functions "a()".)

Default Base
gp.tree

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `GPNode`
  `child`
  the root GPNode in the GPTree
  `byte`
  `constraints`
  constraints on the GPTree -- don't access the constraints through this variable -- use the constraints() method instead, which will give the actual constraints object.
  `static final int`
  `NO_TREENUM`
  `GPIndividual`
  `owner`
  the owner of the GPTree
  `static final String`
  `P_PRINT_STYLE`
  `static final String`
  `P_TREE`
  `static final String`
  `P_TREECONSTRAINTS`
  `static final String`
  `P_USEC`
  `static final String`
  `P_USEGRAPHVIZ`
  `static final String`
  `P_USELATEX`
  `static final String`
  `P_USEOPS`
  `static final String`
  `P_USEVARS`
  `static final int`
  `PRINT_STYLE_C`
  `static final int`
  `PRINT_STYLE_DOT`
  `static final int`
  `PRINT_STYLE_LATEX`
  `static final int`
  `PRINT_STYLE_LISP`
  `int`
  `printStyle`
  The print style of the GPTree.
  `boolean`
  `printTerminalsAsVariablesInC`
  When using c to print for humans, do we print terminals as variables? (as opposed to zero-argument functions)?
  `boolean`
  `printTwoArgumentNonterminalsAsOperatorsInC`
  When using c to print for humans, do we print two-argument nonterminals in operator form "a op b"? (as opposed to functions "op(a, b)")?
  `static final String`
  `V_C`
  `static final String`
  `V_DOT`
  `static final String`
  `V_LATEX`
  `static final String`
  `V_LISP`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GPTree()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `buildTree(EvolutionState state, int thread)`
  Builds a new randomly-generated rooted tree and attaches it to the GPTree.
  `Object`
  `clone()`
  Deep-clones the tree.
  `final GPTreeConstraints`
  `constraints(GPInitializer initializer)`
  `Parameter`
  `defaultBase()`
  Returns the default base for this prototype.
  `GPTree`
  `lightClone()`
  Like clone() but doesn't copy the tree.
  `void`
  `printTree(EvolutionState state, int log)`
  Prints out the tree in single-line fashion suitable for reading in later by computer.
  `void`
  `printTree(EvolutionState state, int log, int verbosity)`
  Prints out the tree in single-line fashion suitable for reading in later by computer.
  `void`
  `printTree(EvolutionState state, PrintWriter writer)`
  Prints out the tree in single-line fashion suitable for reading in later by computer.
  `void`
  `printTreeForHumans(EvolutionState state, int log)`
  Prints out the tree in a readable Lisp-like fashion.
  `void`
  `printTreeForHumans(EvolutionState state, int log, int verbosity)`
  Prints out the tree in a readable Lisp-like fashion.
  `void`
  `readTree(EvolutionState state, DataInput dataInput)`
  `void`
  `readTree(EvolutionState state, LineNumberReader reader)`
  Reads in the tree from a form printed by printTree.
  `void`
  `setup(EvolutionState state, Parameter base)`
  Sets up a prototypical GPTree with those features it shares with other GPTrees in its position in its GPIndividual, and nothhing more.
  `boolean`
  `treeEquals(GPTree tree)`
  Returns true if I am "genetically" the same as tree, though we may have different owners.
  `int`
  `treeHashCode()`
  Returns a hash code for comparing different GPTrees.
  `int`
  `treeNumber()`
  An expensive function which determines my tree number -- only use for errors, etc.
  `final void`
  `verify(EvolutionState state)`
  Verification of validity of the tree -- strictly for debugging purposes only
  `void`
  `writeTree(EvolutionState state, DataOutput dataOutput)`

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

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

- ## Field Details

  - ### P_TREE

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

  - ### P_TREECONSTRAINTS

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

  - ### P_USEGRAPHVIZ

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

  - ### P_USELATEX

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

  - ### P_USEC

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

  - ### P_USEOPS

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

  - ### P_USEVARS

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

  - ### NO_TREENUM

    public static final int NO_TREENUM
    See Also:
      - Constant Field Values

  - ### P_PRINT_STYLE

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

  - ### V_LISP

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

  - ### V_DOT

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

  - ### V_LATEX

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

  - ### V_C

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

  - ### PRINT_STYLE_LISP

    public static final int PRINT_STYLE_LISP
    See Also:
      - Constant Field Values

  - ### PRINT_STYLE_DOT

    public static final int PRINT_STYLE_DOT
    See Also:
      - Constant Field Values

  - ### PRINT_STYLE_LATEX

    public static final int PRINT_STYLE_LATEX
    See Also:
      - Constant Field Values

  - ### PRINT_STYLE_C

    public static final int PRINT_STYLE_C
    See Also:
      - Constant Field Values

  - ### child

    public GPNode child
    the root GPNode in the GPTree

  - ### owner

    public GPIndividual owner
    the owner of the GPTree

  - ### constraints

    public byte constraints
    constraints on the GPTree -- don't access the constraints through this variable -- use the constraints() method instead, which will give the actual constraints object.

  - ### printStyle

    public int printStyle
    The print style of the GPTree.

  - ### printTerminalsAsVariablesInC

    public boolean printTerminalsAsVariablesInC
    When using c to print for humans, do we print terminals as variables? (as opposed to zero-argument functions)?

  - ### printTwoArgumentNonterminalsAsOperatorsInC

    public boolean printTwoArgumentNonterminalsAsOperatorsInC
    When using c to print for humans, do we print two-argument nonterminals in operator form "a op b"? (as opposed to functions "op(a, b)")?

- ## Constructor Details

  - ### GPTree

    public GPTree()

- ## Method Details

  - ### constraints

    public final GPTreeConstraints constraints(GPInitializer initializer)

  - ### 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(...).
    Specified by:
      `defaultBase` in interface `Prototype`

  - ### treeEquals

    public boolean treeEquals(GPTree tree)
    Returns true if I am "genetically" the same as tree, though we may have different owners.

  - ### treeHashCode

    public int treeHashCode()
    Returns a hash code for comparing different GPTrees. In general, two trees which are treeEquals(...) should have the same hash code.

  - ### lightClone

    public GPTree lightClone()
    Like clone() but doesn't copy the tree.

  - ### clone

    public Object clone()
    Deep-clones the tree. Note that you should not deep-clone trees attached to the prototypical GPIndividual: they are blank trees with no root, and this method will generate a NullPointerException as a result.
    Specified by:
      `clone` in interface `Prototype`
    Overrides:
      `clone` in class `Object`

  - ### treeNumber

    public int treeNumber()
    An expensive function which determines my tree number -- only use for errors, etc. Returns ec.gp.GPTree.NO_TREENUM if the tree number could not be determined (might happen if it's not been assigned yet).

  - ### setup

    public void setup(EvolutionState state, Parameter base)
    Sets up a prototypical GPTree with those features it shares with other GPTrees in its position in its GPIndividual, and nothhing more. This must be called after the GPTypes and GPNodeConstraints have been set up. Presently they're set up in GPInitializer, which gets called before this does, so we're safe.
    Specified by:
      `setup` in interface `Prototype`
    Specified by:
      `setup` in interface `Setup`

  - ### verify

    public final void verify(EvolutionState state)
    Verification of validity of the tree -- strictly for debugging purposes only

  - ### printTree

    public void printTree(EvolutionState state, int log)
    Prints out the tree in single-line fashion suitable for reading in later by computer. O(n). The default version of this method simply calls child's printRootedTree(...) method.

  - ### printTree

    public void printTree(EvolutionState state, int log, int verbosity)
    Prints out the tree in single-line fashion suitable for reading in later by computer. O(n). The default version of this method simply calls child's printRootedTree(...) method.

  - ### printTree

    public void printTree(EvolutionState state, PrintWriter writer)
    Prints out the tree in single-line fashion suitable for reading in later by computer. O(n). The default version of this method simply calls child's printRootedTree(...) method.

  - ### readTree

    public void readTree(EvolutionState state, LineNumberReader reader) throws IOException
    Reads in the tree from a form printed by printTree.
    Throws:
      `IOException`

  - ### writeTree

    public void writeTree(EvolutionState state, DataOutput dataOutput) throws IOException
    Throws:
      `IOException`

  - ### readTree

    public void readTree(EvolutionState state, DataInput dataInput) throws IOException
    Throws:
      `IOException`

  - ### printTreeForHumans

    public void printTreeForHumans(EvolutionState state, int log)
    Prints out the tree in a readable Lisp-like fashion. O(n). The default version of this method simply calls child's printRootedTreeForHumans(...) method.

  - ### printTreeForHumans

    public void printTreeForHumans(EvolutionState state, int log, int verbosity)
    Prints out the tree in a readable Lisp-like fashion. O(n). The default version of this method simply calls child's printRootedTreeForHumans(...) method.

  - ### buildTree

    public void buildTree(EvolutionState state, int thread)
    Builds a new randomly-generated rooted tree and attaches it to the GPTree.