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>();
	}
}