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 java.util.concurrent.atomic.AtomicBoolean;
023
024import io.jenetics.Gene;
025import io.jenetics.Phenotype;
026
027/**
028 * This class allows forcing a reevaluation of the fitness function. A
029 * reevaluation is necessary if the fitness function changes. Changing the
030 * fitness function is not the usual use case but is necessary for some
031 * problems, like symbolic regression analyses with changing input data (time
032 * series).
033 * {@snippet lang="java":
034 * final var nullifier = new FitnessNullifier<DoubleGene, Double>();
035 *
036 * final Engine<DoubleGene, Double> engine = Engine.builder(problem)
037 *     .interceptor(nullifier)
038 *     .build();
039 *
040 * // Invalidate fitness value by calling the 'nullifyFitness' method,
041 * // possible from a different thread. This forces the reevaluation of
042 * // the fitness values at the start of the next generation.
043 * nullifier.nullifyFitness();
044 * }
045 *
046 * @implNote
047 * This interceptor is thread-safe and can be used from different threads. No
048 * additional synchronization is necessary.
049 *
050 * @see Phenotype#nullifyFitness()
051 *
052 * @param <G> the gene type
053 * @param <C> the fitness result type
054 *
055 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
056 * @since 6.0
057 * @version 6.0
058 */
059public final class FitnessNullifier<
060        G extends Gene<?, G>,
061        C extends Comparable<? super C>
062>
063        implements EvolutionInterceptor<G, C>
064{
065
066        private final AtomicBoolean _invalid = new AtomicBoolean(false);
067
068        /**
069         * Nullifies the fitness values of the population, if requested. The
070         * <em>nullification flag</em> is reset after this call. Two consecutive
071         * calls of this method might lead to two different results.
072         *
073         * @see #nullifyFitness()
074         *
075         * @param start the evolution start object
076         * @return the evolution start object with the nullified fitness values,
077         *         if the nullification has been triggered
078         */
079        @Override
080        public EvolutionStart<G, C> before(final EvolutionStart<G, C> start) {
081                final boolean invalid = _invalid.getAndSet(false);
082                return invalid ? invalidate(start) : start;
083        }
084
085        private EvolutionStart<G, C> invalidate(final EvolutionStart<G, C> start) {
086                return EvolutionStart.of(
087                        start.population().map(Phenotype::nullifyFitness),
088                        start.generation()
089                );
090        }
091
092        /**
093         * Triggers the nullification of the fitness values of the population for
094         * the next generation.
095         *
096         * @see #before(EvolutionStart)
097         *
098         * @return {@code true} if the <em>nullification</em> request will trigger
099         *         a new fitness nullification. @{code false} if the fitness
100         *         <em>nullification</em> has been requested before, without
101         *         actually executing it.
102         */
103        public boolean nullifyFitness() {
104                return !_invalid.getAndSet(true);
105        }
106
107}