ec
Class Individual

java.lang.Object
  extended byec.Individual
All Implemented Interfaces:
java.lang.Cloneable, Prototype, java.io.Serializable, Setup
Direct Known Subclasses:
GPIndividual, RuleIndividual, VectorIndividual

public abstract class Individual
extends java.lang.Object
implements Prototype

An Individual is an item in the EC population stew which is evaluated and assigned a fitness which determines its likelihood of selection. Individuals are created most commonly by the newIndividual(...) method of the ec.Species class.

In general Individuals are immutable. That is, once they are created they should not be modified. This protocol helps insure that they are safe to read under multithreaded conditions. You can violate this protocol, but try to do so when you know you have only have a single thread.

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

See Also:
Serialized Form

Field Summary
 boolean evaluated
          Has the individual been evaluated and its fitness determined yet?
static java.lang.String EVALUATED_PREAMBLE
          A string appropriate to put in front of whether or not the individual has been printed.
 Fitness fitness
          The fitness of the Individual.
 Species species
          The species of the Individual.
 
Constructor Summary
Individual()
           
 
Method Summary
 java.lang.Object clone()
          Creates a new individual cloned from a prototype, and suitable to begin use in its own evolutionary context.
abstract  boolean equals(java.lang.Object ind)
          Returns true if I am genetically "equal" to ind.
 java.lang.String genotypeToString()
          Print to a string the genotype of the Individual in a fashion intended to be parsed in again via parseGenotype(...).
 java.lang.String genotypeToStringForHumans()
          Print to a string the genotype of the Individual in a fashion readable by humans, and not intended to be parsed in again.
abstract  int hashCode()
          Returns a hashcode for the individual, such that individuals which are equals(...) each other always return the same hash code.
protected  void parseGenotype(EvolutionState state, java.io.LineNumberReader reader)
          This method is used only by the default version of readIndividual(state,reader), and it is intended to be overridden to parse in that part of the individual that was outputted in the genotypeToString() method.
 void printIndividual(EvolutionState state, int log, int verbosity)
          Should print the individual in a way that can be read by computer, including its fitness, using state.output.println(...,verbosity,log) You can get fitness to print itself at the appropriate time by calling fitness.printFitness(state,log,verbosity);
 void printIndividual(EvolutionState state, java.io.PrintWriter writer)
          Should print the individual in a way that can be read by computer, including its fitness.
 void printIndividualForHumans(EvolutionState state, int log, int verbosity)
          Should print the individual out in a pleasing way for humans, including its fitness, using state.output.println(...,verbosity,log) You can get fitness to print itself at the appropriate time by calling fitness.printFitnessForHumans(state,log,verbosity);
 void readGenotype(EvolutionState state, java.io.DataInput dataInput)
           
 void readIndividual(EvolutionState state, java.io.DataInput dataInput)
          Reads the binary form of an individual from a DataInput.
 void readIndividual(EvolutionState state, java.io.LineNumberReader reader)
          Reads in the individual from a form printed by printIndividual().
 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.
 long size()
          Returns the "size" of the individual.
 java.lang.String toString()
          Overridden here because hashCode() is not expected to return the pointer to the object.
 void writeGenotype(EvolutionState state, java.io.DataOutput dataOutput)
           
 void writeIndividual(EvolutionState state, java.io.DataOutput dataOutput)
          Writes the binary form of an individual out to a DataOutput.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface ec.Prototype
defaultBase
 

Field Detail

EVALUATED_PREAMBLE

public static final java.lang.String EVALUATED_PREAMBLE
A string appropriate to put in front of whether or not the individual has been printed.

See Also:
Constant Field Values

fitness

public Fitness fitness
The fitness of the Individual.


species

public Species species
The species of the Individual.


evaluated

public boolean evaluated
Has the individual been evaluated and its fitness determined yet?

Constructor Detail

Individual

public Individual()
Method Detail

clone

public java.lang.Object clone()
Description copied from interface: Prototype
Creates a new individual cloned from a prototype, and suitable to begin use in its own evolutionary context.

The question here is whether or not this means to perform a "deep" or "light" ("shallow") clone, or something in-between. You may need to deep-clone parts of your object rather than simply copying their references, depending on the situation:

  • If you hold objects which are shared with other instances, don't clone them.
  • If you hold objects which must be unique, clone them.
  • If you hold objects which were given to you as a gesture of kindness, and aren't owned by you, you probably shouldn't clone them.
  • DON'T attempt to clone: Singletons, Cliques, or Groups.
  • Arrays are not cloned automatically; you may need to clone an array if you're not sharing it with other instances. Arrays have the nice feature of being copyable by calling clone() on them.

Implementations.

  • If no ancestor of yours implements protoClone(), and you have no need to either (light cloning is fine with you), and you are abstract, then you should not declare protoClone().
  • If no ancestor of yours implements protoClone(), and you have no need to either (light cloning is fine with you), and you are not abstract, then you should implement it as follows:

            public Object protoClone() 
            { 
            return super.clone();
            }
            
  • If no ancestor of yours implements protoClone(), but you need to deep-clone some things, then you should implement it as follows:

            public Object protoClone() 
            {
            myobj = (MyObject) (super.clone());
    
            // put your deep-cloning code here...
            // ...you should use protoClone and not 
            // protoCloneSimple to clone subordinate objects...
            return myobj;
            } 
            
  • If you need to override an ancestors' implementation of protoClone, in order to do your own deep cloning as well, then you should implement it as follows:

            public Object protoClone() 
            {
            MyObject myobj = (MyObject)(super.protoClone());
    
            // put your deep-cloning code here...
            // ...you should use protoClone and not 
            // protoCloneSimple to clone subordinate objects...
            return myobj;
            } 
            

If you know that your superclasses will never change their protoClone() implementations, you might try inlining them in your overridden protoClone() method. But this is dangerous (though it yields a small net increase).

In general, you want to keep your deep cloning to an absolute minimum, so that you don't have to call protoClone() but one time.

The approach taken here is the fastest that I am aware of while still permitting objects to be specified at runtime from a parameter file. It would be faster to use the "new" operator; but that would require hard-coding that we can't do. Although using java.lang.Object.clone() entails an extra layer that deals with stripping away the "protected" keyword and also wrapping the exception handling (which is a BIG hit, about three times as slow as using "new"), it's still MUCH faster than using java.lang.Class.newInstance(), and also much faster than rolling our own Clone() method.

Specified by:
clone in interface Prototype

size

public long size()
Returns the "size" of the individual. This is used for things like parsimony pressure. The default form of this method returns 0 -- if you care about parsimony pressure, you'll need to override the default to provide a more descriptive measure of size.


equals

public abstract boolean equals(java.lang.Object ind)
Returns true if I am genetically "equal" to ind. This should mostly be interpreted as saying that we are of the same class and that we hold the same data. It should NOT be a pointer comparison.


hashCode

public abstract int hashCode()
Returns a hashcode for the individual, such that individuals which are equals(...) each other always return the same hash code.


toString

public java.lang.String toString()
Overridden here because hashCode() is not expected to return the pointer to the object. toString() normally uses hashCode() to print a unique identifier, and that's no longer the case. You're welcome to override this anyway you like to make the individual print out in a more lucid fashion.


genotypeToStringForHumans

public java.lang.String genotypeToStringForHumans()
Print to a string the genotype of the Individual in a fashion readable by humans, and not intended to be parsed in again. The fitness and evaluated flag should not be included. The default form simply calls toString(), but you'll probably want to override this to something else.


genotypeToString

public java.lang.String genotypeToString()
Print to a string the genotype of the Individual in a fashion intended to be parsed in again via parseGenotype(...). The fitness and evaluated flag should not be included. The default form simply calls toString(), which is almost certainly wrong, and you'll probably want to override this to something else.


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

printIndividualForHumans

public void printIndividualForHumans(EvolutionState state,
                                     int log,
                                     int verbosity)
Should print the individual out in a pleasing way for humans, including its fitness, using state.output.println(...,verbosity,log) You can get fitness to print itself at the appropriate time by calling fitness.printFitnessForHumans(state,log,verbosity);

The default form of this method simply prints out whether or not the individual has been evaluated, its fitness, and then Individual.genotypeToStringForHumans(). Feel free to override this to produce more sophisticated behavior.


printIndividual

public void printIndividual(EvolutionState state,
                            int log,
                            int verbosity)
Should print the individual in a way that can be read by computer, including its fitness, using state.output.println(...,verbosity,log) You can get fitness to print itself at the appropriate time by calling fitness.printFitness(state,log,verbosity);

The default form of this method simply prints out whether or not the individual has been evaluated, its fitness, and then Individual.genotypeToString(). Feel free to override this to produce more sophisticated behavior.


printIndividual

public void printIndividual(EvolutionState state,
                            java.io.PrintWriter writer)
Should print the individual in a way that can be read by computer, including its fitness. You can get fitness to print itself at the appropriate time by calling fitness.printFitness(state,log,writer); Usually you should try to use printIndividual(state,log,verbosity) instead -- use this method only if you can't print through the Output facility for some reason.

The default form of this method simply prints out whether or not the individual has been evaluated, its fitness, and then Individual.genotypeToString(). Feel free to override this to produce more sophisticated behavior.


readIndividual

public void readIndividual(EvolutionState state,
                           java.io.LineNumberReader reader)
                    throws java.io.IOException
Reads in the individual from a form printed by printIndividual(). The default simply reads in evaluation information, then fitness information, and then calls parseGenotype() (which you should implement). Or feel free to override this to produce more sophisticated behavior.

Throws:
java.io.IOException

parseGenotype

protected void parseGenotype(EvolutionState state,
                             java.io.LineNumberReader reader)
                      throws java.io.IOException
This method is used only by the default version of readIndividual(state,reader), and it is intended to be overridden to parse in that part of the individual that was outputted in the genotypeToString() method. The default version of this method exits the program with an "unimplemented" error. You'll want to override this method, or to override readIndividual(...) to not use this method.

Throws:
java.io.IOException

writeIndividual

public void writeIndividual(EvolutionState state,
                            java.io.DataOutput dataOutput)
                     throws java.io.IOException
Writes the binary form of an individual out to a DataOutput. This is not for serialization: the object should only write out the data relevant to the object sufficient to rebuild it from a DataInput. The Species will be reattached later, there's no need to write it. The default version simply writes the evaluated and fitness information and nothing else. Thus if (for example) your individual's genotype consists of an array of integers, you might do this:

        super.writeIndividual(state,dataOutput);
        dataOutput.writeInt(integers.length);
        for(int x=0;x

Throws:
java.io.IOException

writeGenotype

public void writeGenotype(EvolutionState state,
                          java.io.DataOutput dataOutput)
                   throws java.io.IOException
Throws:
java.io.IOException

readGenotype

public void readGenotype(EvolutionState state,
                         java.io.DataInput dataInput)
                  throws java.io.IOException
Throws:
java.io.IOException

readIndividual

public void readIndividual(EvolutionState state,
                           java.io.DataInput dataInput)
                    throws java.io.IOException
Reads the binary form of an individual from a DataInput. This is not for serialization: the object should only read in the data written out via printIndividual(state,dataInput). The Species will be reattached later, there's no need to read it. The default version simply reads the evaluated and fitness information and nothing else. Thus if (for example) your individual's genotype consists of an array of integers, you might do this:

        super.readIndividual(state,dataInput);
        integers = new int[dataInput.read(integers.length);
        for(int x=0;x

Throws:
java.io.IOException