Package ec

# Class Species

java.lang.Object
ec.Species

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

Direct Known Subclasses:
  `GPSpecies`, `RuleSpecies`, `VectorSpecies`

public abstract class Species extends Object implements Prototype
Species is a prototype which defines the features for a set of individuals in the population. Typically, individuals may breed if they belong to the same species (but it's not a hard-and-fast rule). Each Subpopulation has one Species object which defines the species for individuals in that Subpopulation.

Species are generally responsible for creating individuals, through their newIndividual(...) method. This method usually clones its prototypical individual and makes some additional modifications to the clone, then returns it. Note that the prototypical individual does not need to be a complete individual -- for example, GPSpecies holds a GPIndividual which doesn't have any trees (the tree roots are null).

Species also holds a prototypical breeding pipeline meant to breed this individual. To breed individuals of this species, clone the pipeline and use the clone.

Parameters

base.`ind` classname, inherits and != ec.Individual | (the class for the prototypical individual for the species)
base.`fitness` classname, inherits and != ec.Fitness | (the class for the prototypical fitness for the species)
base.`numpipes` int >= 1 | (total number of breeding pipelines for the species)
base.`pipe` classname, inherits and != ec.BreedingSource | (the class for the prototypical Breeding Source)

Parameter bases

base.`ind` | i_prototype (the prototypical individual)
base.`pipe` | pipe_prototype (breeding source prototype)
base.`fitness` | f_prototype (the prototypical fitness)

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `Fitness`
  `f_prototype`
  The prototypical fitness for individuals of this species.
  `Individual`
  `i_prototype`
  The prototypical individual for this species.
  `static final String`
  `P_FITNESS`
  `static final String`
  `P_INDIVIDUAL`
  `static final String`
  `P_PIPE`
  `BreedingSource`
  `pipe_prototype`
  The prototypical breeding pipeline for this species.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Species()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `HashMap<String,Object>`
  `buildMisc(EvolutionState state, int subpopIndex, int thread)`
  Called whenever the Breeder calls produce(...) on a BreedingPipeline, in order to pass a new "misc" object.
  `Object`
  `clone()`
  Creates a new individual cloned from a prototype, and suitable to begin use in its own evolutionary context.
  `Individual`
  `newIndividual(EvolutionState state, int thread)`
  Provides a brand-new individual to fill in a population.
  `Individual`
  `newIndividual(EvolutionState state, DataInput dataInput)`
  Provides an individual read from a DataInput source, including the fitness.
  `Individual`
  `newIndividual(EvolutionState state, LineNumberReader reader)`
  Provides an individual read from a stream, including the fitness; the individual will appear as it was written by printIndividual(...).
  `void`
  `setup(EvolutionState state, Parameter base)`
  The default version of setup(...) loads requested pipelines and calls setup(...) on them and normalizes their probabilities.
  `void`
  `updateIndividual(EvolutionState state, Individual ind)`
  A hook for code that is run on every individual as soon as it is evaluated.
  `void`
  `updateSubpopulation(EvolutionState state, Subpopulation subpop)`
  A hook for code that is run on the entire subpopulation as soon as it has been evaluated.

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

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

  ### Methods inherited from interface ec.Prototype

  `defaultBase`

- ## Field Details

  - ### P_INDIVIDUAL

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

  - ### P_PIPE

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

  - ### P_FITNESS

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

  - ### i_prototype

    public Individual i_prototype
    The prototypical individual for this species.

  - ### pipe_prototype

    public BreedingSource pipe_prototype
    The prototypical breeding pipeline for this species.

  - ### f_prototype

    public Fitness f_prototype
    The prototypical fitness for individuals of this species.

- ## Constructor Details

  - ### Species

    public Species()

- ## Method Details

  - ### clone

    public 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.

    Typically this should be a full "deep" clone. However, you may share certain elements with other objects rather than clone hem, 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 Populations, or Subpopulation.
    - 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 clone(), and you have no need to do clone deeply, and you are abstract, then you should not declare clone().
    - If no ancestor of yours implements clone(), and you have no need to do clone deeply, and you are not abstract, then you should implement it as follows:

      ``

           public Object clone()
               {
               try
                   {
                   return super.clone();
                   }
               catch ((CloneNotSupportedException e)
                   { throw new InternalError(); } // never happens
               }

    - If no ancestor of yours implements clone(), but you need to deep-clone some things, then you should implement it as follows:

      ``

           public Object clone()
               {
               try
                   {
                   MyObject myobj = (MyObject) (super.clone());

                   // put your deep-cloning code here...
                   }
               catch ((CloneNotSupportedException e)
                   { throw new InternalError(); } // never happens
               return myobj;
               }

    - If an ancestor has implemented clone(), and you also need to deep clone some things, then you should implement it as follows:

      ``

           public Object clone()
               {
               MyObject myobj = (MyObject) (super.clone());

               // put your deep-cloning code here...

               return myobj;
               }

    Specified by:
      `clone` in interface `Prototype`
    Overrides:
      `clone` in class `Object`

  - ### buildMisc

    public HashMap<String,Object> buildMisc(EvolutionState state, int subpopIndex, int thread)
    Called whenever the Breeder calls produce(...) on a BreedingPipeline, in order to pass a new "misc" object. Customize this as you see fit: the default just builds an empty hashmap.

  - ### newIndividual

    public Individual newIndividual(EvolutionState state, int thread)
    Provides a brand-new individual to fill in a population. The default form simply calls clone(), creates a fitness, sets evaluated to false, and sets the species. If you need to make a more custom genotype (as is the case for GPSpecies, which requires a light rather than deep clone), you will need to override this method as you see fit.

  - ### newIndividual

    public Individual newIndividual(EvolutionState state, LineNumberReader reader) throws IOException
    Provides an individual read from a stream, including the fitness; the individual will appear as it was written by printIndividual(...). Doesn't close the stream. Sets evaluated to false and sets the species. If you need to make a more custom mechanism (as is the case for GPSpecies, which requires a light rather than deep clone), you will need to override this method as you see fit.
    Throws:
      `IOException`

  - ### newIndividual

    public Individual newIndividual(EvolutionState state, DataInput dataInput) throws IOException
    Provides an individual read from a DataInput source, including the fitness. Doesn't close the DataInput. Sets evaluated to false and sets the species. If you need to make a more custom mechanism (as is the case for GPSpecies, which requires a light rather than deep clone), you will need to override this method as you see fit.
    Throws:
      `IOException`

  - ### setup

    public void setup(EvolutionState state, Parameter base)
    The default version of setup(...) loads requested pipelines and calls setup(...) on them and normalizes their probabilities. If your individual prototype might need to know special things about the species (like parameters stored in it), then when you override this setup method, you'll need to set those parameters BEFORE you call super.setup(...), because the setup(...) code in Species sets up the prototype.
    Specified by:
      `setup` in interface `Prototype`
    Specified by:
      `setup` in interface `Setup`
    See Also:
      - `Prototype.setup(EvolutionState,Parameter)`

  - ### updateIndividual

    public void updateIndividual(EvolutionState state, Individual ind)
    A hook for code that is run on every individual as soon as it is evaluated. This method does nothing unless it is override by a subclass. For example, an implementation of Ant Colony System might use this to apply a local pheromone update.
    See Also:
      - `SimpleEvaluator`

  - ### updateSubpopulation

    public void updateSubpopulation(EvolutionState state, Subpopulation subpop)
    A hook for code that is run on the entire subpopulation as soon as it has been evaluated. For example, an implementation of Ant System might use this to apply a global pheromone update. You can see how this method is used by having a look at SimpleEvaluator.