1 package net.bmahe.genetics4j.neat.combination.parentcompare;
2
3 import net.bmahe.genetics4j.neat.chromosomes.NeatChromosome;
4 import net.bmahe.genetics4j.neat.spec.combination.parentcompare.ParentComparisonPolicy;
5
6 /**
7 * Interface for handling parent comparison strategies during NEAT genetic crossover.
8 *
9 * <p>ParentComparisonHandler defines the contract for comparing two parent chromosomes
10 * to determine which should be considered "chosen" (typically the fitter parent) and
11 * which should be considered "other" (typically the less fit parent) for inheritance
12 * decisions during NEAT crossover operations.
13 *
14 * <p>Purpose in NEAT crossover:
15 * <ul>
16 * <li><strong>Inheritance bias</strong>: Determines which parent contributes disjoint and excess genes</li>
17 * <li><strong>Fitness-based selection</strong>: Guides gene inheritance based on parent performance</li>
18 * <li><strong>Equal fitness handling</strong>: Provides strategy when parents have identical fitness</li>
19 * <li><strong>Policy abstraction</strong>: Allows pluggable comparison strategies</li>
20 * </ul>
21 *
22 * <p>Comparison result usage:
23 * <ul>
24 * <li><strong>Chosen parent</strong>: Usually contributes disjoint and excess genes</li>
25 * <li><strong>Other parent</strong>: May contribute genes when inheritance is unbiased</li>
26 * <li><strong>Matching genes</strong>: Randomly inherited from either parent with bias</li>
27 * <li><strong>Gene re-enabling</strong>: Both parents considered for connection state decisions</li>
28 * </ul>
29 *
30 * <p>Common implementation patterns:
31 * <pre>{@code
32 * // Simple fitness-based comparison handler
33 * public class FitnessComparisonHandler implements ParentComparisonHandler {
34 *
35 * public boolean canHandle(ParentComparisonPolicy policy) {
36 * return policy instanceof FitnessComparison;
37 * }
38 *
39 * public ChosenOtherChromosome compare(ParentComparisonPolicy policy,
40 * NeatChromosome first, NeatChromosome second, int fitnessComparison) {
41 * if (fitnessComparison >= 0) {
42 * return new ChosenOtherChromosome(first, second); // First is fitter
43 * } else {
44 * return new ChosenOtherChromosome(second, first); // Second is fitter
45 * }
46 * }
47 * }
48 *
49 * // Usage in crossover
50 * ParentComparisonHandler handler = new FitnessComparisonHandler();
51 * ChosenOtherChromosome result = handler.compare(
52 * policy, parent1, parent2, fitnessComparator.compare(fitness1, fitness2)
53 * );
54 * NeatChromosome chosenParent = result.chosen();
55 * NeatChromosome otherParent = result.other();
56 * }</pre>
57 *
58 * <p>Integration with crossover:
59 * <ul>
60 * <li><strong>Gene inheritance</strong>: Chosen parent typically dominates gene contribution</li>
61 * <li><strong>Bias application</strong>: Inheritance threshold applied relative to chosen parent</li>
62 * <li><strong>Topology preservation</strong>: Chosen parent's topology forms the base structure</li>
63 * <li><strong>Innovation tracking</strong>: Both parents contribute to innovation alignment</li>
64 * </ul>
65 *
66 * <p>Policy-based design:
67 * <ul>
68 * <li><strong>Strategy pattern</strong>: Different policies enable different comparison strategies</li>
69 * <li><strong>Extensibility</strong>: New comparison strategies can be added without changing crossover code</li>
70 * <li><strong>Configuration</strong>: Comparison behavior controlled by policy parameters</li>
71 * <li><strong>Testing</strong>: Easy to test different comparison strategies in isolation</li>
72 * </ul>
73 *
74 * @see ParentComparisonPolicy
75 * @see ChosenOtherChromosome
76 * @see NeatChromosome
77 * @see net.bmahe.genetics4j.neat.combination.NeatChromosomeCombinator
78 */
79 public interface ParentComparisonHandler {
80
81 /**
82 * Determines whether this handler can process the given parent comparison policy.
83 *
84 * <p>This method allows the handler registry to determine which handler is appropriate
85 * for a given comparison policy type, enabling polymorphic behavior in the crossover
86 * process.
87 *
88 * @param parentComparisonPolicy the comparison policy to check
89 * @return true if this handler can process the policy, false otherwise
90 */
91 boolean canHandle(final ParentComparisonPolicy parentComparisonPolicy);
92
93 /**
94 * Compares two parent chromosomes and determines which should be chosen for preferred inheritance.
95 *
96 * <p>This method analyzes the two parent chromosomes and their relative fitness to determine
97 * which parent should be considered "chosen" (typically the fitter parent) and which should
98 * be "other" for the purposes of biased gene inheritance during crossover.
99 *
100 * <p>The fitness comparison parameter provides the result of comparing the parents' fitness
101 * values: positive if first is fitter, negative if second is fitter, zero if equal.
102 *
103 * @param parentComparisonPolicy the comparison policy defining the comparison strategy
104 * @param first the first parent chromosome
105 * @param second the second parent chromosome
106 * @param fitnessComparison result of fitness comparison (positive: first fitter, negative: second fitter, zero: equal)
107 * @return ChosenOtherChromosome containing the chosen parent and other parent
108 */
109 ChosenOtherChromosome compare(final ParentComparisonPolicy parentComparisonPolicy, final NeatChromosome first,
110 final NeatChromosome second, final int fitnessComparison);
111 }