Optimize.java
001 /*
002  * Java Genetic Algorithm Library (jenetics-1.6.0).
003  * Copyright (c) 2007-2014 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@gmx.at)
019  */
020 package org.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@gmx.at">Franz Wilhelmstötter</a>
029  @since 1.0
030  @version 1.0 &mdash; <em>$Date: 2014-03-07 $</em>
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 o1, final T o2)
041         {
042             return o2.compareTo(o1);
043         }
044     },
045 
046     /**
047      * GA maximization
048      */
049     MAXIMUM {
050         @Override
051         public <T extends Comparable<? super T>>
052         int compare(final T o1, final T o2)
053         {
054             return o1.compareTo(o2);
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 o1 the first object to be compared.
065      @param o2 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 o1, final T o2);
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      * [code]
080      * Population<DoubleGene, Double> population = ...
081      * population.sort(Optimize.MINIMUM.<Double>descending());
082      * [/code]
083      *
084      * The code example above will sort 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 new Comparator<T>() {
093             @Override
094             public int compare(final T o1, final T o2) {
095                 return Optimize.this.compare(o2, o1);
096             }
097         };
098     }
099 
100     /**
101      * Create an appropriate comparator of the given optimization strategy. A
102      * collection of comparable objects with the returned comparator will be
103      * sorted in <b>ascending</b> order, according to the given definition
104      * of <i>better</i> and <i>worse</i>.
105      *
106      * [code]
107      * Population<DoubleGene, Double> population = ...
108      * population.sort(Optimize.MINIMUM.<Double>ascending());
109      * [/code]
110      *
111      * The code example above will sort the population according it's fitness
112      * values in descending order, since lower values are <i>better</i> in this
113      * case.
114      *
115      @param <T> the type of the objects to compare.
116      @return a new {@link Comparator} for the type {@code T}.
117      */
118     public <T extends Comparable<? super T>> Comparator<T> ascending() {
119         return new Comparator<T>() {
120             @Override
121             public int compare(final T o1, final T o2) {
122                 return Optimize.this.compare(o1, o2);
123             }
124         };
125     }
126 
127     /**
128      * Return the best value, according to this optimization direction.
129      *
130      @param <C> the fitness value type.
131      @param a the first value.
132      @param b the second value.
133      @return the best value. If both values are equal the first one is returned.
134      */
135     public <C extends Comparable<? super C>> C best(final C a, final C b) {
136         return compare(b, a? b : a;
137     }
138 
139     /**
140      * Return the worst value, according to this optimization direction.
141      *
142      @param <C> the fitness value type.
143      @param a the first value.
144      @param b the second value.
145      @return the worst value. If both values are equal the first one is returned.
146      */
147     public <C extends Comparable<? super C>> C worst(final C a, final C b) {
148         return compare(b, a? b : a;
149     }
150 
151 }