1 package net.bmahe.genetics4j.core.spec.selection;
2
3 import java.util.Comparator;
4
5 import org.apache.commons.lang3.Validate;
6 import org.immutables.value.Value;
7
8 import net.bmahe.genetics4j.core.Individual;
9
10 /**
11 * Selective Refinement Tournament selection strategy that enhances traditional tournament selection by applying an
12 * additional refinement step to a subset of candidates.
13 * <p>This selection mechanism first performs standard tournament selection, then applies a secondary refinement process
14 * using a custom comparator to a portion of the selected candidates. This allows for more sophisticated selection
15 * criteria beyond simple fitness-based comparison.</p>
16 *
17 * <h3>Algorithm Overview:</h3>
18 * <ol>
19 * <li>Conduct standard tournament selection based on the configured tournament parameters</li>
20 * <li>Apply refinement using the provided comparator to a fraction of candidates (determined by refinementRatio)</li>
21 * <li>Return the refined selection results</li>
22 * </ol>
23 *
24 * <h3>Use Cases:</h3>
25 * <ul>
26 * <li>Multi-objective optimization where secondary criteria matter</li>
27 * <li>Diversity preservation by considering genetic distance in refinement</li>
28 * <li>Age-based selection refinement in evolutionary strategies</li>
29 * <li>Custom fitness landscape exploration with domain-specific comparators</li>
30 * </ul>
31 *
32 * @param <T> the fitness type, must be Comparable
33 *
34 * @see Tournament
35 * @see SelectionPolicy
36 * @see net.bmahe.genetics4j.core.selection.SelectiveRefinementTournamentSelector
37 */
38 @Value.Immutable
39 public abstract class SelectiveRefinementTournament<T extends Comparable<T>> implements SelectionPolicy {
40
41 /**
42 * Gets the base tournament configuration used for initial selection.
43 * <p>This tournament defines the primary selection mechanism including the number of candidates per tournament and
44 * the comparison strategy for determining winners.</p>
45 *
46 * @return the tournament configuration for initial selection
47 */
48 public abstract Tournament<T> tournament();
49
50 /**
51 * Gets the comparator used for refining the selection results.
52 * <p>This comparator is applied during the refinement phase to reorder or filter a subset of the initially selected
53 * individuals. It allows for secondary selection criteria beyond basic fitness comparison, such as diversity
54 * measures, age-based preferences, or multi-objective considerations.</p>
55 *
56 * @return the comparator for refinement selection
57 */
58 public abstract Comparator<Individual<T>> refinementComparator();
59
60 /**
61 * Gets the ratio of candidates that undergo refinement selection.
62 * <p>This value determines what fraction of the initially selected candidates will be subject to the refinement
63 * process using the refinement comparator. A value of 0.0 means no refinement (equivalent to standard tournament),
64 * while 1.0 means all candidates undergo refinement.</p>
65 *
66 * @return the refinement ratio, must be between 0.0 and 1.0 inclusive
67 */
68 public abstract float refinementRatio();
69
70 /**
71 * Validates the configuration parameters for this selection policy.
72 * <p>Ensures that the refinement ratio is within the valid range of [0.0, 1.0]. This method is automatically called
73 * by the Immutables framework during object construction.</p>
74 *
75 * @throws IllegalArgumentException if refinement ratio is not between 0.0 and 1.0 inclusive
76 */
77 @Value.Check
78 public void check() {
79 Validate.inclusiveBetween(0, 1, refinementRatio());
80 }
81
82 /**
83 * Builder class for constructing SelectiveRefinementTournament instances.
84 * <p>Provides a fluent API for configuring all aspects of the selective refinement tournament selection strategy.
85 * All parameters are required except where noted.</p>
86 *
87 * @param <T> the fitness type, must be Comparable
88 *
89 * @see SelectiveRefinementTournament
90 */
91 public static class Builder<T extends Comparable<T>> extends ImmutableSelectiveRefinementTournament.Builder<T> {
92 }
93
94 public static <U extends Comparable<U>> Builder<U> builder() {
95 return new Builder<U>();
96 }
97 }