EvolutionStart.java
001 /*
002  * Java Genetic Algorithm Library (jenetics-5.1.0).
003  * Copyright (c) 2007-2019 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 import static io.jenetics.internal.util.Hashes.hash;
025 
026 import java.util.Objects;
027 
028 import io.jenetics.Gene;
029 import io.jenetics.Phenotype;
030 import io.jenetics.internal.util.require;
031 import io.jenetics.util.ISeq;
032 
033 /**
034  * Represents a state of the GA at the start of an evolution step.
035  *
036  @see EvolutionResult
037  @see EvolutionInit
038  @see EvolutionStreamable#stream(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 5.1
049  */
050 public final class EvolutionStart<
051     extends Gene<?, G>,
052     extends Comparable<? super C>
053 {
054 
055     private final ISeq<Phenotype<G, C>> _population;
056     private final long _generation;
057 
058     private EvolutionStart(
059         final ISeq<Phenotype<G, C>> population,
060         final long generation
061     ) {
062         _population = requireNonNull(population);
063         _generation = require.positive(generation);
064     }
065 
066     /**
067      * Return the population before the evolution step.
068      *
069      @return the start population
070      */
071     public ISeq<Phenotype<G, C>> getPopulation() {
072         return _population;
073     }
074 
075     /**
076      * Return the generation of the start population.
077      *
078      @return the start generation
079      */
080     public long getGeneration() {
081         return _generation;
082     }
083 
084     @Override
085     public int hashCode() {
086         return hash(_generation, hash(_population, hash(getClass())));
087     }
088 
089     @Override
090     public boolean equals(final Object obj) {
091         return obj == this ||
092             obj instanceof EvolutionStart &&
093             _generation == ((EvolutionStart)obj)._generation &&
094             Objects.equals(_population, ((EvolutionStart)obj)._population);
095     }
096 
097     @Override
098     public String toString() {
099         return format(
100             "EvolutionStart[population-size=%d, generation=%d]",
101             _population.size(), _generation
102         );
103     }
104 
105     /**
106      * Create a new evolution start object with the given population and for the
107      * given generation.
108      *
109      @param <G> the gene type
110      @param <C> the fitness type
111      @param population the start population.
112      @param generation the start generation of the population
113      @return a new evolution start object
114      @throws java.lang.NullPointerException if the given {@code population} is
115      *         {@code null}.
116      @throws IllegalArgumentException if the given {@code generation} is
117      *         smaller then one
118      */
119     public static <G extends Gene<?, G>, C extends Comparable<? super C>>
120     EvolutionStart<G, C> of(
121         final ISeq<Phenotype<G, C>> population,
122         final long generation
123     ) {
124         return new EvolutionStart<>(population, generation);
125     }
126 
127     /**
128      * An empty evolution start object, which can be used as initial evolution
129      * value. The evolution {@link Engine} is then responsible for creating the
130      * proper initial population,
131      *
132      @since 5.1
133      *
134      @param <G> the gene type
135      @param <C> the fitness type
136      @return an empty evolution start object
137      */
138     public static <G extends Gene<?, G>, C extends Comparable<? super C>>
139     EvolutionStart<G, C> empty() {
140         return new EvolutionStart<>(ISeq.empty()1);
141     }
142 
143 }