EvolutionStart.java
001 /*
002  * Java Genetic Algorithm Library (jenetics-7.0.0).
003  * Copyright (c) 2007-2022 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 import static io.jenetics.internal.util.SerialIO.readLong;
026 import static io.jenetics.internal.util.SerialIO.writeLong;
027 
028 import java.io.IOException;
029 import java.io.InvalidObjectException;
030 import java.io.ObjectInput;
031 import java.io.ObjectInputStream;
032 import java.io.ObjectOutput;
033 import java.io.Serial;
034 import java.io.Serializable;
035 import java.util.Objects;
036 
037 import io.jenetics.Gene;
038 import io.jenetics.Phenotype;
039 import io.jenetics.internal.util.Requires;
040 import io.jenetics.util.ISeq;
041 
042 /**
043  * Represents a state of the GA at the start of an evolution step.
044  *
045  @see EvolutionResult
046  @see EvolutionInit
047  @see EvolutionStreamable#stream(EvolutionStart)
048  *
049  @param <G> the gene type
050  @param <C> the fitness type
051  *
052  * @implNote
053  * This class is immutable and thread-safe.
054  *
055  @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
056  @since 3.1
057  @version 6.0
058  */
059 public final class EvolutionStart<
060     extends Gene<?, G>,
061     extends Comparable<? super C>
062 >
063     implements Serializable
064 {
065 
066     @Serial
067     private static final long serialVersionUID = 2L;
068 
069     private final ISeq<Phenotype<G, C>> _population;
070     private final long _generation;
071 
072     private final boolean _dirty;
073 
074     EvolutionStart(
075         final ISeq<Phenotype<G, C>> population,
076         final long generation,
077         final boolean dirty
078     ) {
079         _population = requireNonNull(population);
080         _generation = Requires.positive(generation);
081         _dirty = dirty;
082     }
083 
084     /**
085      * Return the population before the evolution step.
086      *
087      @return the start population
088      */
089     public ISeq<Phenotype<G, C>> population() {
090         return _population;
091     }
092 
093     /**
094      * Return the generation of the start population.
095      *
096      @return the start generation
097      */
098     public long generation() {
099         return _generation;
100     }
101 
102     /**
103      * Indicates whether the population is guaranteed to be evaluated. If this
104      * flag is {@code true}, the population possibly contains unevaluated
105      * individuals.
106      *
107      @return {@code false}, if it is guaranteed that all individuals has
108      *         already been evaluated, {@code true} otherwise
109      */
110     boolean isDirty() {
111         return _dirty;
112     }
113 
114     @Override
115     public int hashCode() {
116         return hash(_generation, hash(_population, hash(getClass())));
117     }
118 
119     @Override
120     public boolean equals(final Object obj) {
121         return obj == this ||
122             obj instanceof EvolutionStart<?, ?> other &&
123             _generation == other._generation &&
124             Objects.equals(_population, other._population);
125     }
126 
127     @Override
128     public String toString() {
129         return format(
130             "EvolutionStart[population-size=%d, generation=%d]",
131             _population.size(), _generation
132         );
133     }
134 
135     /**
136      * Create a new evolution start object with the given population and for the
137      * given generation.
138      *
139      @param <G> the gene type
140      @param <C> the fitness type
141      @param population the start population.
142      @param generation the start generation of the population
143      @return a new evolution start object
144      @throws java.lang.NullPointerException if the given {@code population} is
145      *         {@code null}.
146      @throws IllegalArgumentException if the given {@code generation} is
147      *         smaller then one
148      */
149     public static <G extends Gene<?, G>, C extends Comparable<? super C>>
150     EvolutionStart<G, C> of(
151         final ISeq<Phenotype<G, C>> population,
152         final long generation
153     ) {
154         return new EvolutionStart<>(population, generation, true);
155     }
156 
157     /**
158      * An empty evolution start object, which can be used as initial evolution
159      * value. The evolution {@link Engine} is then responsible for creating the
160      * proper initial population,
161      *
162      @since 5.1
163      *
164      @param <G> the gene type
165      @param <C> the fitness type
166      @return an empty evolution start object
167      */
168     public static <G extends Gene<?, G>, C extends Comparable<? super C>>
169     EvolutionStart<G, C> empty() {
170         return new EvolutionStart<>(ISeq.empty()1false);
171     }
172 
173 
174     /* *************************************************************************
175      *  Java object serialization
176      * ************************************************************************/
177 
178     @Serial
179     private Object writeReplace() {
180         return new SerialProxy(SerialProxy.EVOLUTION_START, this);
181     }
182 
183     @Serial
184     private void readObject(final ObjectInputStream stream)
185         throws InvalidObjectException
186     {
187         throw new InvalidObjectException("Serialization proxy required.");
188     }
189 
190     void write(final ObjectOutput outthrows IOException {
191         out.writeObject(_population);
192         writeLong(_generation, out);
193     }
194 
195     @SuppressWarnings({"unchecked""rawtypes"})
196     static Object read(final ObjectInput in)
197         throws IOException, ClassNotFoundException
198     {
199         return new EvolutionStart(
200             (ISeq)in.readObject(),
201             readLong(in),
202             true
203         );
204     }
205 
206 }