Package ec.vector

# Class VectorSpecies

java.lang.Object
ec.Species
ec.vector.VectorSpecies

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

Direct Known Subclasses:
  `BitVectorSpecies`, `FloatVectorSpecies`, `GeneVectorSpecies`, `IntegerVectorSpecies`

public class VectorSpecies extends Species
VectorSpecies is a species which can create VectorIndividuals. Different VectorSpecies are used for different kinds of VectorIndividuals: a plain VectorSpecies is probably only applicable for BitVectorIndividuals.

VectorSpecies supports the following recombination methods:

- One-point crossover.
- Two-point crossover.
- Uniform crossover - inaccurately called "any-point".
- Line recombination - children are random points on a line between the two parents.
- Intermediate recombination - the value of each component of the vector is between the values of that component of the parent vectors.

Note that BitVectorIndividuals (which use VectorSpecies) and GeneVectorIndividuals (which use GeneVectorSpecies, a subclass of VectorSpecies) do not support Line or Intermediate Recombination.

Also note that for LongVectorIndividuals, there are certain values that will never be created by line and intermediate recombination, because the recombination is calculated using doubles and then rounded to the nearest long. For large enough values (but still smaller than the maximum long), the difference between one double and the next is greater than one.

VectorSpecies has three wasy to determine the initial size of the individual:

- A fixed size.
- Geometric distribution.
- Uniform distribution

If the algorithm used is the geometric distribution, the VectorSpecies starts at a minimum size and continues flipping a coin with a certain "resize probability", increasing the size each time, until the coin comes up tails (fails). The chunk size must be 1 in this case.

If the algorithm used is the uniform distribution, the VectorSpecies picks a random size between a provided minimum and maximum size, inclusive. The chunk size must be 1 in this case.

If the size is fixed, then you can also provide a "chunk size" which constrains the locations in which crossover can be performed (only along chunk boundaries). The genome size must be a multiple of the chunk size in this case.

VectorSpecies also contains a number of parameters guiding how the individual crosses over and mutates.

Per-Gene and Per-Segment Specification. VectorSpecies and its subclasses specify a lot of parameters, notably mutation and initialization parameters, in one of three ways. We will use the `mutation-probability` parameter as an example.

1. Globally for all genes in the genome. This is done by specifying:

   base.`mutation-probability`
   base.`max-gene`

   Note: you must provide these values even if you don't use them, as they're used as defaults by #2 and #3 below.

2. You may provide parameters for genes in segments (regions) along the genome. The idea is to allow you to specify large chunks of genes all having the same parameter features. To do this you must first specify how many segments there are:

   base.`num-segments`

   The segments then may be defined by either start or end indices of genes. This is controlled by specifying the value of:

   base.`segment-type`

   ...which can assume the value of start or end, with start being the default. The indices are defined using Java array style, i.e. the first gene has the index of 0, and the last gene has the index of genome-size - 1.

   Using this method, each segment is specified byj...

   base.`segment.`j`.start`
   base.`segment.`j`.mutation-probability` if segment-type value was chosen as start or by:

   base.`segment.`j`.end`
   base.`segment.`j`.mutation-probability` if segment-type value is equal to end.

3. You may parameters for each separate gene. This is done by specifying (for each gene location i you wish to specify)

   base.`mutation-probability`.i

Any settings for #3 override #2, and both override #1.

The only parameter which can be specified this way in VectorSpecies is at present `mutation-probability`. However a number of parameters are specified this way in subclasses.

Parameters

base.`genome-size` int >= 1 or one of: geometric, uniform | (size of the genome, or if 'geometric' or 'uniform', the algorithm used to size the initial genome)
base.`chunk-size` 1 <= int <= genome-size (default=1) | (the chunk size for crossover (crossover will only occur on chunk boundaries))
base.`geometric-prob` 0.0 <= double < 1.0 | (the coin-flip probability for increasing the initial size using the geometric distribution)
base.`min-initial-size` int >= 0 | (the minimum initial size of the genome)
base.`max-initial-size` int >= min-initial-size | (the maximum initial size of the genome)
base.`crossover-type` string, one of: one, two, any | (default crossover type (one-point, one-point-nonempty, two-point, two-point-nonempty, any-point (uniform), line, or intermediate)
base.`crossover-prob` 0.0 >= double >= 1.0 | (probability that a gene will get crossed over during any-point (uniform) or simulated binary crossover)
base.`line-extension` double >= 0.0 | (for line and intermediate recombination, how far along the line or outside of the hypercube children can be. If this value is zero, all children must be within the hypercube.)
base.`mutation-prob` or
base.`segment`.segment-number.`mutation-prob` or
base.`mutation-prob`.gene-number 0.0 <= double <= 1.0 | (probability that a gene will get mutated over default mutation)

Default Base
vector.species

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `C_ANY_POINT`
  `static final int`
  `C_GEOMETRIC`
  `static final int`
  `C_INTERMED_RECOMB`
  `static final int`
  `C_LINE_RECOMB`
  `static final int`
  `C_NONE`
  `static final int`
  `C_ONE_POINT`
  `static final int`
  `C_ONE_POINT_NO_NOP`
  `static final int`
  `C_SIMULATED_BINARY`
  `static final int`
  `C_TWO_POINT`
  `static final int`
  `C_TWO_POINT_NO_NOP`
  `static final int`
  `C_UNIFORM`
  `int`
  `chunksize`
  How big of chunks should we define for crossover?
  `int`
  `crossoverDistributionIndex`
  What should the SBX distribution index be?
  `double`
  `crossoverProbability`
  Probability that a gene will cross over -- ONLY used in V_ANY_POINT crossover
  `int`
  `crossoverType`
  What kind of crossover do we have?
  `protected int[]`
  `duplicateRetries`
  How often do we retry until we get a non-duplicate gene?
  `boolean`
  `dynamicInitialSize`
  Was the initial size determined dynamically?
  `double`
  `genomeIncreaseProbability`
  With what probability would our genome be at least 1 larger than it is now during initialization?
  `int`
  `genomeResizeAlgorithm`
  How should we reset the genome?
  `int`
  `genomeSize`
  How big of a genome should we create on initialization?
  `double`
  `lineDistance`
  How far along the long a child can be located for line or intermediate recombination
  `int`
  `maxInitialSize`
  What's the largest legal genome?
  `int`
  `minInitialSize`
  What's the smallest legal genome?
  `protected double[]`
  `mutationProbability`
  Probability that a gene will mutate, per gene.
  `static final String`
  `P_CHUNKSIZE`
  `static final String`
  `P_CROSSOVER_DISTRIBUTION_INDEX`
  `static final String`
  `P_CROSSOVERPROB`
  `static final String`
  `P_CROSSOVERTYPE`
  `static final String`
  `P_DUPLICATE_RETRIES`
  `static final String`
  `P_GENOMESIZE`
  `static final String`
  `P_GEOMETRIC_PROBABILITY`
  `static final String`
  `P_LINEDISTANCE`
  `static final String`
  `P_MUTATIONPROB`
  `static final String`
  `P_NUM_SEGMENTS`
  `static final String`
  `P_SEGMENT`
  `static final String`
  `P_SEGMENT_END`
  `static final String`
  `P_SEGMENT_START`
  `static final String`
  `P_SEGMENT_TYPE`
  `static final String`
  `P_UNIFORM_MAX`
  `static final String`
  `P_UNIFORM_MIN`
  `static final String`
  `P_VECTORSPECIES`
  `static final String`
  `V_ANY_POINT`
  `static final String`
  `V_GEOMETRIC`
  `static final String`
  `V_INTERMED_RECOMB`
  `static final String`
  `V_LINE_RECOMB`
  `static final String`
  `V_ONE_POINT`
  `static final String`
  `V_ONE_POINT_NO_NOP`
  `static final String`
  `V_SIMULATED_BINARY`
  `static final String`
  `V_TWO_POINT`
  `static final String`
  `V_TWO_POINT_NO_NOP`
  `static final String`
  `V_UNIFORM`

  ### Fields inherited from class ec.Species

  `f_prototype, i_prototype, P_FITNESS, P_INDIVIDUAL, P_PIPE, pipe_prototype`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `VectorSpecies()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected int`
  `contains(boolean[] array, boolean val)`
  Utility method: returns the first array slot which contains the given value, else -1.
  `protected int`
  `contains(double[] array, double val)`
  Utility method: returns the first array slot which contains the given value, else -1.
  `protected int`
  `contains(int[] array, int val)`
  Utility method: returns the first array slot which contains the given value, else -1.
  `protected int`
  `contains(long[] array, long val)`
  Utility method: returns the first array slot which contains the given value, else -1.
  `Parameter`
  `defaultBase()`
  Returns the default base for this prototype.
  `int`
  `duplicateRetries(int gene)`
  `protected boolean[]`
  `fill(boolean[] array, boolean val)`
  Utility method: fills the array with the given value and returns it.
  `protected double[]`
  `fill(double[] array, double val)`
  Utility method: fills the array with the given value and returns it.
  `protected int[]`
  `fill(int[] array, int val)`
  Utility method: fills the array with the given value and returns it.
  `protected long[]`
  `fill(long[] array, long val)`
  Utility method: fills the array with the given value and returns it.
  `protected void`
  `initializeGenomeSegmentsByEndIndices(EvolutionState state, Parameter base, Parameter def, int numSegments)`
  Looks up genome segments using end indices.
  `protected void`
  `initializeGenomeSegmentsByStartIndices(EvolutionState state, Parameter base, Parameter def, int numSegments)`
  Looks up genome segments using start indices.
  `protected void`
  `loadParametersForGene(EvolutionState state, int index, Parameter base, Parameter def, String postfix)`
  Called when VectorSpecies is setting up per-gene and per-segment parameters.
  `double`
  `mutationProbability(int gene)`
  `Individual`
  `newIndividual(EvolutionState state, int thread)`
  Provides a brand-new individual to fill in a population.
  `void`
  `setup(EvolutionState state, Parameter base)`
  The default version of setup(...) loads requested pipelines and calls setup(...) on them and normalizes their probabilities.
  `protected void`
  `setupGenome(EvolutionState state, Parameter base)`

  ### Methods inherited from class ec.Species

  `buildMisc, clone, newIndividual, newIndividual, updateIndividual, updateSubpopulation`

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

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

- ## Field Details

  - ### P_VECTORSPECIES

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

  - ### P_CROSSOVERTYPE

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

  - ### P_CHUNKSIZE

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

  - ### V_ONE_POINT

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

  - ### V_ONE_POINT_NO_NOP

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

  - ### V_TWO_POINT

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

  - ### V_TWO_POINT_NO_NOP

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

  - ### V_ANY_POINT

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

  - ### V_LINE_RECOMB

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

  - ### V_INTERMED_RECOMB

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

  - ### V_SIMULATED_BINARY

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

  - ### P_CROSSOVER_DISTRIBUTION_INDEX

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

  - ### P_MUTATIONPROB

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

  - ### P_CROSSOVERPROB

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

  - ### P_GENOMESIZE

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

  - ### P_LINEDISTANCE

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

  - ### V_GEOMETRIC

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

  - ### P_GEOMETRIC_PROBABILITY

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

  - ### V_UNIFORM

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

  - ### P_UNIFORM_MIN

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

  - ### P_UNIFORM_MAX

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

  - ### P_NUM_SEGMENTS

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

  - ### P_SEGMENT_TYPE

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

  - ### P_SEGMENT_START

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

  - ### P_SEGMENT_END

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

  - ### P_SEGMENT

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

  - ### P_DUPLICATE_RETRIES

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

  - ### C_ONE_POINT

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

  - ### C_ONE_POINT_NO_NOP

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

  - ### C_TWO_POINT

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

  - ### C_TWO_POINT_NO_NOP

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

  - ### C_ANY_POINT

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

  - ### C_LINE_RECOMB

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

  - ### C_INTERMED_RECOMB

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

  - ### C_SIMULATED_BINARY

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

  - ### C_NONE

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

  - ### C_GEOMETRIC

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

  - ### C_UNIFORM

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

  - ### duplicateRetries

    protected int[] duplicateRetries
    How often do we retry until we get a non-duplicate gene?

  - ### mutationProbability

    protected double[] mutationProbability
    Probability that a gene will mutate, per gene. This array is one longer than the standard genome length. The top element in the array represents the parameters for genes in genomes which have extended beyond the genome length.

  - ### crossoverProbability

    public double crossoverProbability
    Probability that a gene will cross over -- ONLY used in V_ANY_POINT crossover

  - ### crossoverType

    public int crossoverType
    What kind of crossover do we have?

  - ### genomeSize

    public int genomeSize
    How big of a genome should we create on initialization?

  - ### crossoverDistributionIndex

    public int crossoverDistributionIndex
    What should the SBX distribution index be?

  - ### genomeResizeAlgorithm

    public int genomeResizeAlgorithm
    How should we reset the genome?

  - ### minInitialSize

    public int minInitialSize
    What's the smallest legal genome?

  - ### maxInitialSize

    public int maxInitialSize
    What's the largest legal genome?

  - ### genomeIncreaseProbability

    public double genomeIncreaseProbability
    With what probability would our genome be at least 1 larger than it is now during initialization?

  - ### chunksize

    public int chunksize
    How big of chunks should we define for crossover?

  - ### lineDistance

    public double lineDistance
    How far along the long a child can be located for line or intermediate recombination

  - ### dynamicInitialSize

    public boolean dynamicInitialSize
    Was the initial size determined dynamically?

- ## Constructor Details

  - ### VectorSpecies

    public VectorSpecies()

- ## Method Details

  - ### mutationProbability

    public double mutationProbability(int gene)

  - ### duplicateRetries

    public int duplicateRetries(int gene)

  - ### 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(...).

  - ### setupGenome

    protected void setupGenome(EvolutionState state, Parameter base)

  - ### setup

    public void setup(EvolutionState state, Parameter base)
    Description copied from class: `Species`
    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`
    Overrides:
      `setup` in class `Species`
    See Also:
      - `Prototype.setup(EvolutionState,Parameter)`

  - ### loadParametersForGene

    protected void loadParametersForGene(EvolutionState state, int index, Parameter base, Parameter def, String postfix)
    Called when VectorSpecies is setting up per-gene and per-segment parameters. The index is the current gene whose parameter is getting set up. The Parameters in question are the bases for the gene. The postfix should be appended to the end of any parameter looked up (it often contains a number indicating the gene in question), such as state.parameters.exists(base.push(P_PARAM).push(postfix), def.push(P_PARAM).push(postfix)

    If you override this method, be sure to call super(...) at some point, ideally first.

  - ### initializeGenomeSegmentsByStartIndices

    protected void initializeGenomeSegmentsByStartIndices(EvolutionState state, Parameter base, Parameter def, int numSegments)
    Looks up genome segments using start indices. Segments run up to the next declared start index.

  - ### initializeGenomeSegmentsByEndIndices

    protected void initializeGenomeSegmentsByEndIndices(EvolutionState state, Parameter base, Parameter def, int numSegments)
    Looks up genome segments using end indices. Segments run from the previously declared end index.

  - ### newIndividual

    public Individual newIndividual(EvolutionState state, int thread)
    Description copied from class: `Species`
    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.
    Overrides:
      `newIndividual` in class `Species`

  - ### fill

    protected long[] fill(long[] array, long val)
    Utility method: fills the array with the given value and returns it.

  - ### fill

    protected int[] fill(int[] array, int val)
    Utility method: fills the array with the given value and returns it.

  - ### fill

    protected boolean[] fill(boolean[] array, boolean val)
    Utility method: fills the array with the given value and returns it.

  - ### fill

    protected double[] fill(double[] array, double val)
    Utility method: fills the array with the given value and returns it.

  - ### contains

    protected int contains(boolean[] array, boolean val)
    Utility method: returns the first array slot which contains the given value, else -1.

  - ### contains

    protected int contains(long[] array, long val)
    Utility method: returns the first array slot which contains the given value, else -1.

  - ### contains

    protected int contains(int[] array, int val)
    Utility method: returns the first array slot which contains the given value, else -1.

  - ### contains

    protected int contains(double[] array, double val)
    Utility method: returns the first array slot which contains the given value, else -1.