Package ec.gp

# Class ADF

java.lang.Object
ec.gp.GPNode
ec.gp.ADF

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

Direct Known Subclasses:
  `ADM`

public class ADF extends GPNode
An ADF is a GPNode which implements an "Automatically Defined Function", as described in Koza II.

In this system, the ADF facility consists of several classes: ADF, ADM, ADFStack, ADFContext, and ADFArgument. ADFs, and their cousins ADMs ("Automatically Defined Macros [Lee Spector]"), appear as typical function nodes in a GP tree. However, they have a special associated tree in the individual's tree forest which they evaluate as a kind of a "subfunction".

When an ADF is evaluated, it first evaluates all of its children and stores away their results. It then evaluates its associated tree. In the associated tree may exist one or more ADF Argument Terminals, defined by the ADFArgument class. These terminal nodes are associated with a single number which represents the "argument" in the original ADF which evaluated their tree. When an Argument Terminal is evaluated, it returns the stored result for that child number in the parent ADF. Ultimately, when the associated tree completes its evaluation, the ADF returns that value.

ADMs work slightly differently. When an ADM is evaluated, it immediately evaluates its associated tree without first evaluating any children. When an Argument Terminal is evaluated, it evaluates the subtree of the appropriate child number in the parent ADM and returns that result. These subtrees can be evaluated many times. When the associated tree completes its evaluation, the ADM returns that value.

Obviously, if you have Argument Terminals in a tree, that tree must be only callable by ADFs and ADMs, otherwise the Argument Terminals won't have anything to return. Furthermore, you must make sure that you don't have an Argument Terminal in a tree whose number is higher than the smallest arity (number of arguments) of a calling ADF or ADM.

The mechanism behind ADFs and ADMs is complex, requiring two specially- stored stacks (contained in the ADFStack object) of ADFContexts. For information on how this mechanism works, see ADFStack.

Parameters

base.`tree` int >= 0 | (The "associated tree" of the ADF)
base.`name` String, can be undefined | (A simple "name" of the ADF to distinguish it from other ADF functions in your function set. Use only letters, numbers, hyphens, and underscores. Lowercase is best.)

Default Base
gp.adf

See Also:
  - `ADFStack`
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `int`
  `associatedTree`
  The ADF's associated tree
  `String`
  `name`
  The "function name" of the ADF, to distinguish it from other GP functions you might provide.
  `static final String`
  `P_ADF`
  `static final String`
  `P_ASSOCIATEDTREE`
  `static final String`
  `P_FUNCTIONNAME`

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

  `argposition, children, CHILDREN_UNKNOWN, constraints, GPNODEPRINTTAB, MAXPRINTBYTES, NODESEARCH_ALL, NODESEARCH_NONTERMINALS, NODESEARCH_TERMINALS, P_NODE, P_NODECONSTRAINTS, parent`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ADF()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `checkConstraints(EvolutionState state, int tree, GPIndividual typicalIndividual, Parameter individualBase)`
  Checks type-compatibility constraints between the ADF, its argument terminals, and the tree type of its associated tree, and also checks to make sure the tree exists, there aren't invalid argument terminals in it, and there are sufficient argument terminals (a warning).
  `Parameter`
  `defaultBase()`
  The default base for GPNodes -- defined even though GPNode is abstract so you don't have to in subclasses.
  `void`
  `eval(EvolutionState state, int thread, GPData input, ADFStack stack, GPIndividual individual, Problem problem)`
  Evaluates the node with the given thread, state, individual, problem, and stack.
  `String`
  `name()`
  Returns a Lisp-like atom for the node and any nodes of the same class.
  `boolean`
  `nodeEquals(GPNode node)`
  Determines node equality by comparing the class, associated tree, and function name of the nodes.
  `int`
  `nodeHashCode()`
  Returns name.hashCode() + class.hashCode() + associatedTree.
  `void`
  `readNode(EvolutionState state, DataInput dataInput)`
  Override this to read any additional node-specific information from dataInput besides: the number of arguments, the specific node class, the children, and the parent.
  `void`
  `setup(EvolutionState state, Parameter base)`
  Sets up a prototypical GPNode with those features all nodes of that prototype share, and nothing more.
  `String`
  `toString()`
  Returns a Lisp-like atom for the node which can be read in again by computer.
  `void`
  `writeNode(EvolutionState state, DataOutput dataOutput)`
  Override this to write any additional node-specific information to dataOutput besides: the number of arguments, the specific node class, the children, and the parent.

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

  `atDepth, clone, cloneReplacing, cloneReplacing, cloneReplacing, cloneReplacingAtomic, cloneReplacingAtomic, cloneReplacingNoSubclone, constraints, contains, depth, errorInfo, expectedChildren, iterator, iterator, iterator, lightClone, makeCTree, makeGraphvizSubtree, makeGraphvizTree, makeLatexTree, makeLispTree, makeLispTree, nodeEquivalentTo, nodeInPosition, nodeInPosition, numNodes, numNodes, parentType, pathLength, printNode, printNode, printNode, printNodeForHumans, printNodeForHumans, printRootedTree, printRootedTree, printRootedTree, printRootedTreeForHumans, printRootedTreeForHumans, readNode, readRootedTree, readRootedTree, replaceWith, resetNode, rootedTreeEquals, rootedTreeHashCode, rootParent, swapCompatibleWith, toStringForError, toStringForHumans, writeRootedTree`

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

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

- ## Field Details

  - ### P_ADF

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

  - ### P_ASSOCIATEDTREE

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

  - ### P_FUNCTIONNAME

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

  - ### associatedTree

    public int associatedTree
    The ADF's associated tree

  - ### name

    public String name
    The "function name" of the ADF, to distinguish it from other GP functions you might provide.

- ## Constructor Details

  - ### ADF

    public ADF()

- ## Method Details

  - ### name

    public String name()
    Description copied from class: `GPNode`
    Returns a Lisp-like atom for the node and any nodes of the same class. This will almost always be identical to the result of toString() (and the default does exactly this), but for ERCs it'll be different: toString will include the encoded constant data, whereas name() will not include this information and will be the same for all ERCs of this type. If two nodes are nodeEquivalentTo(...) each other, then they will have the same name(). If two nodes are nodeEquals(...) each other, then they will have the same toString().
    Overrides:
      `name` in class `GPNode`

  - ### defaultBase

    public Parameter defaultBase()
    Description copied from class: `GPNode`
    The default base for GPNodes -- defined even though GPNode is abstract so you don't have to in subclasses.
    Specified by:
      `defaultBase` in interface `Prototype`
    Overrides:
      `defaultBase` in class `GPNode`

  - ### writeNode

    public void writeNode(EvolutionState state, DataOutput dataOutput) throws IOException
    Description copied from class: `GPNode`
    Override this to write any additional node-specific information to dataOutput besides: the number of arguments, the specific node class, the children, and the parent. The default version of this method does nothing.
    Overrides:
      `writeNode` in class `GPNode`
    Throws:
      `IOException`

  - ### readNode

    public void readNode(EvolutionState state, DataInput dataInput) throws IOException
    Description copied from class: `GPNode`
    Override this to read any additional node-specific information from dataInput besides: the number of arguments, the specific node class, the children, and the parent. The default version of this method does nothing.
    Overrides:
      `readNode` in class `GPNode`
    Throws:
      `IOException`

  - ### nodeHashCode

    public int nodeHashCode()
    Returns name.hashCode() + class.hashCode() + associatedTree. Hope that's reasonably random.
    Overrides:
      `nodeHashCode` in class `GPNode`

  - ### nodeEquals

    public boolean nodeEquals(GPNode node)
    Determines node equality by comparing the class, associated tree, and function name of the nodes.
    Overrides:
      `nodeEquals` in class `GPNode`

  - ### checkConstraints

    public void checkConstraints(EvolutionState state, int tree, GPIndividual typicalIndividual, Parameter individualBase)
    Checks type-compatibility constraints between the ADF, its argument terminals, and the tree type of its associated tree, and also checks to make sure the tree exists, there aren't invalid argument terminals in it, and there are sufficient argument terminals (a warning). Whew!
    Overrides:
      `checkConstraints` in class `GPNode`

  - ### setup

    public void setup(EvolutionState state, Parameter base)
    Description copied from class: `GPNode`
    Sets up a prototypical GPNode with those features all nodes of that prototype share, and nothing more. So no filled-in children, no argposition, no parent. Yet. 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. You should override this if you need to load some special features on a per-function basis. Note that base hangs off of a function set, so this method may get called for different instances in the same GPNode class if they're being set up as prototypes for different GPFunctionSets. If you absolutely need some global base, then you should use something hanging off of GPDefaults.base(). The ultimate caller of this method must guarantee that he will eventually call state.output.exitIfErrors(), so you can freely use state.output.error instead of state.output.fatal(), which will help a lot.
    Specified by:
      `setup` in interface `Prototype`
    Specified by:
      `setup` in interface `Setup`
    Overrides:
      `setup` in class `GPNode`

  - ### toString

    public String toString()
    Description copied from class: `GPNode`
    Returns a Lisp-like atom for the node which can be read in again by computer. If you need to encode an integer or a float or whatever for some reason (perhaps if it's an ERC), you should use the ec.util.Code library.
    Specified by:
      `toString` in class `GPNode`

  - ### eval

    public void eval(EvolutionState state, int thread, GPData input, ADFStack stack, GPIndividual individual, Problem problem)
    Description copied from class: `GPNode`
    Evaluates the node with the given thread, state, individual, problem, and stack. Your random number generator will be state.random[thread]. The node should, as appropriate, evaluate child nodes with these same items passed to eval(...).

    About input: `input` is special; it is how data is passed between parent and child nodes. If children "receive" data from their parent node when it evaluates them, they should receive this data stored in `input`. If (more likely) the parent "receives" results from its children, it should pass them an `input` object, which they'll fill out, then it should check this object for the returned value.

    A tree is typically evaluated by dropping a GPData into the root. When the root returns, the resultant `input` should hold the return value.

    In general, you should not be creating new GPDatas. If you think about it, in most conditions (excepting ADFs and ADMs) you can use and reuse `input` for most communications purposes between parents and children.

    So, let's say that your GPNode function implements the boolean AND function, and expects its children to return return boolean values (as it does itself). You've implemented your GPData subclass to be, uh, BooleanData, which looks like ``

        public class BooleanData extends GPData
            {
            public boolean result;
            public GPData copyTo(GPData gpd)
              {
              ((BooleanData)gpd).result = result;
              }
            }

    ...so, you might implement your eval(...) function as follows: ``

        public void eval(final EvolutionState state,
                             final int thread,
                             final GPData input,
                             final ADFStack stack,
                             final GPIndividual individual,
                             final Problem problem
            {
            BooleanData dat = (BooleanData)input;
            boolean x;

            // evaluate the first child
            children[0].eval(state,thread,input,stack,individual,problem);

            // store away its result
            x = dat.result;

            // evaluate the second child
            children[1].eval(state,thread,input,stack,individual,problem);

            // return (in input) the result of the two ANDed

            dat.result = dat.result invalid input: '&'invalid input: '&' x;
            return;
            }

    Specified by:
      `eval` in class `GPNode`