sinabs 3.0.4.dev25__py3-none-any.whl → 3.1.1__py3-none-any.whl

sinabs/backend/dynapcnn/io.py

@@ -34,11 +34,9 @@ def enable_timestamps(
     """
     Enable timestamps of the samna node.
 
-    Args
-    ----
-    device_id: str
-        Name of the device to initialize. Required for different existing APIs
-        for Speck chips
+    Args:
+        device_id: Name of the device to initialize. Required for different
+            existing APIs for Speck chips
     """
     device_id = standardize_device_id(device_id=device_id)
     device_info = device_map[device_id]
@@ -52,12 +50,9 @@ def disable_timestamps(
     """
     Disable timestamps of the samna node.
 
-    Args
-    ----
-
-    device_id: str
-        Name of the device to initialize. Required for different existing APIs
-        for Speck chips
+    Args:
+        device_id: Name of the device to initialize. Required for different
+            existing APIs for Speck chips
     """
     device_id = standardize_device_id(device_id=device_id)
     device_info = device_map[device_id]
@@ -71,11 +66,9 @@ def reset_timestamps(
     """
     Reset timestamps of the samna node.
 
-    Args
-    ----
-    device_id: str
-        Name of the device to initialize. Required for different existing APIs
-        for Speck chips
+    Args:
+        device_id: Name of the device to initialize. Required for different
+            existing APIs for Speck chips
     """
     device_id = standardize_device_id(device_id=device_id)
     device_info = device_map[device_id]
@@ -88,19 +81,11 @@ def events_to_xytp(event_list: List, layer: int) -> np.array:
     Convert an eventList read from `samna` to a numpy structured array of `x`, `y`, `t`,
     `channel`.
 
-    Parameters
-    ----------
-
-    event_list: List
-        A list comprising of events from samna API
-
-    layer: int
-        The index of layer for which the data needs to be converted
-
-    Returns
-    -------
+    Args:
+        event_list: A list comprising of events from samna API.
+        layer: The index of layer for which the data needs to be converted.
 
-    xytc: np.array
+    Returns:
         A numpy structured array with columns `x`, `y`, `t`, `channel`.
     """
     evs_filtered = list(
@@ -148,8 +133,11 @@ def get_device_map() -> Dict:
     # Group by device_type_name
     device_groups = groupby(devices, lambda x: x.device_type_name)
     # Switch keys from samna's device_type_name to device_type names
+    # -- guarantee is a supported device
     device_groups = {
-        device_type_map[k]: sort_devices(list(v)) for k, v in device_groups
+        device_type_map[k]: sort_devices(list(v))
+        for k, v in device_groups
+        if k in device_type_map
     }
     # Flat map
     for dev_type, dev_list in device_groups.items():
@@ -161,16 +149,11 @@ def get_device_map() -> Dict:
 def is_device_type(dev_info: samna.device.DeviceInfo, dev_type: str) -> bool:
     """Check if a DeviceInfo object is of a given device type `dev_type`
 
-    Args
-    ----
-
-    dev_info: samna.device.DeviceInfo
-        Device info object
-    dev_type: str
-        Device type as a string
+    Args:
+        dev_info: samna.device.DeviceInfo. Device info object.
+        dev_type: Device type as a string.
 
     Returns:
-    --------
         bool
     """
     return dev_info.device_type_name == device_types[dev_type]
@@ -179,17 +162,13 @@ def is_device_type(dev_info: samna.device.DeviceInfo, dev_type: str) -> bool:
 def discover_device(device_id: str):
     """Discover a samna device by device_name:device_id pair.
 
-    Args
-    ----
-
-    device_id: str
-        Device name/identifier (speck2fdevkit:0 or speck2edevkit:0 or ... )
-        The convention is similar to that of pytorch GPU identifier ie cuda:0 , cuda:1 etc.
-
-    Returns
-    -------
+    Args:
+        device_id: Device name/identifier (speck2fdevkit:0 or speck2edevkit:0)
+            The convention is similar to that of pytorch GPU identifier i.e.,
+            cuda:0 , cuda:1 etc.
 
-    device_info: samna.device.DeviceInfo
+    Returns:
+        samna.device.DeviceInfo
     """
     device_id = standardize_device_id(device_id=device_id)
     device_info = device_map[device_id]
@@ -199,21 +178,21 @@ def discover_device(device_id: str):
 def open_device(device_id: str):
     """Open device function.
 
-    Args
-    ----
-
-    device_id: str
-        device_name:device_id pair given as a string
-
-    Returns
-    -------
+    Args:
+        device_id: device_name:device_id pair given as a string
 
-    device_handle: samna.device.*
+    Returns:
         Device handle received from samna.
     """
     device_id = standardize_device_id(device_id=device_id)
     device_map = get_device_map()
-    device_info = device_map[device_id]
+    try:
+        device_info = device_map[device_id]
+    except KeyError:
+        msg = f"Device {device_id} has not been found. Make sure it is connected."
+        if device_map:
+            msg += "The following devices are available:\n" + "\n".join(device_map)
+        raise IOError(msg)
     device_handle = samna.device.open_device(device_info)
 
     if device_handle is not None:
@@ -225,12 +204,9 @@ def open_device(device_id: str):
 def close_device(device_id: str):
     """Close a device by device identifier.
 
-    Args
-    ----
-
-    device_id: str
-        device_name:device_id pair given as a string.
-        speck2fdevkit:0 or speck2edevkit:0 or speck2fdevkit:1 or ...
+    Args:
+        device_id: device_name:device_id pair given as a string.
+            speck2fdevkit:0 or speck2edevkit:0 or speck2fdevkit:1 or ...
     """
     device_id = standardize_device_id(device_id=device_id)
     device_info = device_map[device_id]
@@ -277,22 +253,15 @@ def calculate_neuron_address(
     """Calculate the neuron address on the devkit. This function is designed for ReadNeuronValue
     event to help the user check the neuron value of the SNN on the devkit.
 
-    Args
-    ----
-
-    x: int
-        x coordinate of the neuron
-    y: int
-        y coordinate of the neuron
-    c: int
-        channel index of the neuron
-    feature_map_size: Tuple[int, int, int]
-        the size of the feature map [channel, height, width]
-
-    Returns
-    ----
+    Args:
+        x: x coordinate of the neuron
+        y: y coordinate of the neuron
+        c: channel index of the neuron
+        feature_map_size: Tuple[int, int, int] the size of the feature map
+            [channel, height, width]
 
-    neuron_address: int
+    Returns:
+        neuron_address: int
     """
     # calculate how many bits it takes based on the feature map size
     channel, height, width = feature_map_size
@@ -317,22 +286,16 @@ def calculate_neuron_address(
 def neuron_address_to_cxy(
     address: int, feature_map_size: Tuple[int, int, int]
 ) -> Tuple:
-    """Calculate the c, x, y, coordinate of a neuron when the address of the NeuronValue event is
-    given.
-
-    Args
-    ----
+    """Calculate the c, x, y, coordinate of a neuron when the address of the
+    NeuronValue event is given.
 
-    address: int
-        the neuron address of the NeuronValue event
-    feature_map_size: Tuple[int, int, int]
-        the size of the feature map [channel, height, width]
-
-    Returns
-    ----
+    Args:
+        address (int): the neuron address of the NeuronValue event
+        feature_map_size: Tuple[int, int, int] the size of the feature map
+            [channel, height, width]
 
-    neuron_cxy: Tuple[int, int, int]
-        the [channel, x, y] of the neuron
+    Returns:
+        neuron_cxy: Tuple[int, int, int] the [channel, x, y] of the neuron
     """
     # calculate how many bits it takes based on the feature map size
     channel, height, width = feature_map_size

sinabs/backend/dynapcnn/mapping.py

@@ -1,10 +1,13 @@
 from collections import deque
 from copy import deepcopy
 from dataclasses import dataclass
-from typing import List, Optional, Tuple
+from typing import Dict, List, Optional, Tuple, Union
+
+import sinabs
 
 from .dvs_layer import DVSLayer
 from .dynapcnn_layer import DynapcnnLayer
+from .exceptions import InvalidModel
 
 
 @dataclass
@@ -27,16 +30,11 @@ def find_chip_layers(
 ) -> List[int]:
     """Find all layers where a given layer configuration fits.
 
-    Parameters
-    ----------
-    layer:
-        DynapcnnLayer
-
-    constraints:
-        A list of all the layer's constraints
+    Args:
+        layer: DynapCNNLayer.
+        constraints: A list of all the layer's constraints.
 
-    Returns
-    -------
+    Returns:
         A list of indices of layers where the given layer fits.
     """
     idx = [i for (i, constraint) in enumerate(constraints) if constraint.fits(layer)]
@@ -44,50 +42,71 @@ def find_chip_layers(
 
 
 def get_valid_mapping(
-    model: "DynapcnnNetwork", constraints: List[LayerConstraints]
-) -> List[Tuple[int, int]]:
+    layers: Dict[int, DynapcnnLayer], constraints: List[LayerConstraints]
+) -> Dict[int, int]:
     """Given a model, find a valid layer ordering for its placement within the constraints
     provided.
 
-    Parameters
-    ----------
-    model:
-        DynapcnnNetwork
-    constraints:
-        A list of all the layer's constraints
+    Args:
+        layers: Dict with layer indices as keys and DynapcnnLayer instances as values.
+        constraints: A list of all the layer's constraints.
 
-    Returns
-    -------
+    Returns:
+        Dict mapping from layer index (key) to assigned core ID (value).
     """
+    # Store layer indices and lists of possible target chips in separate lists
+    layer_indices = []
     layer_mapping = []
-
-    for layer in model.sequence:
-        if isinstance(layer, DynapcnnLayer):
-            layer_mapping.append(find_chip_layers(layer, constraints))
+    for layer_index, this_layer in layers.items():
+        # Skip DVSLayers
+        if isinstance(this_layer, DynapcnnLayer):
+            chip_layers = find_chip_layers(this_layer, constraints)
+            layer_mapping.append(chip_layers)
+            layer_indices.append(layer_index)
+        # Make sure only DynapCNNLayers and DVSLayers are passed
+        elif not isinstance(this_layer, DVSLayer):
+            raise ValueError(f"Found unexpected layer type: `{type(this_layer)}")
 
     graph = make_flow_graph(layer_mapping, len(constraints))
 
-    # Call mapping
+    # use Edmonds' Algorithm to find suitable cores for each DynapCNNLayer.
     new_graph = edmonds(graph, 0, len(graph) - 1)
+    netmap = recover_mapping(new_graph, len(layer_mapping))
 
-    netmap = recover_mapping(new_graph, layer_mapping)
-    return netmap
+    # Convert `netmap` to dict mapping from layer index to core ID
+    return {layer_idx: core_id for layer_idx, core_id in zip(layer_indices, netmap)}
 
 
 @dataclass
-class Edge:
+class FlowGraphEdge:
     s: int
     t: int
     cap: int
     flow: int = 0
-    rev: Optional["Edge"] = None
+    rev: Optional["FlowGraphEdge"] = None
 
     def __repr__(self):
-        return f"Edge from {self.s} to {self.t} with capacity {self.cap} and flow {self.flow}"
+        return f"FlowGraphEdge from {self.s} to {self.t} with capacity {self.cap} and flow {self.flow}"
+
+
+def edmonds(
+    graph: List[List[FlowGraphEdge]], source: int, sink: int, verbose: bool = False
+) -> List[List[FlowGraphEdge]]:
+    """Use Edmonds' Algorithm to compute flow of flow graph
+
+    Makes a copy of the graph. The original graph is not changed in place.
 
+    Args:
+        graph List[List[FlowGraphEdge]]): Flow graph representation. Each list
+            entry corresponds to a node and consists of a list holding the
+            outgoing edges from this node.
+        source (int): Index of source node within graph.
+        sind (int): Index of sink node within graph.
+        verbose (bool): Print detailed flow information if `True`.
 
-# graph is list of list of edges. Each edge is
-def edmonds(graph, source, sink, verbose: bool = False):
+    Returns:
+        New flow graph with calculated flow. Type is List[List[FlowGraphEdge]].
+    """
     graph = deepcopy(graph)
     flow = 0
     while True:
@@ -95,8 +114,8 @@ def edmonds(graph, source, sink, verbose: bool = False):
         q.append(source)
         pred = [None for _ in range(len(graph))]
         while len(q) != 0:
-            cur = q.popleft()
-            for edge in graph[cur]:
+            cur = q.popleft()  # current node index
+            for edge in graph[cur]:  # edges to/from current node
                 if pred[edge.t] is None and edge.t != source and edge.cap > edge.flow:
                     pred[edge.t] = edge
                     q.append(edge.t)
@@ -122,31 +141,33 @@ def edmonds(graph, source, sink, verbose: bool = False):
 
 def make_flow_graph(
     layer_mapping: List[List[int]], num_layers: int = 9
-) -> List[List[Edge]]:
-    """Make a flow graph given all possible chip layers for each DynapcnnCompatibleLayer layer.
-    Note that the flows are not computed yet. The flow for the graph generated here needs to be
-    populated by calling the method `edmonds`
-
-    Parameters
-    ----------
-    layer_mapping:
-        List of a list of all layer indices. Eg. [[1,3], [4, 6, 1]] for a two layer model
-    num_layers:
-        Number of layers on the chip
-
-    Returns
-    -------
-        graph: List[List[Edge]]
+) -> List[List[FlowGraphEdge]]:
+    """
+    Make a bipartite flow graph (flow network) given all possible chip layers
+    for each DynapCNNLayer layer. The goal is to formulate the mapping from
+    DynapCNNLayer instance to chip layer as a bipartite matching problem. Note that the
+    flows are not computed yet. The flow for the graph generated here needs to
+    be populated by calling the method `edmonds`.
+
+    Args:
+        layer_mapping: List of a list of matching chip core indices for each DynapCNNLayer instance.
+            Eg. [[1,3], [4, 6, 1]] for a two layer model, where each integer is a core index.
+        num_layers (int): Number of layers on the chip.
+
+    Returns:
+        Flow graph representation. Each list entry corresponds to a node and consists
+        of a list holding the outgoing edges from this node.
+        The returned object is of type List[List[FlowGraphEdge]].
     """
     graph = []
     # add all our nodes
     # one source node
     graph.append([])
     # one node for every layer that will be mapped
-    for x in range(len(layer_mapping)):
+    for __ in range(len(layer_mapping)):
         graph.append([])
     # one node for every chip layer
-    for x in range(num_layers):
+    for __ in range(num_layers):
         graph.append([])
     # one sink node
     graph.append([])
@@ -154,42 +175,57 @@ def make_flow_graph(
     target_offset = len(layer_mapping) + 1
     # first from source to all layers
     for i in range(len(layer_mapping)):
-        graph[0].append(Edge(s=0, t=i + 1, cap=1, flow=0))
-        # add the reverse edge
-        graph[i + 1].append(Edge(s=i + 1, t=0, cap=0, flow=0))
+        source_to_layer = FlowGraphEdge(s=0, t=i + 1, cap=1, flow=0)
+        layer_to_source = FlowGraphEdge(s=i + 1, t=0, cap=0, flow=0)
         # fill in reverse pointers
-        graph[0][-1].rev = graph[i + 1][-1]
-        graph[i + 1][-1].rev = graph[0][-1]
+        source_to_layer.rev = layer_to_source
+        layer_to_source.rev = source_to_layer
+        # append new edges
+        graph[0].append(source_to_layer)
+        graph[i + 1].append(layer_to_source)
     # then from layers to chip layers
     for i, layer_targets in enumerate(layer_mapping):
         for target in layer_targets:
-            graph[i + 1].append(Edge(s=i + 1, t=target + target_offset, cap=1, flow=0))
-            graph[target + target_offset].append(
-                Edge(s=target + target_offset, t=i + 1, cap=0, flow=0)
+            layer_to_chip = FlowGraphEdge(
+                s=i + 1, t=target + target_offset, cap=1, flow=0
+            )
+            chip_to_layer = FlowGraphEdge(
+                s=target + target_offset, t=i + 1, cap=0, flow=0
             )
-            graph[i + 1][-1].rev = graph[target + target_offset][-1]
-            graph[target + target_offset][-1].rev = graph[i + 1][-1]
-    # print(graph)
+            layer_to_chip.rev = chip_to_layer
+            chip_to_layer.rev = layer_to_chip
+            graph[i + 1].append(layer_to_chip)
+            graph[target + target_offset].append(chip_to_layer)
     # then from chip layers to sink
-    for i, layer in enumerate(graph[target_offset:-1]):
-        sink = len(graph) - 1
-        source = i + target_offset
-        graph[source].append(Edge(s=source, t=sink, cap=1, flow=0))
-        graph[sink].append(Edge(s=sink, t=source, cap=0, flow=0))
-        graph[source][-1].rev = graph[sink][-1]
+    sink = len(graph) - 1
+    for chip_node in range(target_offset, sink):
+        graph[chip_node].append(FlowGraphEdge(s=chip_node, t=sink, cap=1, flow=0))
+        graph[sink].append(FlowGraphEdge(s=sink, t=chip_node, cap=0, flow=0))
+        graph[chip_node][-1].rev = graph[sink][-1]
         graph[sink][-1].rev = graph[sink][-1]
     return graph
 
 
-def recover_mapping(graph, layer_mapping) -> List[Tuple[int, int]]:
+def recover_mapping(graph: List[List[FlowGraphEdge]], num_layers: int) -> List[int]:
+    """Based on the flow graph retrieve a layer-to-core mapping
+
+    Args:
+        graph List[List[FlowGraphEdge]]): Flow graph representation with flow
+            calculated. Each list entry corresponds to a node and consists of a
+            list holding the outgoing edges from this node.
+        num_layers (int): Number of software layers.
+
+    Returns:
+        Assigned core IDs for each layer in order. Type is List[int].
+    """
     mapping = []
-    for i, layer in enumerate(layer_mapping):
-        for edge in graph[i + 1]:
+    for i in range(1, num_layers + 1):  # `+1` to skip source node
+        for edge in graph[i]:
             if edge.flow == 1:
-                mapping.append((i, edge.t - len(layer_mapping) - 1))
-    if len(mapping) != len(layer_mapping):
+                mapping.append(edge.t - num_layers - 1)
+    if len(mapping) != num_layers:
         raise ValueError(
-            "No valid mapping found. "
-            "For Speck family you can use `utils.validate_memory_mapping_speck()` to get more information."
+            "No valid mapping found. One or more of the DynapcnnLayers could not be mapped to any core."
+            "For Speck family you can verify if it is a memory issue by using `utils.validate_memory_mapping_speck()` to get more information."
         )
     return mapping