001/* 002 * Java Genetic Algorithm Library (jenetics-7.2.0). 003 * Copyright (c) 2007-2023 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}