001/*
002 * Java Genetic Algorithm Library (jenetics-8.1.0).
003 * Copyright (c) 2007-2024 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 */
020package io.jenetics.engine;
021
022import static java.lang.String.format;
023import static java.util.Objects.requireNonNull;
024import static io.jenetics.internal.util.Hashes.hash;
025import static io.jenetics.internal.util.SerialIO.readLong;
026import static io.jenetics.internal.util.SerialIO.writeLong;
027
028import java.io.IOException;
029import java.io.InvalidObjectException;
030import java.io.ObjectInput;
031import java.io.ObjectInputStream;
032import java.io.ObjectOutput;
033import java.io.Serial;
034import java.io.Serializable;
035import java.util.Objects;
036
037import io.jenetics.Gene;
038import io.jenetics.Phenotype;
039import io.jenetics.internal.util.Requires;
040import 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 */
059public final class EvolutionStart<
060        G extends Gene<?, G>,
061        C 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(), 1, false);
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 out) throws 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}