Engine (Jenetics 3.8.0)

java.lang.Object
- org.jenetics.engine.Engine<G,C>

All Implemented Interfaces:

Function<EvolutionStart<G,C>,EvolutionResult<G,C>>
```
public final class Engine<G extends Gene<?,G>,C extends Comparable<? super C>>
extends Object
implements Function<EvolutionStart<G,C>,EvolutionResult<G,C>>
```
Genetic algorithm engine which is the main class. The following example shows the main steps in initializing and executing the GA.
public class RealFunction { // Definition of the fitness function. private static Double eval(final Genotype<DoubleGene> gt) { final double x = gt.getGene().doubleValue(); return cos(0.5 + sin(x))*cos(x); } public static void main(String[] args) { // Create/configuring the engine via its builder. final Engine<DoubleGene, Double> engine = Engine .builder( RealFunction::eval, DoubleChromosome.of(0.0, 2.0*PI)) .populationSize(500) .optimize(Optimize.MINIMUM) .alterers( new Mutator<>(0.03), new MeanAlterer<>(0.6)) .build(); // Execute the GA (engine). final Phenotype<DoubleGene, Double> result = engine.stream() // Truncate the evolution stream if no better individual could // be found after 5 consecutive generations. .limit(bySteadyFitness(5)) // Terminate the evolution after maximal 100 generations. .limit(100) .collect(toBestPhenotype()); } }
The architecture allows to decouple the configuration of the engine from the execution. The Engine is configured via the Engine.Builder class and can't be changed after creation. The actual evolution is performed by the EvolutionStream, which is created by the Engine.
This class is thread safe: No mutable state is maintained by the engine. Therefore it is save to create multiple evolution streams with one engine, which may be actually used in different threads.

Since:

3.0

Version:

3.7

Author:

Franz Wilhelmstötter

See Also:

Engine.Builder, EvolutionStart, EvolutionResult, EvolutionStream, EvolutionStatistics, Codec

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Engine.Builder<G extends Gene<?,G>,C extends Comparable<? super C>>
Builder class for building GA Engine instances.

Nested Classes
Modifier and Type	Class and Description
`static class`	`Engine.Builder<G extends Gene<?,G>,C extends Comparable<? super C>>` Builder class for building GA `Engine` instances.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`EvolutionResult<G,C>`	`apply(EvolutionStart<G,C> start)` This method is an alias for the `evolve(EvolutionStart)` method.
`Engine.Builder<G,C>`	`builder()` Create a new evolution `Engine.Builder` initialized with the values of the current evolution `Engine`.
`static <G extends Gene<?,G>,C extends Comparable<? super C>> Engine.Builder<G,C>`	`builder(Function<? super Genotype<G>,? extends C> ff, Chromosome<G> chromosome, Chromosome<G>... chromosomes)` Create a new evolution `Engine.Builder` with the given fitness function and chromosome templates.
`static <G extends Gene<?,G>,C extends Comparable<? super C>> Engine.Builder<G,C>`	`builder(Function<? super Genotype<G>,? extends C> ff, Factory<Genotype<G>> genotypeFactory)` Create a new evolution `Engine.Builder` with the given fitness function and genotype factory.
`static <T,G extends Gene<?,G>,C extends Comparable<? super C>> Engine.Builder<G,C>`	`builder(Function<? super T,? extends C> ff, Codec<T,G> codec)` Create a new evolution `Engine.Builder` with the given fitness function and problem `codec`.
`static <T,G extends Gene<?,G>,C extends Comparable<? super C>> Engine.Builder<G,C>`	`builder(Problem<T,G,C> problem)` Create a new evolution `Engine.Builder` for the given `Problem`.
`EvolutionResult<G,C>`	`evolve(EvolutionStart<G,C> start)` Perform one evolution step with the given evolution `start` object New phenotypes are created with the fitness function and fitness scaler defined by this engine
`EvolutionResult<G,C>`	`evolve(Population<G,C> population, long generation)` Perform one evolution step with the given `population` and `generation`.
`Alterer<G,C>`	`getAlterer()` Return the used `Alterer` of the GA.
`Clock`	`getClock()` Return the `Clock` the engine is using for measuring the execution time.
`Executor`	`getExecutor()` Return the `Executor` the engine is using for executing the evolution steps.
`Function<? super Genotype<G>,? extends C>`	`getFitnessFunction()` Return the fitness function of the GA engine.
`Function<? super C,? extends C>`	`getFitnessScaler()` Return the fitness scaler of the GA engine.
`Factory<Genotype<G>>`	`getGenotypeFactory()` Return the used genotype `Factory` of the GA.
`long`	`getMaximalPhenotypeAge()` Return the maximal allowed phenotype age.
`int`	`getOffspringCount()` Return the number of selected offsprings.
`Selector<G,C>`	`getOffspringSelector()` Return the used offspring `Selector` of the GA.
`Optimize`	`getOptimize()` Return the optimization strategy.
`int`	`getPopulationSize()` Return the number of individuals of a population.
`int`	`getSurvivorsCount()` The number of selected survivors.
`Selector<G,C>`	`getSurvivorsSelector()` Return the used survivor `Selector` of the GA.
`Iterator<EvolutionResult<G,C>>`	`iterator()` Create a new infinite evolution iterator with a newly created population.
`Iterator<EvolutionResult<G,C>>`	`iterator(EvolutionResult<G,C> result)` Create a new infinite evolution iterator starting with a previously evolved `EvolutionResult`.
`Iterator<EvolutionResult<G,C>>`	`iterator(Iterable<Genotype<G>> genotypes)` Create a new infinite evolution iterator with the given initial individuals.
`Iterator<EvolutionResult<G,C>>`	`iterator(Iterable<Genotype<G>> genotypes, long generation)` Create a new infinite evolution iterator with the given initial individuals.
`Iterator<EvolutionResult<G,C>>`	`iterator(Population<G,C> population)` Create a new infinite evolution iterator with the given initial population.
`Iterator<EvolutionResult<G,C>>`	`iterator(Population<G,C> population, long generation)` Create a new infinite evolution iterator with the given initial population.
`EvolutionStream<G,C>`	`stream()` Create a new infinite evolution stream with a newly created population.
`EvolutionStream<G,C>`	`stream(EvolutionResult<G,C> result)` Create a new `EvolutionStream` starting with a previously evolved `EvolutionResult`.
`EvolutionStream<G,C>`	`stream(Iterable<Genotype<G>> genotypes)` Create a new infinite evolution stream with the given initial individuals.
`EvolutionStream<G,C>`	`stream(Iterable<Genotype<G>> genotypes, long generation)` Create a new infinite evolution stream with the given initial individuals.
`EvolutionStream<G,C>`	`stream(Population<G,C> population)` Create a new infinite evolution stream with the given initial population.
`EvolutionStream<G,C>`	`stream(Population<G,C> population, long generation)` Create a new infinite evolution stream with the given initial population.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.function.Function
andThen, compose, identity

- Method Detail
  - evolve
```
public EvolutionResult<G,C> evolve(Population<G,C> population,
                                   long generation)
```
    Perform one evolution step with the given population and generation. New phenotypes are created with the fitness function and fitness scaler defined by this engine
    This method is thread-safe.
    
    Parameters:
    
    population - the population to evolve
    
    generation - the current generation; used for calculating the phenotype age.
    
    Returns:
    
    the evolution result
    
    Throws:
    
    NullPointerException - if the given population is null
    
    IllegalArgumentException - if the given generation is smaller then one
    
    See Also:
    
    evolve(EvolutionStart)
  - evolve
```
public EvolutionResult<G,C> evolve(EvolutionStart<G,C> start)
```
    Perform one evolution step with the given evolution start object New phenotypes are created with the fitness function and fitness scaler defined by this engine
    This method is thread-safe.
    
    Parameters:
    
    start - the evolution start object
    
    Returns:
    
    the evolution result
    
    Throws:
    
    NullPointerException - if the given evolution start is null
    
    Since:
    
    3.1
    
    See Also:
    
    evolve(org.jenetics.Population, long)
  - apply
```
public EvolutionResult<G,C> apply(EvolutionStart<G,C> start)
```
    This method is an alias for the evolve(EvolutionStart) method.
    
    Specified by:
    
    apply in interface Function<EvolutionStart<G extends Gene<?,G>,C extends Comparable<? super C>>,EvolutionResult<G extends Gene<?,G>,C extends Comparable<? super C>>>
    
    Since:
    
    3.1
  - iterator
```
public Iterator<EvolutionResult<G,C>> iterator()
```
    Create a new infinite evolution iterator with a newly created population. This is an alternative way for evolution. It lets the user start, stop and resume the evolution process whenever desired.
    
    Returns:
    
    a new infinite evolution iterator
  - stream
```
public EvolutionStream<G,C> stream()
```
    Create a new infinite evolution stream with a newly created population.
    
    Returns:
    
    a new evolution stream.
  - iterator
```
public Iterator<EvolutionResult<G,C>> iterator(Iterable<Genotype<G>> genotypes)
```
    Create a new infinite evolution iterator with the given initial individuals. If an empty Iterable is given, the engines genotype factory is used for creating the population.
    
    Parameters:
    
    genotypes - the initial individuals used for the evolution iterator. Missing individuals are created and individuals not needed are skipped.
    
    Returns:
    
    a new infinite evolution iterator
    
    Throws:
    
    NullPointerException - if the given genotypes is null.
  - stream
```
public EvolutionStream<G,C> stream(Iterable<Genotype<G>> genotypes)
```
    Create a new infinite evolution stream with the given initial individuals. If an empty Iterable is given, the engines genotype factory is used for creating the population.
    
    Parameters:
    
    genotypes - the initial individuals used for the evolution stream. Missing individuals are created and individuals not needed are skipped.
    
    Returns:
    
    a new evolution stream.
    
    Throws:
    
    NullPointerException - if the given genotypes is null.
    
    Since:
    
    3.7
  - iterator
```
public Iterator<EvolutionResult<G,C>> iterator(Iterable<Genotype<G>> genotypes,
                                               long generation)
```
    Create a new infinite evolution iterator with the given initial individuals. If an empty Iterable is given, the engines genotype factory is used for creating the population.
    
    Parameters:
    
    genotypes - the initial individuals used for the evolution iterator. Missing individuals are created and individuals not needed are skipped.
    
    generation - the generation the stream starts from; must be greater than zero.
    
    Returns:
    
    a new infinite evolution iterator
    
    Throws:
    
    NullPointerException - if the given genotypes is null.
    
    IllegalArgumentException - if the given generation is smaller then one
    
    Since:
    
    3.7
  - stream
```
public EvolutionStream<G,C> stream(Iterable<Genotype<G>> genotypes,
                                   long generation)
```
    Create a new infinite evolution stream with the given initial individuals. If an empty Iterable is given, the engines genotype factory is used for creating the population.
    
    Parameters:
    
    genotypes - the initial individuals used for the evolution stream. Missing individuals are created and individuals not needed are skipped.
    
    generation - the generation the stream starts from; must be greater than zero.
    
    Returns:
    
    a new evolution stream.
    
    Throws:
    
    NullPointerException - if the given genotypes is null.
    
    IllegalArgumentException - if the given generation is smaller then one
    
    Since:
    
    3.7
  - iterator
```
public Iterator<EvolutionResult<G,C>> iterator(Population<G,C> population)
```
    Create a new infinite evolution iterator with the given initial population. If an empty Population is given, the engines genotype factory is used for creating the population. The given population might be the result of an other engine and this method allows to start the evolution with the outcome of an different engine. The fitness function and the fitness scaler are replaced by the one defined for this engine.
    
    Parameters:
    
    population - the initial individuals used for the evolution iterator. Missing individuals are created and individuals not needed are skipped.
    
    Returns:
    
    a new infinite evolution iterator
    
    Throws:
    
    NullPointerException - if the given population is null.
    
    Since:
    
    3.7
  - stream
```
public EvolutionStream<G,C> stream(Population<G,C> population)
```
    Create a new infinite evolution stream with the given initial population. If an empty Population is given, the engines genotype factory is used for creating the population. The given population might be the result of an other engine and this method allows to start the evolution with the outcome of an different engine. The fitness function and the fitness scaler are replaced by the one defined for this engine.
    
    Parameters:
    
    population - the initial individuals used for the evolution stream. Missing individuals are created and individuals not needed are skipped.
    
    Returns:
    
    a new evolution stream.
    
    Throws:
    
    NullPointerException - if the given population is null.
  - iterator
```
public Iterator<EvolutionResult<G,C>> iterator(Population<G,C> population,
                                               long generation)
```
    Create a new infinite evolution iterator with the given initial population. If an empty Population is given, the engines genotype factory is used for creating the population. The given population might be the result of an other engine and this method allows to start the evolution with the outcome of an different engine. The fitness function and the fitness scaler are replaced by the one defined for this engine.
    
    Parameters:
    
    population - the initial individuals used for the evolution iterator. Missing individuals are created and individuals not needed are skipped.
    
    generation - the generation the iterator starts from; must be greater than zero.
    
    Returns:
    
    a new infinite evolution iterator
    
    Throws:
    
    NullPointerException - if the given population is null.
    
    IllegalArgumentException - if the given generation is smaller then one
  - stream
```
public EvolutionStream<G,C> stream(Population<G,C> population,
                                   long generation)
```
    Create a new infinite evolution stream with the given initial population. If an empty Population is given, the engines genotype factory is used for creating the population. The given population might be the result of an other engine and this method allows to start the evolution with the outcome of an different engine. The fitness function and the fitness scaler are replaced by the one defined for this engine.
    
    Parameters:
    
    population - the initial individuals used for the evolution stream. Missing individuals are created and individuals not needed are skipped.
    
    generation - the generation the stream starts from; must be greater than zero.
    
    Returns:
    
    a new evolution stream.
    
    Throws:
    
    NullPointerException - if the given population is null.
    
    IllegalArgumentException - if the given generation is smaller then one
  - iterator
```
public Iterator<EvolutionResult<G,C>> iterator(EvolutionResult<G,C> result)
```
    Create a new infinite evolution iterator starting with a previously evolved EvolutionResult. The iterator is initialized with the population of the given result and its total generation EvolutionResult.getTotalGenerations().
    
    Parameters:
    
    result - the previously evolved EvolutionResult
    
    Returns:
    
    a new evolution stream, which continues a previous one
    
    Throws:
    
    NullPointerException - if the given evolution result is null
    
    Since:
    
    3.7
  - stream
```
public EvolutionStream<G,C> stream(EvolutionResult<G,C> result)
```
    Create a new EvolutionStream starting with a previously evolved EvolutionResult. The stream is initialized with the population of the given result and its total generation EvolutionResult.getTotalGenerations().
    private static final Problem<Double, DoubleGene, Double> PROBLEM = Problem.of( x -> cos(0.5 + sin(x))*cos(x), codecs.ofScalar(DoubleRange.of(0.0, 2.0*PI)) ); private static final Engine<DoubleGene, Double> ENGINE = Engine.builder(PROBLEM) .optimize(Optimize.MINIMUM) .offspringSelector(new RouletteWheelSelector<>()) .build(); public static void main(final String[] args) throws IOException { // Result of the first evolution run. final EvolutionResult<DoubleGene, Double> rescue = ENGINE.stream() .limit(limit.bySteadyFitness(10)) .collect(EvolutionResult.toBestEvolutionResult()); // Save the result of the first run into a file. final Path path = Paths.get("result.bin"); IO.object.write(rescue, path); // Load the previous result and continue evolution. @SuppressWarnings("unchecked") final EvolutionResult<DoubleGene, Double> result = ENGINE .stream((EvolutionResult<DoubleGene, Double>)IO.object.read(path)) .limit(limit.bySteadyFitness(20)) .collect(EvolutionResult.toBestEvolutionResult()); System.out.println(result.getBestPhenotype()); }
    The example above shows how to save an EvolutionResult from a first run, save it to disk and continue the evolution.
    
    Parameters:
    
    result - the previously evolved EvolutionResult
    
    Returns:
    
    a new evolution stream, which continues a previous one
    
    Throws:
    
    NullPointerException - if the given evolution result is null
    
    Since:
    
    3.7
  - getFitnessFunction
```
public Function<? super Genotype<G>,? extends C> getFitnessFunction()
```
    Return the fitness function of the GA engine.
    
    Returns:
    
    the fitness function
  - getFitnessScaler
```
public Function<? super C,? extends C> getFitnessScaler()
```
    Return the fitness scaler of the GA engine.
    
    Returns:
    
    the fitness scaler
  - getGenotypeFactory
```
public Factory<Genotype<G>> getGenotypeFactory()
```
    Return the used genotype Factory of the GA. The genotype factory is used for creating the initial population and new, random individuals when needed (as replacement for invalid and/or died genotypes).
    
    Returns:
    
    the used genotype Factory of the GA.
  - getSurvivorsSelector
```
public Selector<G,C> getSurvivorsSelector()
```
    Return the used survivor Selector of the GA.
    
    Returns:
    
    the used survivor Selector of the GA.
  - getOffspringSelector
```
public Selector<G,C> getOffspringSelector()
```
    Return the used offspring Selector of the GA.
    
    Returns:
    
    the used offspring Selector of the GA.
  - getAlterer
```
public Alterer<G,C> getAlterer()
```
    Return the used Alterer of the GA.
    
    Returns:
    
    the used Alterer of the GA.
  - getOffspringCount
```
public int getOffspringCount()
```
    Return the number of selected offsprings.
    
    Returns:
    
    the number of selected offsprings
  - getSurvivorsCount
```
public int getSurvivorsCount()
```
    The number of selected survivors.
    
    Returns:
    
    the number of selected survivors
  - getPopulationSize
```
public int getPopulationSize()
```
    Return the number of individuals of a population.
    
    Returns:
    
    the number of individuals of a population
  - getMaximalPhenotypeAge
```
public long getMaximalPhenotypeAge()
```
    Return the maximal allowed phenotype age.
    
    Returns:
    
    the maximal allowed phenotype age
  - getOptimize
```
public Optimize getOptimize()
```
    Return the optimization strategy.
    
    Returns:
    
    the optimization strategy
  - getClock
```
public Clock getClock()
```
    Return the Clock the engine is using for measuring the execution time.
    
    Returns:
    
    the clock used for measuring the execution time
  - getExecutor
```
public Executor getExecutor()
```
    Return the Executor the engine is using for executing the evolution steps.
    
    Returns:
    
    the executor used for performing the evolution steps
  - builder
```
public Engine.Builder<G,C> builder()
```
    Create a new evolution Engine.Builder initialized with the values of the current evolution Engine. With this method, the evolution engine can serve as a template for a new one.
    
    Returns:
    
    a new engine builder
  - builder
```
public static <T,G extends Gene<?,G>,C extends Comparable<? super C>> Engine.Builder<G,C> builder(Problem<T,G,C> problem)
```
    Create a new evolution Engine.Builder for the given Problem.
    
    Type Parameters:
    
    T - the (native) argument type of the problem fitness function
    
    G - the gene type the evolution engine is working with
    
    C - the result type of the fitness function
    
    Parameters:
    
    problem - the problem to be solved by the evolution Engine
    
    Returns:
    
    Create a new evolution Engine.Builder
    
    Since:
    
    3.4
  - builder
```
public static <G extends Gene<?,G>,C extends Comparable<? super C>> Engine.Builder<G,C> builder(Function<? super Genotype<G>,? extends C> ff,
                                                                                                Factory<Genotype<G>> genotypeFactory)
```
    Create a new evolution Engine.Builder with the given fitness function and genotype factory.
    
    Type Parameters:
    
    G - the gene type
    
    C - the fitness function result type
    
    Parameters:
    
    ff - the fitness function
    
    genotypeFactory - the genotype factory
    
    Returns:
    
    a new engine builder
    
    Throws:
    
    NullPointerException - if one of the arguments is null.
  - builder
```
@SafeVarargs
public static <G extends Gene<?,G>,C extends Comparable<? super C>> Engine.Builder<G,C> builder(Function<? super Genotype<G>,? extends C> ff,
                                                                                                             Chromosome<G> chromosome,
                                                                                                             Chromosome<G>... chromosomes)
```
    Create a new evolution Engine.Builder with the given fitness function and chromosome templates.
    
    Type Parameters:
    
    G - the gene type
    
    C - the fitness function result type
    
    Parameters:
    
    ff - the fitness function
    
    chromosome - the first chromosome
    
    chromosomes - the chromosome templates
    
    Returns:
    
    a new engine builder
    
    Throws:
    
    NullPointerException - if one of the arguments is null.
  - builder
```
public static <T,G extends Gene<?,G>,C extends Comparable<? super C>> Engine.Builder<G,C> builder(Function<? super T,? extends C> ff,
                                                                                                  Codec<T,G> codec)
```
    Create a new evolution Engine.Builder with the given fitness function and problem codec.
    
    Type Parameters:
    
    T - the fitness function input type
    
    C - the fitness function result type
    
    G - the gene type
    
    Parameters:
    
    ff - the fitness function
    
    codec - the problem codec
    
    Returns:
    
    a new engine builder
    
    Throws:
    
    NullPointerException - if one of the arguments is null.
    
    Since:
    
    3.2

Class Engine<G extends Gene<?,G>,C extends Comparable<? super C>>

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.function.Function

Method Detail

evolve

evolve

apply

iterator

stream

iterator

stream

iterator

stream

iterator

stream

iterator

stream

iterator

stream

getFitnessFunction

getFitnessScaler

getGenotypeFactory

getSurvivorsSelector

getOffspringSelector

getAlterer

getOffspringCount

getSurvivorsCount

getPopulationSize

getMaximalPhenotypeAge

getOptimize

getClock

getExecutor

builder

builder

builder

builder

builder