ChosenOtherChromosome.java

package net.bmahe.genetics4j.neat.combination.parentcompare;

import net.bmahe.genetics4j.neat.chromosomes.NeatChromosome;

/**
 * Represents the result of parent comparison during NEAT genetic crossover.
 * 
 * <p>ChosenOtherChromosome is a simple record that encapsulates the result of comparing two
 * parent chromosomes for NEAT crossover operations. It designates which parent should be
 * considered "chosen" (typically the fitter parent) and which should be "other" for the
 * purposes of biased gene inheritance.
 * 
 * <p>Usage in NEAT crossover:
 * <ul>
 * <li><strong>Inheritance bias</strong>: Chosen parent typically contributes disjoint and excess genes</li>
 * <li><strong>Gene selection</strong>: Inheritance threshold applied relative to chosen parent</li>
 * <li><strong>Topology guidance</strong>: Chosen parent's structure often forms the offspring base</li>
 * <li><strong>Equal fitness handling</strong>: Both parents may be treated equally when fitness is identical</li>
 * </ul>
 * 
 * <p>Parent role significance:
 * <ul>
 * <li><strong>Chosen parent</strong>: Usually the fitter parent, contributes more genes to offspring</li>
 * <li><strong>Other parent</strong>: Usually the less fit parent, contributes fewer genes</li>
 * <li><strong>Matching genes</strong>: Both parents can contribute genes with equal probability (biased)</li>
 * <li><strong>Gene re-enabling</strong>: Both parents considered for connection state decisions</li>
 * </ul>
 * 
 * <p>Common usage patterns:
 * <pre>{@code
 * // Result of parent comparison
 * ChosenOtherChromosome comparison = parentHandler.compare(
 *     policy, parent1, parent2, fitnessComparison
 * );
 * 
 * // Extract parents for crossover
 * NeatChromosome chosenParent = comparison.chosen();
 * NeatChromosome otherParent = comparison.other();
 * 
 * // Use in gene inheritance decisions
 * if (fitnessComparison != 0 || random.nextDouble() < inheritanceThreshold) {
 *     // Inherit from chosen parent
 *     inheritGene(chosenParent.getConnections().get(index));
 * } else {
 *     // Inherit from other parent
 *     inheritGene(otherParent.getConnections().get(index));
 * }
 * 
 * // Access parent properties
 * int numInputs = chosenParent.getNumInputs();
 * float minWeight = chosenParent.getMinWeightValue();
 * List<Connection> chosenConnections = chosenParent.getConnections();
 * List<Connection> otherConnections = otherParent.getConnections();
 * }</pre>
 * 
 * <p>Immutability and value semantics:
 * <ul>
 * <li><strong>Immutable</strong>: Record provides immutability for safe passing between methods</li>
 * <li><strong>Value equality</strong>: Two instances are equal if both chosen and other chromosomes match</li>
 * <li><strong>Compact representation</strong>: Minimal memory overhead with clear semantic meaning</li>
 * <li><strong>Null safety</strong>: Both chromosomes are expected to be non-null in valid comparisons</li>
 * </ul>
 * 
 * <p>Integration with comparison handlers:
 * <ul>
 * <li><strong>Return type</strong>: Standard return type for ParentComparisonHandler.compare()</li>
 * <li><strong>Type safety</strong>: Ensures correct parent roles in crossover operations</li>
 * <li><strong>Clear semantics</strong>: Eliminates confusion about which parent is which</li>
 * <li><strong>Consistent interface</strong>: All comparison handlers return same type</li>
 * </ul>
 * 
 * @param chosen the chromosome designated as "chosen" (typically fitter) for preferred inheritance
 * @param other the chromosome designated as "other" (typically less fit) for secondary inheritance
 * @see ParentComparisonHandler
 * @see net.bmahe.genetics4j.neat.combination.NeatChromosomeCombinator
 * @see NeatChromosome
 */
public record ChosenOtherChromosome(NeatChromosome chosen, NeatChromosome other) {
}