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