[wip] Rework load_libraryfile and LazyLibrary using overlays

examples/tutorial/library.py

@@ -1,5 +1,5 @@
 """
-Tutorial: using `LazyLibrary` and `Pather.interface()`.
+Tutorial: using a source-backed lazy GDS library and `Pather.interface()`.
 
 This example assumes you have already read `devices.py` and generated the
 `circuit.gds` file it writes. The goal here is not the photonic-crystal geometry
@@ -10,32 +10,28 @@ from typing import Any
 from pprint import pformat
 
 
-from masque import Pather, LazyLibrary
-from masque.file.gdsii import writefile, load_libraryfile
+from masque import Pather
+from masque.file.gdsii import writefile
+from masque.file.gdsii_lazy import OverlayLibrary, readfile
 
 import basic_shapes
 import devices
-from devices import data_to_ports
 from basic_shapes import GDS_OPTS
 
 
 def main() -> None:
-    # A `LazyLibrary` delays work until a pattern is actually needed.
-    # That applies both to GDS cells we load from disk and to python callables
-    # that generate patterns on demand.
-    lib = LazyLibrary()
+    # `OverlayLibrary` lets us mix source-backed GDS cells with python-generated
+    # patterns behind the same library interface.
+    lib = OverlayLibrary()
 
     #
     # Load some devices from a GDS file
     #
 
-    # Scan circuit.gds and prepare to lazy-load its contents
-    gds_lib, _properties = load_libraryfile('circuit.gds', postprocess=data_to_ports)
-
-    # Add those cells into our lazy library.
-    # Nothing is read yet; we are only registering how to fetch and postprocess
-    # each pattern when it is first requested.
-    lib.add(gds_lib)
+    # Scan circuit.gds and prepare to lazy-load its contents. Port labels are
+    # imported on first materialization, but the raw source remains untouched.
+    gds_lib, _properties = readfile('circuit.gds')
+    lib.add_source(gds_lib.with_ports_from_data(layers=[(3, 0)], max_depth=1))
 
     print('Patterns loaded from GDS into library:\n' + pformat(list(lib.keys())))
 
@@ -43,20 +39,18 @@ def main() -> None:
     # Add some new devices to the library, this time from python code rather than GDS
     #
 
-    lib['triangle'] = lambda: basic_shapes.triangle(devices.RADIUS)
+    lib['triangle'] = basic_shapes.triangle(devices.RADIUS)
     opts: dict[str, Any] = dict(
         lattice_constant = devices.LATTICE_CONSTANT,
         hole = 'triangle',
         )
 
-    # Triangle-based variants. These lambdas are only recipes for building the
-    # patterns; they do not execute until someone asks for the cell.
-    lib['tri_wg10'] = lambda: devices.waveguide(length=10, mirror_periods=5, **opts)
-    lib['tri_wg05'] = lambda: devices.waveguide(length=5, mirror_periods=5, **opts)
-    lib['tri_wg28'] = lambda: devices.waveguide(length=28, mirror_periods=5, **opts)
-    lib['tri_bend0'] = lambda: devices.bend(mirror_periods=5, **opts)
-    lib['tri_ysplit'] = lambda: devices.y_splitter(mirror_periods=5, **opts)
-    lib['tri_l3cav'] = lambda: devices.perturbed_l3(xy_size=(4, 10), **opts, hole_lib=lib)
+    lib['tri_wg10'] = devices.waveguide(length=10, mirror_periods=5, **opts)
+    lib['tri_wg05'] = devices.waveguide(length=5, mirror_periods=5, **opts)
+    lib['tri_wg28'] = devices.waveguide(length=28, mirror_periods=5, **opts)
+    lib['tri_bend0'] = devices.bend(mirror_periods=5, **opts)
+    lib['tri_ysplit'] = devices.y_splitter(mirror_periods=5, **opts)
+    lib['tri_l3cav'] = devices.perturbed_l3(xy_size=(4, 10), **opts, hole_lib=lib)
 
     #
     # Build a mixed waveguide with an L3 cavity in the middle