io.jenetics.engine.EvolutionInterceptor Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jenetics Show documentation
Jenetics - Java Genetic Algorithm Library
There is a newer version: 8.1.0
/*
 * Java Genetic Algorithm Library (jenetics-7.1.2).
 * Copyright (c) 2007-2023 Franz Wilhelmstötter
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * Author:
 *    Franz Wilhelmstötter ([email protected])
 */
package io.jenetics.engine;

import static java.util.Objects.requireNonNull;

import java.util.function.Function;

import io.jenetics.Gene;

/**
 * The evolution interceptor allows to update the {@link EvolutionStart} object,
 * before the evolution start, and update the {@link EvolutionResult}
 * object after the evolution.
 *
 * @see EvolutionResult#toUniquePopulation()
 * @see Engine.Builder#interceptor(EvolutionInterceptor)
 *
 * @param  the gene type
 * @param  the fitness result type
 *
 * @author Franz Wilhelmstötter
 * @since 6.0
 * @version 6.0
 */
public interface EvolutionInterceptor<
	G extends Gene,
	C extends Comparable
> {

	/**
	 * This method is called right before the evaluation of a generation is
	 * started.
	 *
	 * @param start the evolution start object
	 * @return the possible update evolution start object
	 * @throws NullPointerException if the evolution {@code start} object is
	 *         {@code null}
	 */
	default EvolutionStart before(final EvolutionStart start) {
		return start;
	}

	/**
	 * This method is called after the evaluation of a generation. If this
	 * method alters the evolution result object, the population within this
	 * result object is re-evaluated.
	 *
	 * @param result the evolution result object to update
	 * @return the possible updated evolution result object
	 * @throws NullPointerException if the evolution {@code result} object is
	 *         {@code null}
	 */
	default EvolutionResult after(final EvolutionResult result) {
		return result;
	}

	/**
	 * Composes {@code this} interceptor with the {@code other} one. The
	 * {@link #before(EvolutionStart)} of {@code this} interceptor is called
	 * after the {@code before} method of the {@code other} interceptor.
	 * And the {@link #after(EvolutionResult)} of {@code this} interceptor is
	 * called before the {@code after} method of the {@code other}
	 * interceptor.
	 *
	 * @param other the other, composing interceptor
	 * @return a new, composed interceptor
	 * @throws NullPointerException if the {@code other} interceptor is
	 *         {@code null}
	 */
	default EvolutionInterceptor
	compose(final EvolutionInterceptor other) {
		requireNonNull(other);
		return EvolutionInterceptor.of(
			start -> before(other.before(start)),
			result -> other.after(after(result))
		);
	}

	/**
	 * Create a new interceptor instance with the given {@code before} and
	 * {@code after} functions.
	 *
	 * @param before the function executed before each evolution step
	 * @param after the function executed after each evolution step
	 * @param  the gene type
	 * @param  the fitness result type
	 * @return a new interceptor instance with the given interceptor functions
	 * @throws NullPointerException if one of the functions is {@code null}
	 */
	static , C extends Comparable>
	EvolutionInterceptor of(
		final Function, EvolutionStart> before,
		final Function, EvolutionResult> after
	) {
		requireNonNull(before);
		requireNonNull(after);

		return new EvolutionInterceptor<>() {
			@Override
			public EvolutionStart before(final EvolutionStart start) {
				return before.apply(start);
			}

			@Override
			public EvolutionResult after(final EvolutionResult result) {
				return after.apply(result);
			}
		};
	}

	/**
	 * Create a new interceptor instance with the given {@code before} function.
	 *
	 * @param before the function executed before each evolution step
	 * @param  the gene type
	 * @param  the fitness result type
	 * @return a new interceptor instance with the given interceptor function
	 * @throws NullPointerException if the function is {@code null}
	 */
	static , C extends Comparable>
	EvolutionInterceptor
	ofBefore(final Function, EvolutionStart> before) {
		return EvolutionInterceptor.of(before, Function.identity());
	}

	/**
	 * Create a new interceptor instance with the given {@code after} function.
	 *
	 * @param after the function executed after each evolution step
	 * @param  the gene type
	 * @param  the fitness result type
	 * @return a new interceptor instance with the given interceptor function
	 * @throws NullPointerException if the function is {@code null}
	 */
	static , C extends Comparable>
	EvolutionInterceptor
	ofAfter(final Function, EvolutionResult> after) {
		return EvolutionInterceptor.of(Function.identity(), after);
	}

	/**
	 * Return an interceptor object which does nothing.
	 *
	 * @param  the gene type
	 * @param  the fitness result type
	 * @return a new identity interceptor
	 */
	static , C extends Comparable>
	EvolutionInterceptor identity() {
		return EvolutionInterceptor.of(Function.identity(), Function.identity());
	}

}