Module io.jenetics.base
Package io.jenetics.engine

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

java.lang.Object
io.jenetics.engine.Engine<G,C>
Type Parameters:
G - the gene type
C - the fitness result type
All Implemented Interfaces:
Evaluator<G,C>, Evolution<G,C>, EvolutionStreamable<G,C>
public final class Engine<G extends Gene<?,G>,C extends Comparable<? super C>> extends Object implements Evolution<G,C>, EvolutionStreamable<G,C>, Evaluator<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.gene().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.

Concurrency

By default, the engine uses the ForkJoinPool.commonPool() for executing the evolution steps and evaluating the fitness function concurrently. You can change the used execution services with the Engine.Builder.executor(Executor) method. If you want to use a different executor for evaluating the fitness functions, you have to set the Engine.Builder.fitnessExecutor(BatchExecutor). 
final Engine<DoubleGene, Double> engine = Engine
    .builder(...)
    // Using this execution service for parallelize the evolution steps.
    .executor(Executors.newFixedThreadPool(5))
    // Using one virtual thread for every fitness function evaluation.
    .fitnessExecutor(BatchExecutor.ofVirtualThreads())
    .build();
Since:
3.0
Version:
7.0
See Also:
Implementation Note:
This class is thread safe: The engine maintains no mutable state. Therefore, it is safe to create multiple evolution streams with one engine, which may be actually used in different threads.

  • Method Details

    • evolve

      public EvolutionResult<G,C> evolve(EvolutionStart<G,C> start)
      Description copied from interface: Evolution
      Perform one evolution step with the given evolution start object New phenotypes are created with the fitness function defined by this engine
      Specified by:
      evolve in interface Evolution<G extends Gene<?,G>,C extends Comparable<? super C>>
      Parameters:
      start - the evolution start object
      Returns:
      the evolution result
      See Also:

    • eval

      public ISeq<Phenotype<G,C>> eval(Seq<Phenotype<G,C>> population)
      Evaluates the fitness function of the given population with the configured Evaluator of this engine and returns a new population with its fitness value assigned.
      Specified by:
      eval in interface Evaluator<G extends Gene<?,G>,C extends Comparable<? super C>>
      Parameters:
      population - the population to evaluate
      Returns:
      a new population with assigned fitness values
      Throws:
      IllegalStateException - if the configured fitness function doesn't return a population with the same size as the input population. This exception is also thrown if one of the populations phenotype has no fitness value assigned.
      Since:
      5.0
      See Also:

    • stream

      public EvolutionStream<G,C> stream(Supplier<EvolutionStart<G,C>> start)
      Description copied from interface: EvolutionStreamable
      Create a new, possibly infinite, evolution stream with the given evolution start. If an empty Population is given, the engine's genotype factory is used for creating the population. The given population might be the result of another engine, and this method allows to start the evolution with the outcome of a different engine. The fitness function is replaced by the one defined for this engine.
      Specified by:
      stream in interface EvolutionStreamable<G extends Gene<?,G>,C extends Comparable<? super C>>
      Parameters:
      start - the data the evolution stream starts with
      Returns:
      a new infinite evolution stream

    • stream

      public EvolutionStream<G,C> stream(EvolutionInit<G> init)
      Description copied from interface: EvolutionStreamable
      Create a new, possibly infinite, evolution stream with the given initial value. If an empty Population is given, the engines genotype factory is used for creating the population. The given population might be the result of another engine, and this method allows to start the evolution with the outcome of a different engine. The fitness function is replaced by the one defined for this engine.
      Specified by:
      stream in interface EvolutionStreamable<G extends Gene<?,G>,C extends Comparable<? super C>>
      Parameters:
      init - the data the evolution stream is initialized with
      Returns:
      a new infinite evolution stream

    • genotypeFactory

      public Factory<Genotype<G>> genotypeFactory()
      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.

    • constraint

      public Constraint<G,C> constraint()
      Return the constraint of the evolution problem.
      Returns:
      the constraint of the evolution problem
      Since:
      5.0

    • survivorsSelector

      public Selector<G,C> survivorsSelector()
      Return the used survivor Selector of the GA.
      Returns:
      the used survivor Selector of the GA.

    • offspringSelector

      public Selector<G,C> offspringSelector()
      Return the used offspring Selector of the GA.
      Returns:
      the used offspring Selector of the GA.

    • alterer

      public Alterer<G,C> alterer()
      Return the used Alterer of the GA.
      Returns:
      the used Alterer of the GA.

    • offspringSize

      public int offspringSize()
      Return the number of selected offspring.
      Returns:
      the number of selected offspring

    • survivorsSize

      public int survivorsSize()
      The number of selected survivors.
      Returns:
      the number of selected survivors

    • populationSize

      public int populationSize()
      Return the number of individuals of a population.
      Returns:
      the number of individuals of a population

    • maximalPhenotypeAge

      public long maximalPhenotypeAge()
      Return the maximal allowed phenotype age.
      Returns:
      the maximal allowed phenotype age

    • optimize

      public Optimize optimize()
      Return the optimization strategy.
      Returns:
      the optimization strategy

    • clock

      public InstantSource clock()
      Return the InstantSource the engine is using for measuring the execution time.
      Returns:
      the clock used for measuring the execution time

    • executor

      public Executor executor()
      Return the Executor the engine is using for executing the evolution steps.
      Returns:
      the executor used for performing the evolution steps

    • interceptor

      public EvolutionInterceptor<G,C> interceptor()
      Return the evolution interceptor.
      Returns:
      the evolution result mapper
      Since:
      6.0

    • toBuilder

      public Engine.Builder<G,C> toBuilder()
      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 <G extends Gene<?, G>, C extends Comparable<? super C>> Engine.Builder<G,C> builder(Function<? super Genotype<G>,? extends C> ff, Factory<Genotype<G>> gtf)
      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
      gtf - the genotype factory
      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
      G - the gene type
      C - the fitness function result type
      Parameters:
      ff - the fitness evaluator
      codec - the problem codec
      Returns:
      a new engine builder
      Throws:
      NullPointerException - if one of the arguments is null.
      Since:
      3.2

    • 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

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