EvolutionIterable.java
001 /*
002  * Java Genetic Algorithm Library (jenetics-4.2.0).
003  * Copyright (c) 2007-2018 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.Iterator;
023 import java.util.function.Supplier;
024 
025 import io.jenetics.Gene;
026 import io.jenetics.Genotype;
027 import io.jenetics.Phenotype;
028 import io.jenetics.util.ISeq;
029 
030 /**
031  * This interface defines the capability of creating <b>infinite</b> evolution
032  * iterators.
033  *
034  @see EvolutionStreamable
035  *
036  @deprecated Marked for removal in the next major version.
037  *
038  @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
039  @version 4.1
040  @since 4.1
041  */
042 @Deprecated
043 interface EvolutionIterable<
044     extends Gene<?, G>,
045     extends Comparable<? super C>
046 >  {
047 
048     /**
049      * Create a new <b>infinite</b> evolution iterator with the given evolution
050      * start. If an empty {@code Population} is given, the engines genotype
051      * factory is used for creating the population. The given population might
052      * be the result of an other engine and this method allows to start the
053      * evolution with the outcome of an different engine. The fitness function
054      * and the fitness scaler are replaced by the one defined for this engine.
055      *
056      @deprecated Marked for removal in the next major version.
057      @param start the data the evolution stream starts with
058      @return a new <b>infinite</b> evolution iterator
059      @throws java.lang.NullPointerException if the given evolution
060      *         {@code start} is {@code null}.
061      */
062     @Deprecated
063     public Iterator<EvolutionResult<G, C>>
064     iterator(final Supplier<EvolutionStart<G, C>> start);
065 
066     /**
067      * Create a new <b>infinite</b> evolution iterator with the given initial
068      * value. If an empty {@code Population} is given, the engines genotype
069      * factory is used for creating the population. The given population might
070      * be the result of an other engine and this method allows to start the
071      * evolution with the outcome of an different engine. The fitness function
072      * and the fitness scaler are replaced by the one defined for this engine.
073      *
074      @deprecated Marked for removal in the next major version.
075      @param init the data the evolution iterator is initialized with
076      @return a new <b>infinite</b> evolution stream
077      @throws java.lang.NullPointerException if the given evolution
078      *         {@code start} is {@code null}.
079      */
080     @Deprecated
081     public Iterator<EvolutionResult<G, C>> iterator(final EvolutionInit<G> init);
082 
083     /* *************************************************************************
084      * Default interface methods.
085      * ************************************************************************/
086 
087     /**
088      * Create a new <b>infinite</b> evolution iterator with a newly created
089      * population. This is an alternative way for evolution. It lets the user
090      * start, stop and resume the evolution process whenever desired.
091      *
092      @deprecated Marked for removal in the next major version.
093      @return a new <b>infinite</b> evolution iterator
094      */
095     @Deprecated
096     public default Iterator<EvolutionResult<G, C>> iterator() {
097         return iterator(EvolutionStart.of(ISeq.empty()1));
098     }
099 
100     /**
101      * Create a new <b>infinite</b> evolution iterator with the given evolution
102      * start. If an empty {@code Population} is given, the engines genotype
103      * factory is used for creating the population. The given population might
104      * be the result of an other engine and this method allows to start the
105      * evolution with the outcome of an different engine. The fitness function
106      * and the fitness scaler are replaced by the one defined for this engine.
107      *
108      @deprecated Marked for removal in the next major version.
109      @param start the data the evolution stream starts with
110      @return a new <b>infinite</b> evolution iterator
111      @throws java.lang.NullPointerException if the given evolution
112      *         {@code start} is {@code null}.
113      */
114     @Deprecated
115     public default Iterator<EvolutionResult<G, C>>
116     iterator(final EvolutionStart<G, C> start) {
117         return iterator(() -> start);
118     }
119 
120     /**
121      * Create a new <b>infinite</b> evolution iterator starting with a
122      * previously evolved {@link EvolutionResult}. The iterator is initialized
123      * with the population of the given {@code result} and its total generation
124      {@link EvolutionResult#getTotalGenerations()}.
125      *
126      @deprecated Marked for removal in the next major version.
127      @param result the previously evolved {@code EvolutionResult}
128      @return a new evolution stream, which continues a previous one
129      @throws NullPointerException if the given evolution {@code result} is
130      *         {@code null}
131      */
132     @Deprecated
133     public default Iterator<EvolutionResult<G, C>>
134     iterator(final EvolutionResult<G, C> result) {
135         return iterator(EvolutionStart.of(
136             result.getPopulation(),
137             result.getGeneration()
138         ));
139     }
140 
141     /**
142      * Create a new <b>infinite</b> evolution iterator with the given initial
143      * population. If an empty {@code Population} is given, the engines genotype
144      * factory is used for creating the population. The given population might
145      * be the result of an other engine and this method allows to start the
146      * evolution with the outcome of an different engine. The fitness function
147      * and the fitness scaler are replaced by the one defined for this engine.
148      *
149      @deprecated Marked for removal in the next major version.
150      @param population the initial individuals used for the evolution iterator.
151      *        Missing individuals are created and individuals not needed are
152      *        skipped.
153      @param generation the generation the iterator starts from; must be greater
154      *        than zero.
155      @return a new <b>infinite</b> evolution iterator
156      @throws java.lang.NullPointerException if the given {@code population} is
157      *         {@code null}.
158      @throws IllegalArgumentException if the given {@code generation} is smaller
159      *        then one
160      */
161     @Deprecated
162     public default Iterator<EvolutionResult<G, C>> iterator(
163         final ISeq<Phenotype<G, C>> population,
164         final long generation
165     ) {
166         return iterator(EvolutionStart.of(population, generation));
167     }
168 
169     /**
170      * Create a new <b>infinite</b> evolution iterator with the given initial
171      * population. If an empty {@code Population} is given, the engines genotype
172      * factory is used for creating the population. The given population might
173      * be the result of an other engine and this method allows to start the
174      * evolution with the outcome of an different engine. The fitness function
175      * and the fitness scaler are replaced by the one defined for this engine.
176      *
177      @deprecated Marked for removal in the next major version.
178      @param population the initial individuals used for the evolution iterator.
179      *        Missing individuals are created and individuals not needed are
180      *        skipped.
181      @return a new <b>infinite</b> evolution iterator
182      @throws java.lang.NullPointerException if the given {@code population} is
183      *         {@code null}.
184      */
185     @Deprecated
186     public default Iterator<EvolutionResult<G, C>>
187     iterator(final ISeq<Phenotype<G, C>> population) {
188         return iterator(EvolutionStart.of(population, 1));
189     }
190 
191     /**
192      * Create a new <b>infinite</b> evolution iterator with the given initial
193      * individuals. If an empty {@code Iterable} is given, the engines genotype
194      * factory is used for creating the population.
195      *
196      @deprecated Marked for removal in the next major version.
197      @param genotypes the initial individuals used for the evolution iterator.
198      *        Missing individuals are created and individuals not needed are
199      *        skipped.
200      @param generation the generation the stream starts from; must be greater
201      *        than zero.
202      @return a new <b>infinite</b> evolution iterator
203      @throws java.lang.NullPointerException if the given {@code genotypes} is
204      *         {@code null}.
205      @throws IllegalArgumentException if the given {@code generation} is
206      *         smaller then one
207      */
208     @Deprecated
209     public default Iterator<EvolutionResult<G, C>> iterator(
210         final Iterable<Genotype<G>> genotypes,
211         final long generation
212     ) {
213         return iterator(EvolutionInit.of(
214             ISeq.of(genotypes),
215             generation
216         ));
217     }
218 
219     /**
220      * Create a new <b>infinite</b> evolution iterator with the given initial
221      * individuals. If an empty {@code Iterable} is given, the engines genotype
222      * factory is used for creating the population.
223      *
224      @deprecated Marked for removal in the next major version.
225      @param genotypes the initial individuals used for the evolution iterator.
226      *        Missing individuals are created and individuals not needed are
227      *        skipped.
228      @return a new <b>infinite</b> evolution iterator
229      @throws java.lang.NullPointerException if the given {@code genotypes} is
230      *         {@code null}.
231      */
232     @Deprecated
233     public default Iterator<EvolutionResult<G, C>>
234     iterator(final Iterable<Genotype<G>> genotypes) {
235         return iterator(genotypes, 1);
236     }
237 
238 }