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;
021
022import static io.jenetics.internal.util.Hashes.hash;
023import static io.jenetics.internal.util.SerialIO.readInt;
024import static io.jenetics.internal.util.SerialIO.writeInt;
025
026import java.io.IOException;
027import java.io.InvalidObjectException;
028import java.io.ObjectInput;
029import java.io.ObjectInputStream;
030import java.io.ObjectOutput;
031import java.io.Serial;
032import java.io.Serializable;
033import java.util.Objects;
034
035import io.jenetics.util.BaseSeq;
036import io.jenetics.util.Factory;
037import io.jenetics.util.ISeq;
038import io.jenetics.util.MSeq;
039import io.jenetics.util.Verifiable;
040
041/**
042 * The central class the GA is working with, is the {@code Genotype}. It is the
043 * structural representative of an individual. This class is the encoded problem
044 * solution with one to many {@link Chromosome}.
045 * <p>
046 * <img alt="Genotype" src="doc-files/Genotype.svg" width="400" height="252" >
047 * </p>
048 * The chromosomes of a genotype don't have to have necessarily the same size.
049 * It is only required that all genes are from the same type and the genes within
050 * a chromosome have the same constraints; e.g., the same min- and max values
051 * for the genes value.
052 *
053 * {@snippet lang="java":
054 * final Genotype<DoubleGene> genotype = Genotype.of(
055 *     DoubleChromosome.of(0.0, 1.0, 8),
056 *     DoubleChromosome.of(1.0, 2.0, 10),
057 *     DoubleChromosome.of(0.0, 10.0, 9),
058 *     DoubleChromosome.of(0.1, 0.9, 5)
059 * );
060 * }
061 * The code snippet above creates a genotype with the same structure as shown in
062 * the figure above. In this example the {@link DoubleGene} has been chosen as
063 * a gene type.
064 *
065 * @see Chromosome
066 * @see Phenotype
067 *
068 * @implNote
069 * This class is immutable and thread-safe.
070 *
071 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
072 * @since 1.0
073 * @version 7.2
074 */
075public final class Genotype<G extends Gene<?, G>>
076        implements
077                BaseSeq<Chromosome<G>>,
078                Factory<Genotype<G>>,
079                Verifiable,
080                Serializable
081{
082        @Serial
083        private static final long serialVersionUID = 3L;
084
085        private final ISeq<Chromosome<G>> _chromosomes;
086
087        //Caching isValid value.
088        private byte _valid = -1;
089
090        /**
091         * Create a new Genotype from a given sequence of {@code Chromosomes}.
092         *
093         * @param chromosomes The {@code Chromosome} array the {@code Genotype}
094         *         consists of
095         * @throws NullPointerException if {@code chromosomes} is null or one of its
096         *         elements
097         * @throws IllegalArgumentException if {@code chromosome.length == 0}
098         */
099        Genotype(final ISeq<? extends Chromosome<G>> chromosomes) {
100                if (chromosomes.isEmpty()) {
101                        throw new IllegalArgumentException("No chromosomes given.");
102                }
103
104                _chromosomes = ISeq.upcast(chromosomes);
105        }
106
107        /**
108         * Return the chromosome at the given index. It is guaranteed that the
109         * returned chromosome is not null.
110         *
111         * @since 4.0
112         *
113         * @param index the chromosome index
114         * @return the chromosome with the given index
115         * @throws IndexOutOfBoundsException if
116         *         {@code (index < 0 || index >= _length)}.
117         */
118        @Override
119        public Chromosome<G> get(final int index) {
120                return _chromosomes.get(index);
121        }
122
123        /**
124         * Getting the number of chromosomes of this genotype.
125         *
126         * @return number of chromosomes.
127         */
128        @Override
129        public int length() {
130                return _chromosomes.length();
131        }
132
133        /**
134         * Return the first chromosome. This is an alias for
135         * {@snippet lang="java":
136         * final Genotype<DoubleGene> gt = null; // @replace substring='null' replacement="..."
137         * final Chromosome<DoubleGene> chromosome = gt.get(0);
138         * }
139         *
140         * @since 5.2
141         *
142         * @return The first chromosome.
143         */
144        public Chromosome<G> chromosome() {
145                return get(0);
146        }
147
148        /**
149         * Return the first {@link Gene} of the first {@link Chromosome} of this
150         * {@code Genotype}. This is an alias for
151         * {@snippet lang="java":
152         * final Genotype<DoubleGene> gt = null; // @replace substring='null' replacement="..."
153         * final DoubleGene gene = gt.get(0).get(0);
154         * }
155         *
156         * @since 5.2
157         *
158         * @return the first {@link Gene} of the first {@link Chromosome} of this
159         *         {@code Genotype}.
160         */
161        public G gene() {
162                return get(0).get(0);
163        }
164
165        /**
166         * Return the number of genes this genotype consists of. This is the sum of
167         * the number of genes of the genotype chromosomes.
168         *
169         * @return Return the number of genes this genotype consists of
170         */
171        public int geneCount() {
172                int count = 0;
173                for (var chromosome : this) {
174                        count += chromosome.length();
175                }
176                return count;
177        }
178
179        /**
180         * Test if this genotype is valid. A genotype is valid if all its
181         * {@link Chromosome}s are valid.
182         *
183         * @return true if this genotype is valid, false otherwise.
184         */
185        @Override
186        public boolean isValid() {
187                byte valid = _valid;
188                if (valid == -1) {
189                        valid = (byte)(_chromosomes.forAll(Verifiable::isValid) ? 1 : 0);
190                        _valid = valid;
191                }
192
193                return _valid == 1;
194        }
195
196        /**
197         * Create a new Genotype which consists of the chromosomes from the given
198         * {@code fromIndex} (inclusively) to the given {@code toIndex} (exclusively).
199         * This method creates a <em>view</em> of the underlying chromosomes.
200         *
201         * @since 7.2
202         *
203         * @param fromIndex the start chromosome index, inclusively
204         * @param toIndex the end chromosome index, exclusively
205         * @return a new genotype consisting of the chromosomes within the given
206         *         indexes
207         * @throws IndexOutOfBoundsException for an illegal end point index value
208         *          ({@code fromIndex < 0 || toIndex > length() || fromIndex > toIndex}).
209         */
210        public Genotype<G> slice(int fromIndex, int toIndex) {
211                return new Genotype<>(_chromosomes.subSeq(fromIndex, toIndex));
212        }
213
214        /**
215         * Return a new, random genotype by creating new, random chromosomes (calling
216         * the {@link Chromosome#newInstance()} method) from the chromosomes of this
217         * genotype.
218         */
219        @Override
220        public Genotype<G> newInstance() {
221                return new Genotype<>(_chromosomes.map(Factory::newInstance));
222        }
223
224        @Override
225        public int hashCode() {
226                return hash(_chromosomes);
227        }
228
229        @Override
230        public boolean equals(final Object obj) {
231                return obj instanceof Genotype<?> other &&
232                        Objects.equals(_chromosomes, other._chromosomes);
233        }
234
235        @Override
236        public String toString() {
237                return _chromosomes.toString();
238        }
239
240        /**
241         * Create a new {@code Genotype} from a given array of {@code Chromosomes}.
242         *
243         * @since 3.0
244         *
245         * @param <G> the gene type
246         * @param first the first {@code Chromosome} of the {@code Genotype}
247         * @param rest the rest of the genotype chromosomes.
248         * @return a new {@code Genotype} from the given chromosomes
249         * @throws NullPointerException if {@code chromosomes} is {@code null} or
250         *         one of its elements.
251         */
252        @SafeVarargs
253        public static <G extends Gene<?, G>> Genotype<G> of(
254                final Chromosome<G> first,
255                final Chromosome<G>... rest
256        ) {
257                final MSeq<Chromosome<G>> seq = MSeq.ofLength(1 + rest.length);
258                seq.set(0, first);
259                for (int i = 0; i < rest.length; ++i) {
260                        seq.set(i + 1, rest[i]);
261                }
262                return new Genotype<>(seq.toISeq());
263        }
264
265        /**
266         * Create a new {@code Genotype} which consists of {@code n} chromosomes,
267         * which are created by the given {@code factory}. This method can be used
268         * for easily creating a <i>gene matrix</i>. The following example will
269         * create a 10x5 {@code DoubleGene} <i>matrix</i>.
270         * {@snippet lang="java":
271         * final Genotype<DoubleGene> gt = Genotype
272         *     .of(DoubleChromosome.of(0.0, 1.0, 10), 5);
273         * }
274         *
275         * @since 3.0
276         *
277         * @param <G> the gene type
278         * @param factory the factory which creates the chromosomes this genotype
279         *        consists of
280         * @param n the number of chromosomes this genotype consists of
281         * @return new {@code Genotype} containing {@code n} chromosomes
282         * @throws IllegalArgumentException if {@code n < 1}
283         * @throws NullPointerException if the {@code factory} is {@code null}
284         */
285        public static <G extends Gene<?, G>> Genotype<G>
286        of(final Factory<? extends Chromosome<G>> factory, final int n) {
287                final ISeq<Chromosome<G>> ch = ISeq.of(factory::newInstance, n);
288                return new Genotype<>(ch);
289        }
290
291        /**
292         * Create a new {@code Genotype} from a given array of {@code chromosomes}.
293         *
294         * @since 3.0
295         *
296         * @param <G> the gene type
297         * @param chromosomes the {@code Chromosome}s the returned genotype consists
298         *        of
299         * @return a new {@code Genotype} from the given chromosomes
300         * @throws NullPointerException if {@code chromosomes} is {@code null} or
301         *         one of its elements.
302         * @throws IllegalArgumentException if {@code chromosome.length() < 1}
303         */
304        public static <G extends Gene<?, G>> Genotype<G>
305        of(final Iterable<? extends Chromosome<G>> chromosomes) {
306                return new Genotype<>(ISeq.of(chromosomes));
307        }
308
309
310        /* *************************************************************************
311         *  Java object serialization
312         * ************************************************************************/
313
314        @Serial
315        private Object writeReplace() {
316                return new SerialProxy(SerialProxy.GENOTYPE, this);
317        }
318
319        @Serial
320        private void readObject(final ObjectInputStream stream)
321                throws InvalidObjectException
322        {
323                throw new InvalidObjectException("Serialization proxy required.");
324        }
325
326        void write(final ObjectOutput out) throws IOException {
327                writeInt(_chromosomes.length(), out);
328                for (var ch : _chromosomes) {
329                        out.writeObject(ch);
330                }
331        }
332
333        @SuppressWarnings({"unchecked", "rawtypes"})
334        static Object read(final ObjectInput in)
335                throws IOException, ClassNotFoundException
336        {
337                final int length = readInt(in);
338                final MSeq chromosomes = MSeq.ofLength(length);
339                for (int i = 0; i < length; ++i) {
340                        chromosomes.set(i, in.readObject());
341                }
342
343                return new Genotype(chromosomes.asISeq());
344        }
345
346}