ConnectionPair.java
package net.bmahe.genetics4j.neat;
/**
* Represents a pair of node indices defining a potential connection in NEAT neural networks.
*
* <p>ConnectionPair is a simple record that encapsulates the source and target node indices
* for a neural network connection. This immutable data structure is primarily used as a key
* for innovation number caching in the InnovationManager, enabling efficient lookup and
* assignment of innovation numbers based on connection topology.
*
* <p>Key characteristics:
* <ul>
* <li><strong>Immutable</strong>: Record provides immutability for safe use as hash keys</li>
* <li><strong>Value semantics</strong>: Equality based on both from and to node indices</li>
* <li><strong>Hash key</strong>: Optimized for use in hash-based collections</li>
* <li><strong>Lightweight</strong>: Minimal memory overhead with just two integer fields</li>
* </ul>
*
* <p>Usage in innovation tracking:
* <ul>
* <li><strong>Cache key</strong>: Used as key in InnovationManager's innovation cache</li>
* <li><strong>Connection identification</strong>: Uniquely identifies connection types</li>
* <li><strong>Historical tracking</strong>: Enables consistent innovation number assignment</li>
* <li><strong>Population consistency</strong>: Same connection pairs get same innovation numbers</li>
* </ul>
*
* <p>Common usage patterns:
* <pre>{@code
* // Create connection pair for innovation tracking
* ConnectionPair pair = new ConnectionPair(0, 3); // Input 0 -> Output 3
*
* // Use as cache key in innovation manager
* Map<ConnectionPair, Integer> innovationCache = new HashMap<>();
* int innovationNumber = innovationCache.computeIfAbsent(pair,
* k -> innovationManager.getNextInnovationNumber());
*
* // Connection pair represents potential connection topology
* List<ConnectionPair> possibleConnections = List.of(
* new ConnectionPair(0, 2), // Input 0 -> Output 2
* new ConnectionPair(1, 2), // Input 1 -> Output 2
* new ConnectionPair(0, 3), // Input 0 -> Output 3
* new ConnectionPair(1, 3) // Input 1 -> Output 3
* );
* }</pre>
*
* <p>Integration with NEAT algorithm:
* <ul>
* <li><strong>Innovation management</strong>: Key component of innovation number caching</li>
* <li><strong>Structural mutations</strong>: Used when adding new connections to networks</li>
* <li><strong>Genetic tracking</strong>: Enables consistent gene identification across population</li>
* <li><strong>Crossover operations</strong>: Supports gene alignment during recombination</li>
* </ul>
*
* <p>Performance considerations:
* <ul>
* <li><strong>Efficient hashing</strong>: Record provides optimized hash code implementation</li>
* <li><strong>Memory efficient</strong>: Compact representation with minimal overhead</li>
* <li><strong>Cache friendly</strong>: Small size improves cache locality</li>
* <li><strong>GC efficient</strong>: Immutable objects reduce garbage collection pressure</li>
* </ul>
*
* <p>Value semantics:
* <ul>
* <li><strong>Equality</strong>: Two pairs are equal if both from and to indices match</li>
* <li><strong>Hash code</strong>: Computed from both node indices for efficient hash table usage</li>
* <li><strong>String representation</strong>: Readable format showing connection direction</li>
* <li><strong>Comparison</strong>: Natural ordering based on from index, then to index</li>
* </ul>
*
* @param from the source node index of the connection
* @param to the target node index of the connection
* @see InnovationManager
* @see Connection
* @see net.bmahe.genetics4j.neat.mutation.AddConnectionPolicyHandler
*/
public record ConnectionPair(int from, int to) {
}