Skip to content

velora.wiring

Documentation

Customization: Wiring

The secret sauce to the sparse neuron connections.

LayerMasks dataclass

Storage container for layer masks.

Parameters:

Name Type Description Default
inter torch.Tensor

sparse weight mask for input layer

 required
command torch.Tensor

sparse weight mask for hidden layer

 required
motor torch.Tensor

sparse weight mask for output layer

 required
recurrent torch.Tensor

sparse weight mask for recurrent connections

 required
Source code in velora/wiring.py
Python
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
@dataclass
class LayerMasks:
    """
    Storage container for layer masks.

    Parameters:
        inter (torch.Tensor): sparse weight mask for input layer
        command (torch.Tensor): sparse weight mask for hidden layer
        motor (torch.Tensor): sparse weight mask for output layer
        recurrent (torch.Tensor): sparse weight mask for recurrent connections
    """

    inter: torch.Tensor
    command: torch.Tensor
    motor: torch.Tensor
    recurrent: torch.Tensor

NeuronCounts dataclass

Storage container for NCP neuron category counts.

Parameters:

Name Type Description Default
sensory int

number of input nodes

 required
inter int

number of decision nodes

 required
command int

number of high-level decision nodes

 required
motor int

number of output nodes

 required
Source code in velora/wiring.py
Python
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
@dataclass
class NeuronCounts:
    """
    Storage container for NCP neuron category counts.

    Parameters:
        sensory (int): number of input nodes
        inter (int): number of decision nodes
        command (int): number of high-level decision nodes
        motor (int): number of output nodes
    """

    sensory: int
    inter: int
    command: int
    motor: int

SynapseCounts dataclass

Storage container for NCP neuron synapse connection counts.

Parameters:

Name Type Description Default
sensory int

number of connections for input nodes

 required
inter int

number of connections for decision nodes

 required
command int

number of connections for high-level decision nodes

 required
motor int

number of connections for output nodes

 required
Source code in velora/wiring.py
Python
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
@dataclass
class SynapseCounts:
    """
    Storage container for NCP neuron synapse connection counts.

    Parameters:
        sensory (int): number of connections for input nodes
        inter (int): number of connections for decision nodes
        command (int): number of connections for high-level decision nodes
        motor (int): number of connections for output nodes
    """

    sensory: int
    inter: int
    command: int
    motor: int

Wiring

Creates sparse wiring masks for Neural Circuit Policy (NCP) Networks.

Note

NCPs have three layers:

  1. Inter (input)
  2. Command (hidden)
  3. Motor (output)
Source code in velora/wiring.py
Python
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
class Wiring:
    """
    Creates sparse wiring masks for Neural Circuit Policy (NCP) Networks.

    !!! note

        NCPs have three layers:

        1. Inter (input)
        2. Command (hidden)
        3. Motor (output)
    """

    def __init__(
        self,
        in_features: int,
        n_neurons: int,
        out_features: int,
        *,
        sparsity_level: float = 0.5,
    ) -> None:
        """
        Parameters:
            in_features (int): number of inputs (sensory nodes)
            n_neurons (int): number of decision nodes (inter and command nodes)
            out_features (int): number of outputs (motor nodes)
            sparsity_level (float, optional): controls the connection sparsity between neurons.

                Must be a value between `[0.1, 0.9]` -

                - When `0.1` neurons are very dense.
                - When `0.9` neurons are very sparse.
        """
        if sparsity_level < 0.1 or sparsity_level > 0.9:
            raise ValueError(f"'{sparsity_level=}' must be between '[0.1, 0.9]'.")

        self.density_level = 1.0 - sparsity_level

        self.n_command = max(int(0.4 * n_neurons), 1)
        self.n_inter = n_neurons - self.n_command

        self.counts, self._n_connections = self._set_counts(
            in_features,
            out_features,
        )
        self.masks = self._init_masks(in_features)

        self.build()

    @property
    def n_connections(self) -> SynapseCounts:
        """
        Neuron connection counts.

        Returns:
            connections (SynapseCounts): object containing neuron connection counts.
        """
        return self._n_connections

    def _init_masks(self, n_inputs: int) -> LayerMasks:
        """
        Helper method. Initializes all layer masks with zeros
        and stores them in a container.

        Parameters:
            n_inputs (int): the number of input nodes in the layer

        Returns:
            masks (LayerMasks): initialized layer masks.
        """
        return LayerMasks(
            inter=torch.zeros(
                (n_inputs, self.counts.inter),
                dtype=torch.int32,
            ),
            command=torch.zeros(
                (self.counts.inter, self.counts.command),
                dtype=torch.int32,
            ),
            motor=torch.zeros(
                (self.counts.command, self.counts.motor),
                dtype=torch.int32,
            ),
            recurrent=torch.zeros(
                (self.counts.command, self.counts.command),
                dtype=torch.int32,
            ),
        )

    def _synapse_count(self, count: int, scale: int = 1) -> int:
        """
        Helper method. Computes the synapse count for a single layer.

        Parameters:
            count (int): the number of neurons
            scale (int, optional): a scale factor

        Returns:
            count (int): synapse count.
        """
        return max(int(count * self.density_level * scale), 1)

    def _set_counts(
        self, in_features: int, out_features: int
    ) -> Tuple[NeuronCounts, SynapseCounts]:
        """
        Helper method. Computes the node layer and connection counts.

        Parameters:
            in_features (int): number of network input nodes
            out_features (int): number of network output nodes

        Returns:
            neuron_counts (NeuronCounts): object with neuron counts.
            synapse_counts (SynapseCounts): object with synapse connection counts.
        """
        counts = NeuronCounts(
            sensory=in_features,
            inter=self.n_inter,
            command=self.n_command,
            motor=out_features,
        )

        connections = SynapseCounts(
            sensory=self._synapse_count(self.n_inter),
            inter=self._synapse_count(self.n_command),
            command=self._synapse_count(self.n_command, scale=2),
            motor=self._synapse_count(self.n_command),
        )

        return counts, connections

    @staticmethod
    def polarity(shape: Tuple[int, ...] = (1,)) -> torch.IntTensor:
        """
        Utility method. Randomly selects a polarity of `-1` or `1`, `n` times
        based on shape.

        Parameters:
            shape (Tuple[int, ...]): size of the polarity matrix to generate.

        Returns:
            matrix (torch.Tensor): a polarity matrix filled with `-1` and `1`.
        """
        return torch.IntTensor(np.random.choice([-1, 1], shape))

    def _build_connections(self, mask: torch.Tensor, count: int) -> torch.Tensor:
        """
        Helper method. Randomly assigns connections to a set of nodes by populating
        its mask.

        !!! note "Performs two operations"

            1. Applies minimum connections (count) to all nodes.
            2. Checks all nodes have at least 1 connection.
                If not, adds a connection to 'missing' nodes.

        Parameters:
            mask (torch.Tensor): the initialized mask
            count (int): the number of connections per node

        Examples:
            Given 2 sensory (input) nodes and 5 inter neurons, we can define
            our first layer (inter) mask as:

            ```python
            import torch

            inter_mask = torch.zeros((2, 5), dtype=torch.int32)
            n_connections = 2

            inter_mask = wiring._build_connections(inter_mask, n_connections)

            # tensor([[-1,  1,  0,  0,  1],
            #         [ 0,  0, -1, -1,  0]], dtype=torch.int32)
            ```

        Returns:
            mask (torch.Tensor): updated layer sparsity mask.
        """
        num_nodes, num_cols = mask.shape

        # Add required connection count
        col_indices = torch.IntTensor(
            np.random.choice(num_cols, (num_nodes, count)),
        )
        polarities = self.polarity(col_indices.shape)
        row_indices = torch.arange(num_nodes).unsqueeze(1)

        mask[row_indices, col_indices] = polarities

        # Add missing node connections (if applicable)
        # -> Every node in 'num_cols' must have at least 1 connection
        # -> Column with all 0s = non-connected node
        is_col_all_zero = (mask == 0).all(dim=0)
        col_zero_indices = torch.nonzero(is_col_all_zero, as_tuple=True)[0]
        zero_count = col_zero_indices.numel()

        if zero_count > 0:
            # For each missing connection, randomly select a node and add connection
            # -> row = node
            row_indices = torch.randint(0, num_nodes, (zero_count,))
            random_polarities = self.polarity((zero_count,))
            mask[row_indices, col_zero_indices] = random_polarities

        return mask

    def _build_recurrent_connections(
        self, array: torch.Tensor, count: int
    ) -> torch.Tensor:
        """
        Utility method. Adds recurrent connections to a set of nodes.

        Used to simulate bidirectional connections between command neurons. Strictly
        used for visualization purposes.

        Parameters:
            array (torch.Tensor): an initialized matrix to update
            count (int): total number of connections to add

        Returns:
            matrix (torch.Tensor): the updated matrix.
        """
        n_nodes = array.shape[0]

        src = np.random.choice(n_nodes, count)
        dest = np.random.choice(n_nodes, count)
        polarities = self.polarity((count,))

        array[src, dest] = polarities
        return array

    def build(self) -> None:
        """
        Builds the mask wiring for each layer.

        !!! note "Layer format"

            Follows a three layer format, each with separate masks:

            1. Sensory -> inter
            2. Inter -> command
            3. Command -> motor

        Plus, command recurrent connections for ODE solvers.
        """
        # Sensory -> inter
        self.masks.inter = self._build_connections(
            self.masks.inter,
            self._n_connections.sensory,
        )
        # Inter -> command
        self.masks.command = self._build_connections(
            self.masks.command,
            self._n_connections.inter,
        )
        # Command -> motor
        self.masks.motor = self._build_connections(
            self.masks.motor,
            self._n_connections.command,
        )

        # Command -> command
        self.masks.recurrent = self._build_recurrent_connections(
            self.masks.recurrent,
            self._n_connections.command,
        )

    def data(self) -> Tuple[LayerMasks, NeuronCounts]:
        """
        Retrieves wiring storage containers for layer masks and node counts.

        Returns:
            masks (LayerMasks): the object containing layer masks.
            counts (NeuronCounts): the object containing node counts.
        """
        return self.masks, self.counts

n_connections property

Neuron connection counts.

Returns:

Name Type Description
connections SynapseCounts

object containing neuron connection counts.

__init__(in_features, n_neurons, out_features, *, sparsity_level=0.5)

Parameters:

Name Type Description Default
in_features int

number of inputs (sensory nodes)

 required
n_neurons int

number of decision nodes (inter and command nodes)

 required
out_features int

number of outputs (motor nodes)

 required
sparsity_level float

controls the connection sparsity between neurons.

Must be a value between [0.1, 0.9] -

  • When 0.1 neurons are very dense.
  • When 0.9 neurons are very sparse.
 0.5
Source code in velora/wiring.py
Python
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def __init__(
    self,
    in_features: int,
    n_neurons: int,
    out_features: int,
    *,
    sparsity_level: float = 0.5,
) -> None:
    """
    Parameters:
        in_features (int): number of inputs (sensory nodes)
        n_neurons (int): number of decision nodes (inter and command nodes)
        out_features (int): number of outputs (motor nodes)
        sparsity_level (float, optional): controls the connection sparsity between neurons.

            Must be a value between `[0.1, 0.9]` -

            - When `0.1` neurons are very dense.
            - When `0.9` neurons are very sparse.
    """
    if sparsity_level < 0.1 or sparsity_level > 0.9:
        raise ValueError(f"'{sparsity_level=}' must be between '[0.1, 0.9]'.")

    self.density_level = 1.0 - sparsity_level

    self.n_command = max(int(0.4 * n_neurons), 1)
    self.n_inter = n_neurons - self.n_command

    self.counts, self._n_connections = self._set_counts(
        in_features,
        out_features,
    )
    self.masks = self._init_masks(in_features)

    self.build()

build()

Builds the mask wiring for each layer.

Layer format

Follows a three layer format, each with separate masks:

  1. Sensory -> inter
  2. Inter -> command
  3. Command -> motor

Plus, command recurrent connections for ODE solvers.

Source code in velora/wiring.py
Python
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
def build(self) -> None:
    """
    Builds the mask wiring for each layer.

    !!! note "Layer format"

        Follows a three layer format, each with separate masks:

        1. Sensory -> inter
        2. Inter -> command
        3. Command -> motor

    Plus, command recurrent connections for ODE solvers.
    """
    # Sensory -> inter
    self.masks.inter = self._build_connections(
        self.masks.inter,
        self._n_connections.sensory,
    )
    # Inter -> command
    self.masks.command = self._build_connections(
        self.masks.command,
        self._n_connections.inter,
    )
    # Command -> motor
    self.masks.motor = self._build_connections(
        self.masks.motor,
        self._n_connections.command,
    )

    # Command -> command
    self.masks.recurrent = self._build_recurrent_connections(
        self.masks.recurrent,
        self._n_connections.command,
    )

data()

Retrieves wiring storage containers for layer masks and node counts.

Returns:

Name Type Description
masks LayerMasks

the object containing layer masks.
counts NeuronCounts

the object containing node counts.
Source code in velora/wiring.py
Python
330
331
332
333
334
335
336
337
338
def data(self) -> Tuple[LayerMasks, NeuronCounts]:
    """
    Retrieves wiring storage containers for layer masks and node counts.

    Returns:
        masks (LayerMasks): the object containing layer masks.
        counts (NeuronCounts): the object containing node counts.
    """
    return self.masks, self.counts

polarity(shape=(1,)) staticmethod

Utility method. Randomly selects a polarity of -1 or 1, n times based on shape.

Parameters:

Name Type Description Default
shape Tuple[int, ...]

size of the polarity matrix to generate.

 (1,)

Returns:

Name Type Description
matrix torch.Tensor

a polarity matrix filled with -1 and 1.
Source code in velora/wiring.py
Python
194
195
196
197
198
199
200
201
202
203
204
205
206
@staticmethod
def polarity(shape: Tuple[int, ...] = (1,)) -> torch.IntTensor:
    """
    Utility method. Randomly selects a polarity of `-1` or `1`, `n` times
    based on shape.

    Parameters:
        shape (Tuple[int, ...]): size of the polarity matrix to generate.

    Returns:
        matrix (torch.Tensor): a polarity matrix filled with `-1` and `1`.
    """
    return torch.IntTensor(np.random.choice([-1, 1], shape))