001 /*
002 * Java Genetic Algorithm Library (jenetics-3.5.0).
003 * Copyright (c) 2007-2016 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
021 /**
022 * This is the base package of the Jenetics library and contains all domain
023 * classes, like Gene, Chromosome or Genotype. Most of this types are immutable
024 * data classes and doesn't implement any behavior. It also contains the Selector
025 * and Alterer interfaces and its implementations. The classes in this package
026 * are (almost) sufficient to implement an own GA.
027 *
028 * <h3>Introduction</h3>
029 * <p><strong>Jenetics</strong> is an <strong>Genetic Algorithm</strong>,
030 * respectively an <strong>Evolutionary Algorithm</strong>, library written in
031 * Java. It is designed with a clear separation of the several concepts of the
032 * algorithm, e. g. Gene, Chromosome, Genotype, Phenotype, Population and
033 * fitness Function. <strong>Jenetics</strong> allows you to minimize and
034 * maximize the given fitness function without tweaking it. In contrast to other
035 * GA implementations, the library uses the concept of an evolution stream
036 * (EvolutionStream) for executing the evolution steps. Since the
037 * EvolutionStream implements the Java Stream interface, it works smoothly with
038 * the rest of the Java streaming API.</p>
039 *
040 * <h3>Getting Started</h3>
041 * <p>The minimum evolution Engine setup needs a genotype factory,
042 * Factory<Genotype<?>>, and a fitness Function. The Genotype
043 * implements the Factory interface and can therefore be used as prototype for
044 * creating the initial Population and for creating new random Genotypes.</p>
045 *
046 * <pre>{@code
047 * import org.jenetics.BitChromosome;
048 * import org.jenetics.BitGene;
049 * import org.jenetics.Genotype;
050 * import org.jenetics.engine.Engine;
051 * import org.jenetics.engine.EvolutionResult;
052 * import org.jenetics.util.Factory;
053 *
054 * public class HelloWorld {
055 * // 2.) Definition of the fitness function.
056 * private static Integer eval(Genotype<BitGene> gt) {
057 * return ((BitChromosome)gt.getChromosome()).bitCount();
058 * }
059 *
060 * public static void main(String[] args) {
061 * // 1.) Define the genotype (factory) suitable
062 * // for the problem.
063 * Factory<Genotype<BitGene>> gtf =
064 * Genotype.of(BitChromosome.of(10, 0.5));
065 *
066 * // 3.) Create the execution environment.
067 * Engine<BitGene, Integer> engine = Engine
068 * .builder(HelloWorld::eval, gtf)
069 * .build();
070 *
071 * // 4.) Start the execution (evolution) and
072 * // collect the result.
073 * Genotype<BitGene> result = engine.stream()
074 * .limit(100)
075 * .collect(EvolutionResult.toBestGenotype());
076 *
077 * System.out.println("Hello World:\n" + result);
078 * }
079 * }
080 * }</pre>
081 *
082 * <p>In contrast to other GA implementations, the library uses the concept of
083 * an evolution stream (EvolutionStream) for executing the evolution steps.
084 * Since the EvolutionStream implements the Java Stream interface, it works
085 * smoothly with the rest of the Java streaming API. Now let's have a closer
086 * look at listing above and discuss this simple program step by step:</p>
087 * <ol>
088 * <li>The probably most challenging part, when setting up a new evolution
089 * Engine, is to transform the problem domain into a appropriate Genotype
090 * (factory) representation. In our example we want to count the number of ones
091 * of a BitChromosome. Since we are counting only the ones of one chromosome,
092 * we are adding only one BitChromosome to our Genotype. In general, the
093 * Genotype can be created with 1 to n chromosomes.</li>
094 * <li>Once this is done, the fitness function which should be maximized, can be
095 * defined. Utilizing the new language features introduced in Java 8, we simply
096 * write a private static method, which takes the genotype we defined and
097 * calculate it's fitness value. If we want to use the optimized bit-counting
098 * method, bitCount(), we have to cast the Chromosome<BitGene> class to
099 * the actual used BitChromosome class. Since we know for sure that we created
100 * the Genotype with a BitChromosome, this can be done safely. A reference to
101 * the eval method is then used as fitness function and passed to the
102 * Engine.build method.</li>
103 * <li>In the third step we are creating the evolution Engine, which is
104 * responsible for changing, respectively evolving, a given population. The
105 * Engine is highly configurable and takes parameters for controlling the
106 * evolutionary and the computational environment. For changing the evolutionary
107 * behavior, you can set different alterers and selectors. By changing the used
108 * Executor service, you control the number of threads, the Engine is allowed to
109 * use. An new Engine instance can only be created via its builder, which is
110 * created by calling the Engine.builder method.</li>
111 * <li>In the last step, we can create a new EvolutionStream from our Engine.
112 * The EvolutionStream is the model or view of the evolutionary process. It
113 * serves as a »process handle« and also allows you, among other things, to
114 * control the termination of the evolution. In our example, we simply truncate
115 * the stream after 100 generations. If you don't limit the stream, the
116 * EvolutionStream will not terminate and run forever. Since the EvolutionStream
117 * extends the java.util.stream.Stream interface, it integrates smoothly with
118 * the rest of the Java streaming API. The final result, the best Genotype in
119 * our example, is then collected with one of the predefined collectors of the
120 * EvolutionResult class.</li>
121 * </ol>
122 *
123 * @author <a href="mailto:franz.wilhelmstoetter@gmx.at">Franz Wilhelmstötter</a>
124 * @since 1.0
125 * @version 3.1
126 */
127 package org.jenetics;
|