Selector.java
01 /*
02  * Java Genetic Algorithm Library (jenetics-6.1.0).
03  * Copyright (c) 2007-2020 Franz Wilhelmstötter
04  *
05  * Licensed under the Apache License, Version 2.0 (the "License");
06  * you may not use this file except in compliance with the License.
07  * You may obtain a copy of the License at
08  *
09  *      http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  * Author:
18  *    Franz Wilhelmstötter (franz.wilhelmstoetter@gmail.com)
19  */
20 package io.jenetics;
21 
22 import io.jenetics.util.ISeq;
23 import io.jenetics.util.Seq;
24 
25 /**
26  * Selectors are responsible for selecting a given number of individuals from
27  * the population. The selectors are used to divide the population into
28  * survivors and offspring. The selectors for offspring and for the survivors
29  * can be chosen independently.
30  <pre>{@code
31  * final Engine<DoubleGene, Double> engine = Engine
32  *     .builder(gtf, ff)
33  *     .offspringSelector(new RouletteWheelSelector<>())
34  *     .survivorsSelector(new TournamentSelector<>())
35  *     .build();
36  * }</pre>
37  *
38  @param <G> The gene type this GA evaluates,
39  @param <C> The result type (of the fitness function).
40  *
41  @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
42  @since 1.0
43  @version 4.0
44  */
45 @FunctionalInterface
46 public interface Selector<
47     extends Gene<?, G>,
48     extends Comparable<? super C>
49 {
50 
51     /**
52      * Select phenotypes from the Population.
53      *
54      @param population The population to select from.
55      @param count The number of phenotypes to select.
56      @param opt Determines whether the individuals with higher fitness values
57      *        or lower fitness values must be selected. This parameter determines
58      *        whether the GA maximizes or minimizes the fitness function.
59      @return The selected phenotypes (a new Population).
60      @throws NullPointerException if the arguments is {@code null}.
61      @throws IllegalArgumentException if the select count is smaller than zero.
62      */
63     ISeq<Phenotype<G, C>> select(
64         final Seq<Phenotype<G, C>> population,
65         final int count,
66         final Optimize opt
67     );
68 
69 }