1 package net.bmahe.genetics4j.core.termination;
2
3 import java.util.List;
4
5 import net.bmahe.genetics4j.core.Genotype;
6 import net.bmahe.genetics4j.core.spec.AbstractEAConfiguration;
7
8 /**
9 * Functional interface for determining when to stop the evolutionary algorithm.
10 *
11 * <p>Termination criteria are essential for controlling when an evolutionary algorithm should stop evolving and return
12 * its best solutions. The choice of termination criteria significantly affects both the quality of results and
13 * computational efficiency.
14 *
15 * <p>Termination conditions provide access to various aspects of the evolution state including:
16 * <ul>
17 * <li><strong>Generation count</strong>: Number of evolutionary cycles completed</li>
18 * <li><strong>Population state</strong>: Current genotypes and their fitness values</li>
19 * <li><strong>Configuration</strong>: Algorithm parameters and settings</li>
20 * <li><strong>Evolution progress</strong>: Fitness improvements and convergence indicators</li>
21 * </ul>
22 *
23 * <p>Common termination strategies include:
24 * <ul>
25 * <li><strong>Generation limit</strong>: Stop after a fixed number of generations</li>
26 * <li><strong>Fitness threshold</strong>: Stop when best fitness reaches a target value</li>
27 * <li><strong>Convergence detection</strong>: Stop when population diversity becomes too low</li>
28 * <li><strong>Stagnation detection</strong>: Stop when fitness stops improving for N generations</li>
29 * <li><strong>Time limit</strong>: Stop after a specified duration</li>
30 * <li><strong>Resource limit</strong>: Stop when computational budget is exhausted</li>
31 * </ul>
32 *
33 * <p>Best practices for termination criteria:
34 * <ul>
35 * <li><strong>Multiple criteria</strong>: Combine several conditions using logical operators</li>
36 * <li><strong>Problem-specific</strong>: Adapt criteria to the characteristics of the optimization problem</li>
37 * <li><strong>Configurable</strong>: Allow users to adjust termination parameters</li>
38 * <li><strong>Efficient</strong>: Minimize computational overhead of termination checks</li>
39 * </ul>
40 *
41 * @param <T> the type of the fitness values, must be comparable for fitness-based termination
42 * @see Terminations
43 * @see net.bmahe.genetics4j.core.EASystem
44 */
45 @FunctionalInterface
46 public interface Termination<T extends Comparable<T>> {
47
48 /**
49 * Determines whether the evolutionary algorithm should terminate.
50 *
51 * <p>This method is called after each generation to check if any termination criteria have been satisfied. The
52 * implementation should evaluate the current state of evolution and return {@code true} if the algorithm should
53 * stop, {@code false} otherwise.
54 *
55 * <p>The method has access to:
56 * <ul>
57 * <li>Current generation number (starting from 0)</li>
58 * <li>Current population genotypes</li>
59 * <li>Current fitness values for all individuals</li>
60 * <li>Algorithm configuration and parameters</li>
61 * </ul>
62 *
63 * <p>Implementations should be efficient as this method is called frequently during evolution. Complex termination
64 * logic should cache intermediate results when possible.
65 *
66 * @param eaConfiguration the evolutionary algorithm configuration containing parameters
67 * @param generation the current generation number (0-based)
68 * @param population the list of genotypes in the current population
69 * @param fitness the list of fitness values corresponding to each genotype
70 * @return {@code true} if the algorithm should terminate, {@code false} to continue evolving
71 * @throws IllegalArgumentException if any parameter is null or if population and fitness lists have different sizes
72 * @throws RuntimeException if termination evaluation fails due to computational errors
73 */
74 boolean isDone(final AbstractEAConfiguration<T> eaConfiguration, final long generation,
75 final List<Genotype> population, final List<T> fitness);
76 }