Optimize.java
001 /*
002  * Java Genetic Algorithm Library (jenetics-6.1.0).
003  * Copyright (c) 2007-2020 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;
021 
022 import java.util.Comparator;
023 
024 /**
025  * This {@code enum} determines whether the GA should maximize or minimize the
026  * fitness function.
027  *
028  @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
029  @since 1.0
030  @version 3.0
031  */
032 public enum Optimize {
033 
034     /**
035      * GA minimization
036      */
037     MINIMUM {
038         @Override
039         public <T extends Comparable<? super T>>
040         int compare(final T a, final T b)
041         {
042             return b.compareTo(a);
043         }
044     },
045 
046     /**
047      * GA maximization
048      */
049     MAXIMUM {
050         @Override
051         public <T extends Comparable<? super T>>
052         int compare(final T a, final T b)
053         {
054             return a.compareTo(b);
055         }
056     };
057 
058     /**
059      * Compares two comparable objects. Returns a negative integer, zero, or a
060      * positive integer as the first argument is better than, equal to, or worse
061      * than the second.
062      *
063      @param <T> the comparable type
064      @param a the first object to be compared.
065      @param b the second object to be compared.
066      @return a negative integer, zero, or a positive integer as the first
067      *          argument is better than, equal to, or worse than the second.
068      @throws NullPointerException if one of the arguments is {@code null}.
069      */
070     public abstract <T extends Comparable<? super T>>
071     int compare(final T a, final T b);
072 
073     /**
074      * Create an appropriate comparator of the given optimization strategy. A
075      * collection of comparable objects with the returned comparator will be
076      * sorted in <b>descending</b> order, according to the given definition
077      * of <i>better</i> and <i>worse</i>.
078      *
079      <pre>{@code
080      * final Population<DoubleGene, Double> population = ...
081      * population.sort(Optimize.MINIMUM.<Double>descending());
082      * }</pre>
083      *
084      * The code example above will populationSort the population according it's fitness
085      * values in ascending order, since lower values are <i>better</i> in this
086      * case.
087      *
088      @param <T> the type of the objects to compare.
089      @return a new {@link Comparator} for the type {@code T}.
090      */
091     public <T extends Comparable<? super T>> Comparator<T> descending() {
092         return (a, b-> compare(b, a);
093     }
094 
095     /**
096      * Create an appropriate comparator of the given optimization strategy. A
097      * collection of comparable objects with the returned comparator will be
098      * sorted in <b>ascending</b> order, according to the given definition
099      * of <i>better</i> and <i>worse</i>.
100      *
101      <pre>{@code
102      * final Population<DoubleGene, Double> population = ...
103      * population.sort(Optimize.MINIMUM.<Double>ascending());
104      * }</pre>
105      *
106      * The code example above will populationSort the population according it's fitness
107      * values in descending order, since lower values are <i>better</i> in this
108      * case.
109      *
110      @param <T> the type of the objects to compare.
111      @return a new {@link Comparator} for the type {@code T}.
112      */
113     public <T extends Comparable<? super T>> Comparator<T> ascending() {
114         return this::compare;
115     }
116 
117     /**
118      * Return the best value, according to this optimization direction.
119      *
120      @param <C> the fitness value type.
121      @param a the first value.
122      @param b the second value.
123      @return the best value. If both values are equal the first one is returned.
124      */
125     public <C extends Comparable<? super C>> C best(final C a, final C b) {
126         return compare(b, a? b : a;
127     }
128 
129     /**
130      * Return the worst value, according to this optimization direction.
131      *
132      @param <C> the fitness value type.
133      @param a the first value.
134      @param b the second value.
135      @return the worst value. If both values are equal the first one is returned.
136      */
137     public <C extends Comparable<? super C>> C worst(final C a, final C b) {
138         return compare(b, a? b : a;
139     }
140 
141 }