snapshot 2022-03-30 23:17:32.485991

snarl/interfaces/masque.py

@@ -1,3 +1,6 @@
+"""
+Functionality for extracting geometry and label info from `masque` patterns.
+"""
 from typing import Sequence, Dict, List, Any, Tuple, Optional, Mapping
 from collections import defaultdict
 
@@ -11,13 +14,29 @@ from ..types import layer_t
 from ..utils import connectivity2layers
 
 
-def read_topcell(
-        topcell: Pattern,
+def read_cell(
+        cell: Pattern,
         connectivity: Sequence[Tuple[layer_t, Optional[layer_t], layer_t]],
         label_mapping: Optional[Mapping[layer_t, layer_t]] = None,
         ) -> Tuple[
                 defaultdict[layer_t, List[NDArray[numpy.float64]]],
                 defaultdict[layer_t, List[Tuple[float, float, str]]]]:
+    """
+    Extract `polys` and `labels` from a `masque.Pattern`.
+
+    This function extracts the data needed by `snarl.trace_connectivity`.
+
+    Args:
+        cell: A `masque` `Pattern` object. Usually your topcell.
+        connectivity: A sequence of 3-tuples specifying the layer connectivity.
+            Same as what is provided to `snarl.trace_connectivity`.
+        label_mapping: A mapping of `{label_layer: metal_layer}`. This allows labels
+            to refer to nets on metal layers without the labels themselves being on
+            that layer.
+
+    Returns:
+        `polys` and `labels` data structures, to be passed to `snarl.trace_connectivity`.
+    """
 
     metal_layers, via_layers = connectivity2layers(connectivity)
     poly_layers = metal_layers | via_layers
@@ -26,19 +45,19 @@ def read_topcell(
         label_mapping = {layer: layer for layer in metal_layers}
     label_layers = {label_layer for label_layer in label_mapping.keys()}
 
-    topcell = topcell.deepcopy().subset(
+    cell = cell.deepcopy().subset(
         shapes_func=lambda ss: ss.layer in poly_layers,
         labels_func=lambda ll: ll.layer in label_layers,
         subpatterns_func=lambda ss: True,
         )
-    topcell = topcell.flatten()
+    cell = cell.flatten()
 
-    polys = load_polys(topcell, list(poly_layers))
+    polys = load_polys(cell, list(poly_layers))
 
     metal_labels = defaultdict(list)
     for label_layer, metal_layer in label_mapping.items():
         labels = []
-        for ll in topcell.labels:
+        for ll in cell.labels:
             if ll.layer != label_layer:
                 continue
 
@@ -57,11 +76,22 @@ def read_topcell(
 
 
 def load_polys(
-        topcell: Pattern,
+        cell: Pattern,
         layers: Sequence[layer_t],
         ) -> defaultdict[layer_t, List[NDArray[numpy.float64]]]:
+    """
+    Given a *flat* `masque.Pattern`, extract the polygon info into the format used by `snarl`.
+
+    Args:
+        cell: The `Pattern` object to extract from.
+        layers: The layers to extract.
+
+    Returns:
+        `{layer0: [poly0, [(x0, y0), (x1, y1), ...], poly2, ...]}`
+        `polys` structure usable by `snarl.trace_connectivity`.
+    """
     polys = defaultdict(list)
-    for ss in topcell.shapes:
+    for ss in cell.shapes:
         if ss.layer not in layers:
             continue