From e10a90636c37426a1da026ae4d0db18ae1f10360 Mon Sep 17 00:00:00 2001
From: Felix Bauer <felix.bauer@synsense.ai>
Date: Wed, 3 Apr 2024 14:09:18 +0200
Subject: [PATCH 1/2] dynapcnn.mapping.py: Add clarifying docstrings and
 comments

---
 sinabs/backend/dynapcnn/mapping.py | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/sinabs/backend/dynapcnn/mapping.py b/sinabs/backend/dynapcnn/mapping.py
index 5fefaa0b..ba025f01 100644
--- a/sinabs/backend/dynapcnn/mapping.py
+++ b/sinabs/backend/dynapcnn/mapping.py
@@ -88,6 +88,7 @@ def __repr__(self):
 
 # graph is list of list of edges. Each edge is
 def edmonds(graph, source, sink, verbose: bool = False):
+    """ Use Edmonds-Karp-Algorithm to match software layers to chip layers"""
     graph = deepcopy(graph)
     flow = 0
     while True:
@@ -95,9 +96,13 @@ 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]:
-                if pred[edge.t] is None and edge.t != source and edge.cap > edge.flow:
+            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)
         if pred[sink] is not None:
@@ -123,9 +128,12 @@ 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`
+    """
+    Make a bipartite flow graph (flow network) given all possible chip layers
+    for each DynapcnnLayer layer. The goal is to formulate the mapping from
+    software layer 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`
 
     Parameters
     ----------

From c6e019075b168ef272564d614e718b038ccf4686 Mon Sep 17 00:00:00 2001
From: Felix Bauer <felix.bauer@synsense.ai>
Date: Wed, 3 Apr 2024 14:20:16 +0200
Subject: [PATCH 2/2] Fix black formatting

---
 sinabs/backend/dynapcnn/mapping.py | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/sinabs/backend/dynapcnn/mapping.py b/sinabs/backend/dynapcnn/mapping.py
index ba025f01..36c38ad4 100644
--- a/sinabs/backend/dynapcnn/mapping.py
+++ b/sinabs/backend/dynapcnn/mapping.py
@@ -88,7 +88,7 @@ def __repr__(self):
 
 # graph is list of list of edges. Each edge is
 def edmonds(graph, source, sink, verbose: bool = False):
-    """ Use Edmonds-Karp-Algorithm to match software layers to chip layers"""
+    """Use Edmonds-Karp-Algorithm to match software layers to chip layers"""
     graph = deepcopy(graph)
     flow = 0
     while True:
@@ -98,11 +98,7 @@ def edmonds(graph, source, sink, verbose: bool = False):
         while len(q) != 0:
             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
-                ):
+                if pred[edge.t] is None and edge.t != source and edge.cap > edge.flow:
                     pred[edge.t] = edge
                     q.append(edge.t)
         if pred[sink] is not None: