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
9 * parent chromosomes for NEAT crossover operations. It designates which parent should be
10 * considered "chosen" (typically the fitter parent) and which should be "other" for the
11 * purposes of biased gene inheritance.
12 *
13 * <p>Usage in NEAT crossover:
14 * <ul>
15 * <li><strong>Inheritance bias</strong>: Chosen parent typically contributes disjoint and excess genes</li>
16 * <li><strong>Gene selection</strong>: Inheritance threshold applied relative to chosen parent</li>
17 * <li><strong>Topology guidance</strong>: Chosen parent's structure often forms the offspring base</li>
18 * <li><strong>Equal fitness handling</strong>: Both parents may be treated equally when fitness is identical</li>
19 * </ul>
20 *
21 * <p>Parent role significance:
22 * <ul>
23 * <li><strong>Chosen parent</strong>: Usually the fitter parent, contributes more genes to offspring</li>
24 * <li><strong>Other parent</strong>: Usually the less fit parent, contributes fewer genes</li>
25 * <li><strong>Matching genes</strong>: Both parents can contribute genes with equal probability (biased)</li>
26 * <li><strong>Gene re-enabling</strong>: Both parents considered for connection state decisions</li>
27 * </ul>
28 *
29 * <p>Common usage patterns:
30 * <pre>{@code
31 * // Result of parent comparison
32 * ChosenOtherChromosome comparison = parentHandler.compare(
33 * policy, parent1, parent2, fitnessComparison
34 * );
35 *
36 * // Extract parents for crossover
37 * NeatChromosome chosenParent = comparison.chosen();
38 * NeatChromosome otherParent = comparison.other();
39 *
40 * // Use in gene inheritance decisions
41 * if (fitnessComparison != 0 || random.nextDouble() < inheritanceThreshold) {
42 * // Inherit from chosen parent
43 * inheritGene(chosenParent.getConnections().get(index));
44 * } else {
45 * // Inherit from other parent
46 * inheritGene(otherParent.getConnections().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 }