SelectiveRefinementTournament.java
package net.bmahe.genetics4j.core.spec.selection;
import java.util.Comparator;
import org.apache.commons.lang3.Validate;
import org.immutables.value.Value;
import net.bmahe.genetics4j.core.Individual;
/**
* Selective Refinement Tournament selection strategy that enhances traditional tournament selection by applying an
* additional refinement step to a subset of candidates.
* <p>This selection mechanism first performs standard tournament selection, then applies a secondary refinement process
* using a custom comparator to a portion of the selected candidates. This allows for more sophisticated selection
* criteria beyond simple fitness-based comparison.</p>
*
* <h3>Algorithm Overview:</h3>
* <ol>
* <li>Conduct standard tournament selection based on the configured tournament parameters</li>
* <li>Apply refinement using the provided comparator to a fraction of candidates (determined by refinementRatio)</li>
* <li>Return the refined selection results</li>
* </ol>
*
* <h3>Use Cases:</h3>
* <ul>
* <li>Multi-objective optimization where secondary criteria matter</li>
* <li>Diversity preservation by considering genetic distance in refinement</li>
* <li>Age-based selection refinement in evolutionary strategies</li>
* <li>Custom fitness landscape exploration with domain-specific comparators</li>
* </ul>
*
* @param <T> the fitness type, must be Comparable
*
* @see Tournament
* @see SelectionPolicy
* @see net.bmahe.genetics4j.core.selection.SelectiveRefinementTournamentSelector
*/
@Value.Immutable
public abstract class SelectiveRefinementTournament<T extends Comparable<T>> implements SelectionPolicy {
/**
* Gets the base tournament configuration used for initial selection.
* <p>This tournament defines the primary selection mechanism including the number of candidates per tournament and
* the comparison strategy for determining winners.</p>
*
* @return the tournament configuration for initial selection
*/
public abstract Tournament<T> tournament();
/**
* Gets the comparator used for refining the selection results.
* <p>This comparator is applied during the refinement phase to reorder or filter a subset of the initially selected
* individuals. It allows for secondary selection criteria beyond basic fitness comparison, such as diversity
* measures, age-based preferences, or multi-objective considerations.</p>
*
* @return the comparator for refinement selection
*/
public abstract Comparator<Individual<T>> refinementComparator();
/**
* Gets the ratio of candidates that undergo refinement selection.
* <p>This value determines what fraction of the initially selected candidates will be subject to the refinement
* process using the refinement comparator. A value of 0.0 means no refinement (equivalent to standard tournament),
* while 1.0 means all candidates undergo refinement.</p>
*
* @return the refinement ratio, must be between 0.0 and 1.0 inclusive
*/
public abstract float refinementRatio();
/**
* Validates the configuration parameters for this selection policy.
* <p>Ensures that the refinement ratio is within the valid range of [0.0, 1.0]. This method is automatically called
* by the Immutables framework during object construction.</p>
*
* @throws IllegalArgumentException if refinement ratio is not between 0.0 and 1.0 inclusive
*/
@Value.Check
public void check() {
Validate.inclusiveBetween(0, 1, refinementRatio());
}
/**
* Builder class for constructing SelectiveRefinementTournament instances.
* <p>Provides a fluent API for configuring all aspects of the selective refinement tournament selection strategy.
* All parameters are required except where noted.</p>
*
* @param <T> the fitness type, must be Comparable
*
* @see SelectiveRefinementTournament
*/
public static class Builder<T extends Comparable<T>> extends ImmutableSelectiveRefinementTournament.Builder<T> {
}
public static <U extends Comparable<U>> Builder<U> builder() {
return new Builder<U>();
}
}