EvolutionStart.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 static java.lang.String.format;
023 import static java.util.Objects.requireNonNull;
024 
025 import java.util.Objects;
026 
027 import io.jenetics.Gene;
028 import io.jenetics.Phenotype;
029 import io.jenetics.internal.util.require;
030 import io.jenetics.util.ISeq;
031 
032 /**
033  * Represents a state of the GA at the start of an evolution step.
034  *
035  @see EvolutionResult
036  @see EvolutionInit
037  @see EvolutionStreamable#stream(EvolutionStart)
038  @see EvolutionIterable#iterator(EvolutionStart)
039  *
040  @param <G> the gene type
041  @param <C> the fitness type
042  *
043  * @implNote
044  * This class is immutable and thread-safe.
045  *
046  @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
047  @since 3.1
048  @version 4.0
049  */
050 public final class EvolutionStart<
051     extends Gene<?, G>,
052     extends Comparable<? super C>
053 >
054 {
055 
056     private final ISeq<Phenotype<G, C>> _population;
057     private final long _generation;
058 
059     private EvolutionStart(
060         final ISeq<Phenotype<G, C>> population,
061         final long generation
062     ) {
063         _population = requireNonNull(population);
064         _generation = require.positive(generation);
065     }
066 
067     /**
068      * Return the population before the evolution step.
069      *
070      @return the start population
071      */
072     public ISeq<Phenotype<G, C>> getPopulation() {
073         return _population;
074     }
075 
076     /**
077      * Return the generation of the start population.
078      *
079      @return the start generation
080      */
081     public long getGeneration() {
082         return _generation;
083     }
084 
085     @Override
086     public int hashCode() {
087         int hash = 17;
088         hash += 31*_generation + 17;
089         hash += 31*Objects.hashCode(_population17;
090         return hash;
091     }
092 
093     @Override
094     public boolean equals(final Object obj) {
095         return obj == this ||
096             obj instanceof EvolutionStart &&
097             _generation == ((EvolutionStart)obj)._generation &&
098             Objects.equals(_population, ((EvolutionStart)obj)._population);
099     }
100 
101     @Override
102     public String toString() {
103         return format(
104             "EvolutionStart[population-size=%d, generation=%d]",
105             _population.size(), _generation
106         );
107     }
108 
109     /**
110      * Create a new evolution start object with the given population and for the
111      * given generation.
112      *
113      @param <G> the gene type
114      @param <C> the fitness type
115      @param population the start population.
116      @param generation the start generation of the population
117      @return a new evolution start object
118      @throws java.lang.NullPointerException if the given {@code population} is
119      *         {@code null}.
120      @throws IllegalArgumentException if the given {@code generation} is
121      *         smaller then one
122      */
123     public static <G extends Gene<?, G>, C extends Comparable<? super C>>
124     EvolutionStart<G, C> of(
125         final ISeq<Phenotype<G, C>> population,
126         final long generation
127     ) {
128         return new EvolutionStart<>(population, generation);
129     }
130 
131 }