JEvolution (JEvolution)
Date: 2013-03-21

evSOLve.JEvolution

## Class JEvolution

- java.lang.Object
- - evSOLve.JEvolution.JEvolution

-     public class JEvolution
      extends java.lang.Object

  A quite general implementation of Evolutionary Algorithms.
  Since:
    June 8, 2001
  Version:
    0.9.8 $Id: JEvolution.java 532 2013-03-20 18:55:18Z helmut $
  Author:
    Helmut A. Mayer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `generationCount` The number of currently completed generations.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addChromosome(Chromosome chromosome)` Add a JEvolution native or a custom Chromosome to the Genotype.
    `boolean` | `doesMaximization()` Returns status of optimization.
    `void` | `doEvolve()` The evolutionary cycle.
    `int` | `doEvolve(int stepGenerations)` Runs JEvolution for the specified number of generations.
    `java.util.Comparator` | `getFitnessComparator()` Returns the fitness comparator.
    `double` | `getFitnessThreshold()` Gives the fitness threshold of this evolutionary cycle.
    `boolean` | `getFreezer()` Gets the freezing state of the population.
    `java.util.List<Chromosome>` | `getGenotypeModel()` Returns the genotype used by JEvolution.
    `static JEvolution` | `getInstance()` Returns the singleton.
    `JEvolutionReporter` | `getJEvolutionReporter()` Access statistics.
    `evSOLve.JEvolution.Population` | `getLastPopulation()` Returns the current (last) population.
    `int` | `getMaximalGenerations()` Gives maximal number of generations.
    `int` | `getMinimalGenerations()` Gives minimal number of generations.
    `int` | `getOffspringCount()` Returns the number of offspring.
    `int` | `getParentCount()` Returns the number of parents.
    `SubPopulation` | `getSeedPopulation()` Returns the seedPopulation (may be empty).
    `double` | `getShuffleRate()` Returns the shuffle rate.
    `void` | `recordPopulation(java.lang.String fileName)` Deprecated.
    `void` | `restorePopulation(java.lang.String fileName)` Deprecated.
    `void` | `setFitnessThreshold(double fitnessThreshold)` Changes the fitness threshold.
    `void` | `setFreezer(boolean freeze)` Freezes the population starting with the next generation.
    `void` | `setMaximalGenerations(int maximalGenerations)` Changes maximal number of generations.
    `void` | `setMaximization(boolean maximization)` Sets status of optimization.
    `void` | `setMinimalGenerations(int minimalGenerations)` Changes minimal number of generations.
    `void` | `setPhenotype(Phenotype phenotype)` Set the Phenotype with all the problem-specific code.
    `void` | `setPopulationSize(int populationSize)` Changes population sizes.
    `void` | `setPopulationSize(int parentCount, int offspringCount)` Changes population sizes.
    `void` | `setSeedPopulation(SubPopulation seedPopulation)` Sets seed population.
    `void` | `setSelection(Selection selection)` Set Selection type.
    `void` | `setShuffleRate(double shuffleRate)` Sets the shuffle rate.
    `void` | `setSubPopulations(int subPopulationCount)` Sets the number of sub-populations (default = 1).

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

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

- - ### Field Detail

    - #### generationCount

          protected int generationCount

      The number of currently completed generations.

  - ### Method Detail

    - #### getInstance

          public static JEvolution getInstance()

      Returns the singleton.
      Returns:
        the single instance

    - #### doEvolve

          public void doEvolve()

      The evolutionary cycle. Each call of this method performs a complete run of JEvolution until termination, hence, calling it n times will result in n evolutionary runs.

    - #### doEvolve

          public int doEvolve(int stepGenerations)

      Runs JEvolution for the specified number of generations. If stepGenerations <= 0, this call is identical to doEvolve(). If the complete evolutionary run has terminated, the return value is 0. Whenever a termination criterion is reached JEvolution terminates, even when the number of step generations has NOT been completed. Calling this method after termination of a run simply starts a new run. Calling doEvolve() after a number of step generations will complete the run until termination.
      Returns:
        the total number of completed generations (0, if run has terminated)
      See Also:
        `doEvolve()`

    - #### addChromosome

          public void addChromosome(Chromosome chromosome)

      Add a JEvolution native or a custom Chromosome to the Genotype. This way a JEvolution genotype can contain an arbitrary number of Chromosomes, but for writing a proper Phenotype class, the user has to be aware of the order of the chromosomes which corresponds to the order of adding it to the genotype. There is no restriction on the type of Chromosomes, i.e., you can use different Chromosomes in a genotype. Crossover is done separately for each Chromosome (with specific parameters set by the user). You may also shuffle Chromosomes.
      Parameters:
        `chromosome` - JEvolution native or costum Chromosome
      See Also:
        `Phenotype.doOntogeny(java.util.List<evSOLve.JEvolution.chromosomes.Chromosome>)`, `setShuffleRate(double)`

    - #### getGenotypeModel

          public java.util.List<Chromosome> getGenotypeModel()

      Returns the genotype used by JEvolution. The returned genotype is identical to the one used by JEvolution to determine how each Individual's genotype is composed, so any changes to the returned Vector will change the genotype model.
      Returns:
        the structure of the genotype (a Vector of Chromosomes)
      See Also:
        `addChromosome(evSOLve.JEvolution.chromosomes.Chromosome)`

    - #### setPhenotype

          public void setPhenotype(Phenotype phenotype)

      Set the Phenotype with all the problem-specific code.
      Parameters:
        `phenotype` - Fitness code provided by user.

    - #### setSelection

          public void setSelection(Selection selection)

      Set Selection type.
      Parameters:
        `selection` - native or custom selection method

    - #### getParentCount

          public int getParentCount()

      Returns the number of parents.
      Returns:
        the number of parents (mu in ES)

    - #### getOffspringCount

          public int getOffspringCount()

      Returns the number of offspring.
      Returns:
        the number of offspring (lambda in ES)

    - #### setSubPopulations

          public void setSubPopulations(int subPopulationCount)
                                 throws JEvolutionException

      Sets the number of sub-populations (default = 1). The 'populationSize' is the size of each sub-population.
      Parameters:
        `subPopulationCount` - number of sub-populations
      Throws:
        `JEvolutionException` - count < 1

    - #### setPopulationSize

          public void setPopulationSize(int populationSize)
                                 throws JEvolutionException

      Changes population sizes.
      Parameters:
        `populationSize` - number of parents = number of offspring
      Throws:
        `JEvolutionException` - size < 0

    - #### setPopulationSize

          public void setPopulationSize(int parentCount,
                               int offspringCount)
                                 throws JEvolutionException

      Changes population sizes. If the number of parents is not equal to the number of offspring (mu, lambda)-selection will be done automatically.
      Parameters:
        `parentCount` - the number of parents (mu in ES)
        `offspringCount` - the number of offspring (lambda in ES)
      Throws:
        `JEvolutionException` - count < 0

    - #### getLastPopulation

          public evSOLve.JEvolution.Population getLastPopulation()

      Returns the current (last) population.
      Returns:
        seedPopulation the subpopulation of seed individuals
      See Also:
        `Population.getIndividual(int)`, `Individual.toFile(java.lang.String)`

    - #### getSeedPopulation

          public SubPopulation getSeedPopulation()

      Returns the seedPopulation (may be empty).
      Returns:
        seedPopulation the subpopulation of seed individuals
      See Also:
        `SubPopulation.addIndividual(evSOLve.JEvolution.Individual)`

    - #### setSeedPopulation

          public void setSeedPopulation(SubPopulation seedPopulation)

      Sets seed population. May be used to seed the start population with existing solutions (Individuals of previous runs). The size of the seed population is arbitrary, but it will be decimated to the set subpopulation size (GP flavor), if it is larger. If it is smaller, the start subpopulations are completed with random individuals.
      Parameters:
        `seedPopulation` - subpopulation of seed individuals
      See Also:
        `SubPopulation.addIndividual(evSOLve.JEvolution.Individual)`

    - #### recordPopulation

          public void recordPopulation(java.lang.String fileName)
                                throws java.io.IOException

      Deprecated.
      Writes the current (last) population to a file. This is useful for being able to store current evolution results and to continue the run in the future without starting from scratch.
      Parameters:
        `fileName` - name of the file whereto the current population is written
      Throws:
        `java.io.FileNotFoundException`
        `java.io.IOException`
      See Also:
        `Population.getIndividual(int)`, `Individual.toFile(java.lang.String)`

    - #### restorePopulation

          public void restorePopulation(java.lang.String fileName)
                                 throws java.io.IOException,
                                        java.lang.ClassNotFoundException

      Deprecated.
      Restores a population from a file, and uses this population as a seed population for a new evolution run. Note: Make sure to set up all JEvolution parameters (especially genotype and phenotype) BEFORE restoring the population using this method, as the restoration process needs correct parameters. It is not checked, if the restored population meets the parameter setup, e.g., you could restore the population of a run having evolved neural networks, and use it to evolve antennas, but this, of course, will lead to unpredictable behavior. The restoration of the population will only take effect before a new evolution run or after (a potential) current evolution run has terminated, but not in between an evolution run.
      Parameters:
        `fileName` - name of the file to restore the population from
      Throws:
        `java.io.FileNotFoundException`
        `java.io.IOException`
        `java.lang.ClassNotFoundException`
      See Also:
        `Individual.Individual(java.lang.String)`

    - #### setFreezer

          public void setFreezer(boolean freeze)

      Freezes the population starting with the next generation. The current generation is simply copied to the next generation, and nothing is altered (no mutation, no crosssover). This method may be called during a running JEvolution. It is not yet synchronized, as it seems unlikely that multiple tasks control a JEvolution. This method is very likely only useful in coevolutionary settings.
      Parameters:
        `freeze` - true, if population to be frozen

    - #### getFreezer

          public boolean getFreezer()

      Gets the freezing state of the population.
      Returns:
        true, if population is frozen

    - #### getMaximalGenerations

          public int getMaximalGenerations()

      Gives maximal number of generations.
      Returns:
        maximalGenerations generations per run

    - #### setMaximalGenerations

          public void setMaximalGenerations(int maximalGenerations)
                                     throws JEvolutionException

      Changes maximal number of generations.
      Parameters:
        `maximalGenerations` - generations per run
      Throws:
        `JEvolutionException` - meaningless number

    - #### getMinimalGenerations

          public int getMinimalGenerations()

      Gives minimal number of generations. This number of generations is always executed regardless of any other termination criteria.
      Returns:
        minimalGenerations minimal generations per run (default 0)

    - #### setMinimalGenerations

          public void setMinimalGenerations(int minimalGenerations)
                                     throws JEvolutionException

      Changes minimal number of generations. This number of generations is always executed regardless of any other termination criteria.
      Parameters:
        `minimalGenerations` - minimal generations per run (default 0)
      Throws:
        `JEvolutionException` - meaningless number

    - #### getFitnessThreshold

          public double getFitnessThreshold()

      Gives the fitness threshold of this evolutionary cycle. Above (below in case of minimization) (or equal to) this fitness evolution is halted. However, the minimal number of generations is always executed.
      Returns:
        the fitness value where evolution is terminated (default Double.MAX_VALUE or Double.MIN_VALUE)
      See Also:
        `setMinimalGenerations(int)`

    - #### setFitnessThreshold

          public void setFitnessThreshold(double fitnessThreshold)

      Changes the fitness threshold. Above (below in case of minimization) (or equal to) this fitness evolution is halted. However, the minimal number of generations is always executed.
      Parameters:
        `fitnessThreshold` - the fitness value to terminate evolution
      See Also:
        `setMinimalGenerations(int)`

    - #### getFitnessComparator

          public java.util.Comparator getFitnessComparator()

      Returns the fitness comparator.
      Returns:
        the fitness comparator

    - #### getShuffleRate

          public double getShuffleRate()

      Returns the shuffle rate.
      Returns:
        the probability to shuffle homologous chromosomes

    - #### setShuffleRate

          public void setShuffleRate(double shuffleRate)

      Sets the shuffle rate. Shuffling is only meaningful, if you use more than one Chromosome for your genotype. If Chromosomes are shuffled, equivalent Chromosomes are exchanged randomly between the parents with the given probability (= shuffle rate).
      Parameters:
        `shuffleRate` - the probability to shuffle homologous chromosomes
      See Also:
        `addChromosome(evSOLve.JEvolution.chromosomes.Chromosome)`

    - #### doesMaximization

          public boolean doesMaximization()

      Returns status of optimization.
      Returns:
        true, if maximization, false minimization

    - #### setMaximization

          public void setMaximization(boolean maximization)

      Sets status of optimization. Also changes 'fitnessThreshold' to the respective default value (Double.MAX_VALUE for maximization, Double.MIN_VALUE for minimization).
      Parameters:
        `maximization` - true, if maximization

    - #### getJEvolutionReporter

          public JEvolutionReporter getJEvolutionReporter()

      Access statistics.
      Returns:
        JAReporter the JA's bookkeeper