001/*
002 * Java Genetic Algorithm Library (jenetics-8.1.0).
003 * Copyright (c) 2007-2024 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 */
020package io.jenetics.engine;
021
022import java.util.concurrent.CompletableFuture;
023import java.util.concurrent.Future;
024import java.util.function.Function;
025
026import io.jenetics.Gene;
027import io.jenetics.Genotype;
028
029/**
030 * This class contains factory methods for creating commonly usable
031 * {@link Evaluator} implementations.
032 *
033 * @see Evaluator
034 *
035 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
036 * @version 8.0
037 * @since 5.0
038 */
039public final class Evaluators {
040        private Evaluators() {}
041
042        /**
043         * Return a new fitness evaluator, which evaluates <em>asynchronous</em>
044         * fitness functions.
045         *
046         * @see #completable(Function)
047         *
048         * @param fitness the asynchronous fitness function
049         * @param <G> the gene type
050         * @param <C> the fitness value type
051         * @return a new (asynchronous) fitness evaluator
052         * @throws NullPointerException if one of the arguments is {@code null}
053         */
054        public static <G extends Gene<?, G>, C extends Comparable<? super C>>
055        Evaluator<G, C>
056        async(final Function<? super Genotype<G>, ? extends Future<C>> fitness) {
057                return new FutureEvaluator<>(fitness);
058        }
059
060        /**
061         * Return a new fitness evaluator, which evaluates <em>asynchronous</em>
062         * fitness functions.
063         *
064         * @param fitness the asynchronous fitness function, working on the
065         *        <em>native</em> fitness domain
066         * @param decoder the decoder function for the fitness domain
067         * @param <T> the <em>native</em> fitness domain type
068         * @param <G> the gene type
069         * @param <C> the fitness value type
070         * @return a new (async) fitness evaluator
071         * @throws NullPointerException if one of the arguments is {@code null}
072         */
073        public static <T, G extends Gene<?, G>, C extends Comparable<? super C>>
074        Evaluator<G, C> async(
075                final Function<? super T, ? extends Future<C>> fitness,
076                final Function<? super Genotype<G>, ? extends T> decoder
077        ) {
078                return async(fitness.compose(decoder));
079        }
080
081        /**
082         * Return a new fitness evaluator, which evaluates <em>asynchronous</em>
083         * fitness functions.
084         *
085         * @param fitness the asynchronous fitness function, working on the
086         *        <em>native</em> fitness domain
087         * @param codec the codec used for transforming the fitness domain
088         * @param <T> the <em>native</em> fitness domain type
089         * @param <G> the gene type
090         * @param <C> the fitness value type
091         * @return a new (async) fitness evaluator
092         * @throws NullPointerException if one of the arguments is {@code null}
093         */
094        public static <T, G extends Gene<?, G>, C extends Comparable<? super C>>
095        Evaluator<G, C> async(
096                final Function<? super T, ? extends Future<C>> fitness,
097                final Codec<T, G> codec
098        ) {
099                return async(fitness, codec.decoder());
100        }
101
102        /**
103         * Return a new fitness evaluator, which evaluates <em>asynchronous</em>
104         * fitness functions.
105         *
106         * @see #async(Function)
107         *
108         * @param fitness the asynchronous fitness function
109         * @param <G> the gene type
110         * @param <C> the fitness value type
111         * @return a new (asynchronous) fitness evaluator
112         * @throws NullPointerException if one of the arguments is {@code null}
113         */
114        public static <G extends Gene<?, G>, C extends Comparable<? super C>>
115        Evaluator<G, C>
116        completable(
117                final Function<
118                        ? super Genotype<G>,
119                        ? extends CompletableFuture<C>> fitness
120        ) {
121                return new CompletableFutureEvaluator<>(fitness);
122        }
123
124        /**
125         * Return a new fitness evaluator, which evaluates <em>asynchronous</em>
126         * fitness functions.
127         *
128         * @param fitness the asynchronous fitness function, working on the
129         *        <em>native</em> fitness domain
130         * @param decoder the decoder function for the fitness domain
131         * @param <T> the <em>native</em> fitness domain type
132         * @param <G> the gene type
133         * @param <C> the fitness value type
134         * @return a new (async) fitness evaluator
135         * @throws NullPointerException if one of the arguments is {@code null}
136         */
137        public static <T, G extends Gene<?, G>, C extends Comparable<? super C>>
138        Evaluator<G, C> completable(
139                final Function<? super T, ? extends CompletableFuture<C>> fitness,
140                final Function<? super Genotype<G>, ? extends T> decoder
141        ) {
142                return completable(fitness.compose(decoder));
143        }
144
145        /**
146         * Return a new fitness evaluator, which evaluates <em>asynchronous</em>
147         * fitness functions.
148         *
149         * @param fitness the asynchronous fitness function, working on the
150         *        <em>native</em> fitness domain
151         * @param codec the codec used for transforming the fitness domain
152         * @param <T> the <em>native</em> fitness domain type
153         * @param <G> the gene type
154         * @param <C> the fitness value type
155         * @return a new (async) fitness evaluator
156         * @throws NullPointerException if one of the arguments is {@code null}
157         */
158        public static <T, G extends Gene<?, G>, C extends Comparable<? super C>>
159        Evaluator<G, C> completable(
160                final Function<? super T, ? extends CompletableFuture<C>> fitness,
161                final Codec<T, G> codec
162        ) {
163                return completable(fitness, codec.decoder());
164        }
165
166}