1 package net.bmahe.genetics4j.neat.combination.parentcompare;
2
3 import net.bmahe.genetics4j.neat.chromosomes.NeatChromosome;
4
5 /**
6 * Represents the result of parent comparison during NEAT genetic crossover.
7 *
8 * <p>ChosenOtherChromosome is a simple record that encapsulates the result of comparing two parent chromosomes for NEAT
9 * crossover operations. It designates which parent should be considered "chosen" (typically the fitter parent) and
10 * which should be "other" for the purposes of biased gene inheritance.
11 *
12 * <p>Usage in NEAT crossover:
13 * <ul>
14 * <li><strong>Inheritance bias</strong>: Chosen parent typically contributes disjoint and excess genes</li>
15 * <li><strong>Gene selection</strong>: Inheritance threshold applied relative to chosen parent</li>
16 * <li><strong>Topology guidance</strong>: Chosen parent's structure often forms the offspring base</li>
17 * <li><strong>Equal fitness handling</strong>: Both parents may be treated equally when fitness is identical</li>
18 * </ul>
19 *
20 * <p>Parent role significance:
21 * <ul>
22 * <li><strong>Chosen parent</strong>: Usually the fitter parent, contributes more genes to offspring</li>
23 * <li><strong>Other parent</strong>: Usually the less fit parent, contributes fewer genes</li>
24 * <li><strong>Matching genes</strong>: Both parents can contribute genes with equal probability (biased)</li>
25 * <li><strong>Gene re-enabling</strong>: Both parents considered for connection state decisions</li>
26 * </ul>
27 *
28 * <p>Common usage patterns:
29 *
30 * <pre>{@code
31 * // Result of parent comparison
32 * ChosenOtherChromosome comparison = parentHandler.compare(policy, parent1, parent2, fitnessComparison);
33 *
34 * // Extract parents for crossover
35 * NeatChromosome chosenParent = comparison.chosen();
36 * NeatChromosome otherParent = comparison.other();
37 *
38 * // Use in gene inheritance decisions
39 * if (fitnessComparison != 0 || random.nextDouble() < inheritanceThreshold) {
40 * // Inherit from chosen parent
41 * inheritGene(chosenParent.getConnections()
42 * .get(index));
43 * } else {
44 * // Inherit from other parent
45 * inheritGene(otherParent.getConnections()
46 * .get(index));
47 * }
48 *
49 * // Access parent properties
50 * int numInputs = chosenParent.getNumInputs();
51 * float minWeight = chosenParent.getMinWeightValue();
52 * List<Connection> chosenConnections = chosenParent.getConnections();
53 * List<Connection> otherConnections = otherParent.getConnections();
54 * }</pre>
55 *
56 * <p>Immutability and value semantics:
57 * <ul>
58 * <li><strong>Immutable</strong>: Record provides immutability for safe passing between methods</li>
59 * <li><strong>Value equality</strong>: Two instances are equal if both chosen and other chromosomes match</li>
60 * <li><strong>Compact representation</strong>: Minimal memory overhead with clear semantic meaning</li>
61 * <li><strong>Null safety</strong>: Both chromosomes are expected to be non-null in valid comparisons</li>
62 * </ul>
63 *
64 * <p>Integration with comparison handlers:
65 * <ul>
66 * <li><strong>Return type</strong>: Standard return type for ParentComparisonHandler.compare()</li>
67 * <li><strong>Type safety</strong>: Ensures correct parent roles in crossover operations</li>
68 * <li><strong>Clear semantics</strong>: Eliminates confusion about which parent is which</li>
69 * <li><strong>Consistent interface</strong>: All comparison handlers return same type</li>
70 * </ul>
71 *
72 * @param chosen the chromosome designated as "chosen" (typically fitter) for preferred inheritance
73 * @param other the chromosome designated as "other" (typically less fit) for secondary inheritance
74 * @see ParentComparisonHandler
75 * @see net.bmahe.genetics4j.neat.combination.NeatChromosomeCombinator
76 * @see NeatChromosome
77 */
78 public record ChosenOtherChromosome(NeatChromosome chosen, NeatChromosome other) {
79 }