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().get(index));
42 * } else {
43 * // Inherit from other parent
44 * inheritGene(otherParent.getConnections().get(index));
45 * }
46 *
47 * // Access parent properties
48 * int numInputs = chosenParent.getNumInputs();
49 * float minWeight = chosenParent.getMinWeightValue();
50 * List<Connection> chosenConnections = chosenParent.getConnections();
51 * List<Connection> otherConnections = otherParent.getConnections();
52 * }</pre>
53 *
54 * <p>Immutability and value semantics:
55 * <ul>
56 * <li><strong>Immutable</strong>: Record provides immutability for safe passing between methods</li>
57 * <li><strong>Value equality</strong>: Two instances are equal if both chosen and other chromosomes match</li>
58 * <li><strong>Compact representation</strong>: Minimal memory overhead with clear semantic meaning</li>
59 * <li><strong>Null safety</strong>: Both chromosomes are expected to be non-null in valid comparisons</li>
60 * </ul>
61 *
62 * <p>Integration with comparison handlers:
63 * <ul>
64 * <li><strong>Return type</strong>: Standard return type for ParentComparisonHandler.compare()</li>
65 * <li><strong>Type safety</strong>: Ensures correct parent roles in crossover operations</li>
66 * <li><strong>Clear semantics</strong>: Eliminates confusion about which parent is which</li>
67 * <li><strong>Consistent interface</strong>: All comparison handlers return same type</li>
68 * </ul>
69 *
70 * @param chosen the chromosome designated as "chosen" (typically fitter) for preferred inheritance
71 * @param other the chromosome designated as "other" (typically less fit) for secondary inheritance
72 * @see ParentComparisonHandler
73 * @see net.bmahe.genetics4j.neat.combination.NeatChromosomeCombinator
74 * @see NeatChromosome
75 */
76 public record ChosenOtherChromosome(NeatChromosome chosen, NeatChromosome other) {
77 }