various fixes and cleanup

mainly involving ports_to_data and data_to_ports

examples/tutorial/devices.py

@@ -8,7 +8,7 @@ from masque import (
     layer_t, Pattern, Ref, Label, Builder, Port, Polygon,
     WrapLibrary, Library,
     )
-from masque.builder import port_utils
+from masque.utils import ports2data
 from masque.file.gdsii import writefile, check_valid_names
 
 import pcgen
@@ -20,20 +20,20 @@ LATTICE_CONSTANT = 512
 RADIUS = LATTICE_CONSTANT / 2 * 0.75
 
 
-def dev2pat(dev: Pattern) -> Pattern:
+def ports_to_data(pat: Pattern) -> Pattern:
     """
     Bake port information into the pattern.
     This places a label at each port location on layer (3, 0) with text content
       'name:ptype angle_deg'
     """
-    return port_utils.dev2pat(dev, layer=(3, 0))
+    return ports2data.ports_to_data(pat, layer=(3, 0))
 
 
-def pat2dev(lib: Mapping[str, Pattern], name: str, pat: Pattern) -> Pattern:
+def data_to_ports(lib: Mapping[str, Pattern], name: str, pat: Pattern) -> Pattern:
     """
-    Scans the Pattern to determine port locations. Same format as `dev2pat`
+    Scans the Pattern to determine port locations. Same port format as `ports_to_data`
     """
-    return port_utils.pat2dev(layers=[(3, 0)], library=lib, pattern=pat, name=name)
+    return ports2data.data_to_ports(layers=[(3, 0)], library=lib, pattern=pat, name=name)
 
 
 def perturbed_l3(
@@ -103,7 +103,7 @@ def perturbed_l3(
         output=Port((extent, 0), rotation=pi, ptype='pcwg'),
         )
 
-    dev2pat(pat)
+    ports_to_data(pat)
     return pat
 
 
@@ -142,8 +142,8 @@ def waveguide(
         left=Port((-extent, 0), rotation=0, ptype='pcwg'),
         right=Port((extent, 0), rotation=pi, ptype='pcwg'),
         )
-    dev2pat(pat)
-    print(pat)
+
+    ports_to_data(pat)
     return pat
 
 
@@ -183,7 +183,7 @@ def bend(
                     extent * numpy.sqrt(3) / 2),
                    rotation=pi * 4 / 3, ptype='pcwg'),
         )
-    dev2pat(pat)
+    ports_to_data(pat)
     return pat
 
 
@@ -222,7 +222,7 @@ def y_splitter(
         'bot': Port((extent / 2, -extent * numpy.sqrt(3) / 2), rotation=pi * 2 / 3, ptype='pcwg'),
         }
 
-    dev2pat(pat)
+    ports_to_data(pat)
     return pat
 
 
@@ -311,7 +311,7 @@ def main(interactive: bool = True) -> None:
     # We can also add text labels for our circuit's ports.
     #   They will appear at the uppermost hierarchy level, while the individual
     # device ports will appear further down, in their respective cells.
-    dev2pat(circ.pattern)
+    ports_to_data(circ.pattern)
 
     # Add the pattern into our library
     lib['my_circuit'] = circ.pattern

examples/tutorial/library.py

@@ -10,7 +10,7 @@ from masque.file.gdsii import writefile, load_libraryfile
 import pcgen
 import basic_shapes
 import devices
-from devices import pat2dev, dev2pat
+from devices import ports_to_data, data_to_ports
 from basic_shapes import GDS_OPTS
 
 
@@ -24,7 +24,7 @@ def main() -> None:
     #
 
     # Scan circuit.gds and prepare to lazy-load its contents
-    gds_lib, _properties = load_libraryfile('circuit.gds', postprocess=pat2dev)
+    gds_lib, _properties = load_libraryfile('circuit.gds', postprocess=data_to_ports)
 
     # Add it into the device library by providing a way to read port info
     #   This maintains the lazy evaluation from above, so no patterns
@@ -59,13 +59,18 @@ def main() -> None:
     # Immediately start building from an instance of the L3 cavity
     circ2 = Builder(library=lib, ports='tri_l3cav')
 
-    print(lib['wg10'].ports)
+    #   First way to get abstracts is `lib.abstract(name)`
     circ2.plug(lib.abstract('wg10'), {'input': 'right'})
 
-    abstracts = lib.abstract_view()     # Alternate way to get abstracts
+    #   Second way to get abstracts is to use an AbstractView
+    abstracts = lib.abstract_view()
     circ2.plug(abstracts['wg10'], {'output': 'left'})
-    circ2.plug(abstracts['tri_wg10'], {'input': 'right'})
-    circ2.plug(abstracts['tri_wg10'], {'output': 'left'})
+
+    # Third way to specify an abstract works by automatically getting
+    # it from the library already within the Builder object:
+    # Just pass the pattern name!
+    circ2.plug('tri_wg10', {'input': 'right'})
+    circ2.plug('tri_wg10', {'output': 'left'})
 
     # Add the circuit to the device library.
     #  It has already been generated, so we can use `set_const` as a shorthand for
@@ -81,15 +86,15 @@ def main() -> None:
     circ3 = Builder.interface(source=circ2)
 
     # ... that lets us continue from where we left off.
-    circ3.plug(abstracts['tri_bend0'], {'input': 'right'})
-    circ3.plug(abstracts['tri_bend0'], {'input': 'left'}, mirrored=(True, False)) # mirror since no tri y-symmetry
-    circ3.plug(abstracts['tri_bend0'], {'input': 'right'})
-    circ3.plug(abstracts['bend0'], {'output': 'left'})
-    circ3.plug(abstracts['bend0'], {'output': 'left'})
-    circ3.plug(abstracts['bend0'], {'output': 'left'})
-    circ3.plug(abstracts['tri_wg10'], {'input': 'right'})
-    circ3.plug(abstracts['tri_wg28'], {'input': 'right'})
-    circ3.plug(abstracts['tri_wg10'], {'input': 'right', 'output': 'left'})
+    circ3.plug('tri_bend0', {'input': 'right'})
+    circ3.plug('tri_bend0', {'input': 'left'}, mirrored=(True, False)) # mirror since no tri y-symmetry
+    circ3.plug('tri_bend0', {'input': 'right'})
+    circ3.plug('bend0', {'output': 'left'})
+    circ3.plug('bend0', {'output': 'left'})
+    circ3.plug('bend0', {'output': 'left'})
+    circ3.plug('tri_wg10', {'input': 'right'})
+    circ3.plug('tri_wg28', {'input': 'right'})
+    circ3.plug('tri_wg10', {'input': 'right', 'output': 'left'})
 
     lib.set_const('loop_segment', circ3.pattern)