1 package net.bmahe.genetics4j.neat;
2
3 import org.apache.commons.lang3.Validate;
4 import org.immutables.value.Value;
5
6 /**
7 * Represents a neural network connection in the NEAT (NeuroEvolution of Augmenting Topologies) algorithm.
8 *
9 * <p>A Connection is a fundamental building block of NEAT neural networks, representing a weighted link between two
10 * nodes. Each connection carries essential information for network topology, genetic operations, and evolutionary
11 * tracking through innovation numbers. Connections can be enabled or disabled, allowing for dynamic network topology
12 * exploration during evolution.
13 *
14 * <p>Key properties:
15 * <ul>
16 * <li><strong>Source and target nodes</strong>: Define the directed connection in the network graph</li>
17 * <li><strong>Connection weight</strong>: Determines the strength and polarity of signal transmission</li>
18 * <li><strong>Enabled state</strong>: Controls whether the connection participates in network computation</li>
19 * <li><strong>Innovation number</strong>: Unique identifier for genetic alignment and historical tracking</li>
20 * </ul>
21 *
22 * <p>NEAT algorithm integration:
23 * <ul>
24 * <li><strong>Genetic crossover</strong>: Innovation numbers enable proper gene alignment between parents</li>
25 * <li><strong>Structural mutations</strong>: Connections can be added, removed, or have their state toggled</li>
26 * <li><strong>Weight evolution</strong>: Connection weights are subject to mutation and optimization</li>
27 * <li><strong>Topology innovation</strong>: New connections track the historical order of structural changes</li>
28 * </ul>
29 *
30 * <p>Network computation role:
31 * <ul>
32 * <li><strong>Signal propagation</strong>: Enabled connections transmit weighted signals between nodes</li>
33 * <li><strong>Network evaluation</strong>: Only enabled connections participate in forward propagation</li>
34 * <li><strong>Topology dynamics</strong>: Enable/disable states allow topology exploration without gene loss</li>
35 * <li><strong>Weight optimization</strong>: Connection weights are evolved to optimize network performance</li>
36 * </ul>
37 *
38 * <p>Common usage patterns:
39 *
40 * <pre>{@code
41 * // Create a new connection
42 * Connection connection = Connection.of(
43 * 0, // from node index
44 * 3, // to node index
45 * 0.75f, // connection weight
46 * true, // enabled state
47 * 42 // innovation number
48 * );
49 *
50 * // Builder pattern for complex construction
51 * Connection connection = Connection.builder()
52 * .fromNodeIndex(1)
53 * .toNodeIndex(4)
54 * .weight(-0.5f)
55 * .isEnabled(false)
56 * .innovation(15)
57 * .build();
58 *
59 * // Copy with modifications
60 * Connection modifiedConnection = Connection.builder().from(connection).weight(connection.weight() + 0.1f).build();
61 * }</pre>
62 *
63 * <p>Innovation number significance:
64 * <ul>
65 * <li><strong>Historical marking</strong>: Tracks when each connection type first appeared in evolution</li>
66 * <li><strong>Genetic alignment</strong>: Enables meaningful crossover between different network topologies</li>
67 * <li><strong>Compatibility distance</strong>: Used to measure genetic similarity for speciation</li>
68 * <li><strong>Structural tracking</strong>: Maintains evolutionary history of network topology changes</li>
69 * </ul>
70 *
71 * <p>Connection state management:
72 * <ul>
73 * <li><strong>Enabled connections</strong>: Actively participate in network computation</li>
74 * <li><strong>Disabled connections</strong>: Preserved in genome but don't affect network output</li>
75 * <li><strong>State mutations</strong>: Can toggle between enabled/disabled states during evolution</li>
76 * <li><strong>Structural preservation</strong>: Disabled connections maintain genetic information</li>
77 * </ul>
78 *
79 * <p>Validation and constraints:
80 * <ul>
81 * <li><strong>Node indices</strong>: Must be non-negative and reference valid nodes in the network</li>
82 * <li><strong>Innovation numbers</strong>: Must be non-negative and unique within the population context</li>
83 * <li><strong>Self-connections</strong>: Typically not allowed (from and to nodes must be different)</li>
84 * <li><strong>Weight bounds</strong>: While not enforced, weights typically range within reasonable bounds</li>
85 * </ul>
86 *
87 * @see NeatChromosome
88 * @see InnovationManager
89 * @see FeedForwardNetwork
90 * @see net.bmahe.genetics4j.neat.mutation.AddConnectionPolicyHandler
91 */
92 @Value.Immutable
93 public interface Connection {
94
95 /**
96 * Returns the index of the source node for this connection.
97 *
98 * @return the source node index (non-negative)
99 */
100 @Value.Parameter
101 int fromNodeIndex();
102
103 /**
104 * Returns the index of the target node for this connection.
105 *
106 * @return the target node index (non-negative)
107 */
108 @Value.Parameter
109 int toNodeIndex();
110
111 /**
112 * Returns the weight of this connection.
113 *
114 * <p>The weight determines the strength and polarity of signal transmission through this connection. Positive
115 * weights amplify signals, negative weights invert them, and zero weights effectively disable signal transmission.
116 *
117 * @return the connection weight
118 */
119 @Value.Parameter
120 float weight();
121
122 /**
123 * Returns whether this connection is enabled.
124 *
125 * <p>Enabled connections participate in network computation and signal propagation. Disabled connections are
126 * preserved in the genome but do not affect network output, allowing for topology exploration without gene loss.
127 *
128 * @return true if the connection is enabled, false otherwise
129 */
130 @Value.Parameter
131 boolean isEnabled();
132
133 /**
134 * Returns the innovation number for this connection.
135 *
136 * <p>Innovation numbers are unique identifiers that track the historical order of structural mutations in the NEAT
137 * algorithm. They enable proper gene alignment during crossover and are used to calculate compatibility distance for
138 * speciation.
139 *
140 * @return the innovation number (non-negative)
141 */
142 @Value.Parameter
143 int innovation();
144
145 @Value.Check
146 default void check() {
147 Validate.isTrue(fromNodeIndex() >= 0);
148 Validate.isTrue(toNodeIndex() >= 0);
149 Validate.isTrue(innovation() >= 0);
150 }
151
152 static class Builder extends ImmutableConnection.Builder {
153 }
154
155 static Builder builder() {
156 return new Builder();
157 }
158
159 /**
160 * Creates a new connection with the specified parameters.
161 *
162 * @param from the source node index
163 * @param to the target node index
164 * @param weight the connection weight
165 * @param isEnabled whether the connection is enabled
166 * @param innovation the innovation number
167 * @return a new connection instance
168 * @throws IllegalArgumentException if node indices or innovation number are negative
169 */
170 static Connection of(final int from, final int to, final float weight, final boolean isEnabled,
171 final int innovation) {
172 return ImmutableConnection.of(from, to, weight, isEnabled, innovation);
173 }
174
175 /**
176 * Creates a copy of the specified connection.
177 *
178 * @param original the connection to copy
179 * @return a new connection instance with the same properties as the original
180 */
181 static Connection copyOf(Connection original) {
182 return ImmutableConnection.copyOf(original);
183 }
184 }