Evaluators.java
001 /*
002  * Java Genetic Algorithm Library (jenetics-6.2.0).
003  * Copyright (c) 2007-2021 Franz Wilhelmstötter
004  *
005  * Licensed under the Apache License, Version 2.0 (the "License");
006  * you may not use this file except in compliance with the License.
007  * You may obtain a copy of the License at
008  *
009  *      http://www.apache.org/licenses/LICENSE-2.0
010  *
011  * Unless required by applicable law or agreed to in writing, software
012  * distributed under the License is distributed on an "AS IS" BASIS,
013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014  * See the License for the specific language governing permissions and
015  * limitations under the License.
016  *
017  * Author:
018  *    Franz Wilhelmstötter (franz.wilhelmstoetter@gmail.com)
019  */
020 package io.jenetics.engine;
021 
022 import java.util.concurrent.CompletableFuture;
023 import java.util.concurrent.Executor;
024 import java.util.concurrent.Future;
025 import java.util.function.Function;
026 
027 import io.jenetics.Gene;
028 import io.jenetics.Genotype;
029 
030 /**
031  * This class contains factory methods for creating commonly usable
032  {@link Evaluator} implementations. By default, the evolution {@link Engine}
033  * uses the {@code concurrent} evaluators ({@link #concurrent(Function, Executor)}).
034  *
035  @see Evaluator
036  *
037  @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
038  @version 5.0
039  @since 5.0
040  */
041 public final class Evaluators {
042     private Evaluators() {}
043 
044     /**
045      * Return a new fitness evaluator, which evaluates the fitness function of
046      * the population serially in the main thread. Might be useful for testing
047      * purpose.
048      *
049      @param fitness the fitness function
050      @param <G> the gene type
051      @param <C> the fitness value type
052      @return a new serial fitness evaluator
053      @throws NullPointerException if the fitness {@code function} is {@code null}
054      */
055     public static <G extends Gene<?, G>, C extends Comparable<? super C>>
056     Evaluator<G, C>
057     serial(final Function<? super Genotype<G>, ? extends C> fitness) {
058         return concurrent(fitness, Runnable::run);
059     }
060 
061     /**
062      * Return a new fitness evaluator, which evaluates the fitness function of
063      * the population serially in the main thread. Might be useful for testing
064      * purpose.
065      *
066      @param fitness the fitness function
067      @param decoder the decoder function for the fitness domain
068      @param <T> the <em>native</em> fitness domain type
069      @param <G> the gene type
070      @param <C> the fitness value type
071      @return a new (concurrent) fitness evaluator
072      @throws NullPointerException if one of the arguments is {@code null}
073      */
074     public static <T, G extends Gene<?, G>, C extends Comparable<? super C>>
075     Evaluator<G, C> serial(
076         final Function<? super T, ? extends C> fitness,
077         final Function<? super Genotype<G>, ? extends T> decoder
078     ) {
079         return serial(fitness.compose(decoder));
080     }
081 
082     /**
083      * Return a new fitness evaluator, which evaluates the fitness function of
084      * the population serially in the main thread. Might be useful for testing
085      * purpose.
086      *
087      @param fitness the fitness function
088      @param codec the codec used for transforming the fitness domain
089      @param <T> the <em>native</em> fitness domain type
090      @param <G> the gene type
091      @param <C> the fitness value type
092      @return a new (concurrent) fitness evaluator
093      @throws NullPointerException if one of the arguments is {@code null}
094      */
095     public static <T, G extends Gene<?, G>, C extends Comparable<? super C>>
096     Evaluator<G, C> serial(
097         final Function<? super T, ? extends C> fitness,
098         final Codec<T, G> codec
099     ) {
100         return serial(fitness.compose(codec.decoder()));
101     }
102 
103     /**
104      * Return a new fitness evaluator, which evaluates the fitness function of
105      * the population (concurrently) with the given {@code executor}. This is
106      * the default evaluator used by the evolution engine.
107      *
108      @param fitness the fitness function
109      @param executor the {@code Executor} used for evaluating the fitness
110      *        function
111      @param <G> the gene type
112      @param <C> the fitness value type
113      @return a new (concurrent) fitness evaluator
114      @throws NullPointerException if one of the arguments is {@code null}
115      */
116     public static <G extends Gene<?, G>, C extends Comparable<? super C>>
117     Evaluator<G, C> concurrent(
118         final Function<? super Genotype<G>, ? extends C> fitness,
119         final Executor executor
120     ) {
121         return new ConcurrentEvaluator<>(fitness, executor);
122     }
123 
124     /**
125      * Return a new fitness evaluator, which evaluates the fitness function of
126      * the population (concurrently) with the given {@code executor}. This is
127      * the default evaluator used by the evolution engine.
128      *
129      @param fitness the fitness function, working on the <em>native</em>
130      *        fitness domain
131      @param decoder the decoder function for the fitness domain
132      @param executor the {@code Executor} used for evaluating the fitness
133      *        function
134      @param <T> the <em>native</em> fitness domain type
135      @param <G> the gene type
136      @param <C> the fitness value type
137      @return a new (concurrent) fitness evaluator
138      @throws NullPointerException if one of the arguments is {@code null}
139      */
140     public static <T, G extends Gene<?, G>, C extends Comparable<? super C>>
141     Evaluator<G, C> concurrent(
142         final Function<? super T, ? extends C> fitness,
143         final Function<? super Genotype<G>, ? extends T> decoder,
144         final Executor executor
145     ) {
146         return concurrent(fitness.compose(decoder), executor);
147     }
148 
149     /**
150      * Return a new fitness evaluator, which evaluates the fitness function of
151      * the population (concurrently) with the given {@code executor}. This is
152      * the default evaluator used by the evolution engine.
153      *
154      @param fitness the fitness function, working on the <em>native</em>
155      *        fitness domain
156      @param codec the codec used for transforming the fitness domain
157      @param executor the {@code Executor} used for evaluating the fitness
158      *        function
159      @param <T> the <em>native</em> fitness domain type
160      @param <G> the gene type
161      @param <C> the fitness value type
162      @return a new (concurrent) fitness evaluator
163      @throws NullPointerException if one of the arguments is {@code null}
164      */
165     public static <T, G extends Gene<?, G>, C extends Comparable<? super C>>
166     Evaluator<G, C> concurrent(
167         final Function<? super T, ? extends C> fitness,
168         final Codec<T, G> codec,
169         final Executor executor
170     ) {
171         return concurrent(fitness, codec.decoder(), executor);
172     }
173 
174     /**
175      * Return a new fitness evaluator, which evaluates <em>asynchronous</em>
176      * fitness functions.
177      *
178      @see #completable(Function)
179      *
180      @param fitness the asynchronous fitness function
181      @param <G> the gene type
182      @param <C> the fitness value type
183      @return a new (asynchronous) fitness evaluator
184      @throws NullPointerException if one of the arguments is {@code null}
185      */
186     public static <G extends Gene<?, G>, C extends Comparable<? super C>>
187     Evaluator<G, C>
188     async(final Function<? super Genotype<G>, ? extends Future<C>> fitness) {
189         return new FutureEvaluator<>(fitness);
190     }
191 
192     /**
193      * Return a new fitness evaluator, which evaluates <em>asynchronous</em>
194      * fitness functions.
195      *
196      @param fitness the asynchronous fitness function, working on the
197      *        <em>native</em> fitness domain
198      @param decoder the decoder function for the fitness domain
199      @param <T> the <em>native</em> fitness domain type
200      @param <G> the gene type
201      @param <C> the fitness value type
202      @return a new (async) fitness evaluator
203      @throws NullPointerException if one of the arguments is {@code null}
204      */
205     public static <T, G extends Gene<?, G>, C extends Comparable<? super C>>
206     Evaluator<G, C> async(
207         final Function<? super T, ? extends Future<C>> fitness,
208         final Function<? super Genotype<G>, ? extends T> decoder
209     ) {
210         return async(fitness.compose(decoder));
211     }
212 
213     /**
214      * Return a new fitness evaluator, which evaluates <em>asynchronous</em>
215      * fitness functions.
216      *
217      @param fitness the asynchronous fitness function, working on the
218      *        <em>native</em> fitness domain
219      @param codec the codec used for transforming the fitness domain
220      @param <T> the <em>native</em> fitness domain type
221      @param <G> the gene type
222      @param <C> the fitness value type
223      @return a new (async) fitness evaluator
224      @throws NullPointerException if one of the arguments is {@code null}
225      */
226     public static <T, G extends Gene<?, G>, C extends Comparable<? super C>>
227     Evaluator<G, C> async(
228         final Function<? super T, ? extends Future<C>> fitness,
229         final Codec<T, G> codec
230     ) {
231         return async(fitness, codec.decoder());
232     }
233 
234     /**
235      * Return a new fitness evaluator, which evaluates <em>asynchronous</em>
236      * fitness functions.
237      *
238      @see #async(Function)
239      *
240      @param fitness the asynchronous fitness function
241      @param <G> the gene type
242      @param <C> the fitness value type
243      @return a new (asynchronous) fitness evaluator
244      @throws NullPointerException if one of the arguments is {@code null}
245      */
246     public static <G extends Gene<?, G>, C extends Comparable<? super C>>
247     Evaluator<G, C>
248     completable(
249         final Function<
250             super Genotype<G>,
251             extends CompletableFuture<C>> fitness
252     ) {
253         return new CompletableFutureEvaluator<>(fitness);
254     }
255 
256     /**
257      * Return a new fitness evaluator, which evaluates <em>asynchronous</em>
258      * fitness functions.
259      *
260      @param fitness the asynchronous fitness function, working on the
261      *        <em>native</em> fitness domain
262      @param decoder the decoder function for the fitness domain
263      @param <T> the <em>native</em> fitness domain type
264      @param <G> the gene type
265      @param <C> the fitness value type
266      @return a new (async) fitness evaluator
267      @throws NullPointerException if one of the arguments is {@code null}
268      */
269     public static <T, G extends Gene<?, G>, C extends Comparable<? super C>>
270     Evaluator<G, C> completable(
271         final Function<? super T, ? extends CompletableFuture<C>> fitness,
272         final Function<? super Genotype<G>, ? extends T> decoder
273     ) {
274         return completable(fitness.compose(decoder));
275     }
276 
277     /**
278      * Return a new fitness evaluator, which evaluates <em>asynchronous</em>
279      * fitness functions.
280      *
281      @param fitness the asynchronous fitness function, working on the
282      *        <em>native</em> fitness domain
283      @param codec the codec used for transforming the fitness domain
284      @param <T> the <em>native</em> fitness domain type
285      @param <G> the gene type
286      @param <C> the fitness value type
287      @return a new (async) fitness evaluator
288      @throws NullPointerException if one of the arguments is {@code null}
289      */
290     public static <T, G extends Gene<?, G>, C extends Comparable<? super C>>
291     Evaluator<G, C> completable(
292         final Function<? super T, ? extends CompletableFuture<C>> fitness,
293         final Codec<T, G> codec
294     ) {
295         return completable(fitness, codec.decoder());
296     }
297 
298 }