""" Tutorial: building hierarchical devices with `Pattern`, `Port`, and `Builder`. This file uses photonic-crystal components as the concrete example, so some of the geometry-generation code is domain-specific. The tutorial value is in the Masque patterns around it: creating reusable cells, annotating ports, composing hierarchy with references, and snapping ports together to build a larger circuit. """ from collections.abc import Sequence, Mapping import numpy from numpy import pi from masque import ( layer_t, Pattern, Ref, Builder, Port, Polygon, Library, ) from masque.utils import ports2data from masque.file.gdsii import writefile, check_valid_names import pcgen import basic_shapes from basic_shapes import GDS_OPTS LATTICE_CONSTANT = 512 RADIUS = LATTICE_CONSTANT / 2 * 0.75 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 ports2data.ports_to_data(pat, layer=(3, 0)) def data_to_ports(lib: Mapping[str, Pattern], name: str, pat: Pattern) -> Pattern: """ Scan the Pattern to determine port locations. Same port format as `ports_to_data` """ return ports2data.data_to_ports(layers=[(3, 0)], library=lib, pattern=pat, name=name) def perturbed_l3( lattice_constant: float, hole: str, hole_lib: Mapping[str, Pattern], trench_layer: layer_t = (1, 0), shifts_a: Sequence[float] = (0.15, 0, 0.075), shifts_r: Sequence[float] = (1.0, 1.0, 1.0), xy_size: tuple[int, int] = (10, 10), perturbed_radius: float = 1.1, trench_width: float = 1200, ) -> Pattern: """ Generate a `Pattern` representing a perturbed L3 cavity. Args: lattice_constant: Distance between nearest neighbor holes hole: name of a `Pattern` containing a single hole hole_lib: Library which contains the `Pattern` object for hole. Necessary because we need to know how big it is... trench_layer: Layer for the trenches, default `(1, 0)`. shifts_a: passed to `pcgen.l3_shift`; specifies lattice constant (1 - multiplicative factor) for shifting holes adjacent to the defect (same row). Default `(0.15, 0, 0.075)` for first, second, third holes. shifts_r: passed to `pcgen.l3_shift`; specifies radius for perturbing holes adjacent to the defect (same row). Default 1.0 for all holes. Provided sequence should have same length as `shifts_a`. xy_size: `(x, y)` number of mirror periods in each direction; total size is `2 * n + 1` holes in each direction. Default (10, 10). perturbed_radius: radius of holes perturbed to form an upwards-directed beam (multiplicative factor). Default 1.1. trench_width: Width of the undercut trenches. Default 1200. Returns: `Pattern` object representing the L3 design. """ print('Generating perturbed L3...') # Get hole positions and radii xyr = pcgen.l3_shift_perturbed_defect(mirror_dims=xy_size, perturbed_radius=perturbed_radius, shifts_a=shifts_a, shifts_r=shifts_r) # Build the cavity by instancing the supplied `hole` pattern many times. # Using references keeps the pattern compact even though it contains many holes. pat = Pattern() pat.refs[hole] += [ Ref(scale=r, offset=(lattice_constant * x, lattice_constant * y)) for x, y, r in xyr] # Add rectangular undercut aids based on the referenced hole extents. min_xy, max_xy = pat.get_bounds_nonempty(hole_lib) trench_dx = max_xy[0] - min_xy[0] pat.shapes[trench_layer] += [ Polygon.rect(ymin=max_xy[1], xmin=min_xy[0], lx=trench_dx, ly=trench_width), Polygon.rect(ymax=min_xy[1], xmin=min_xy[0], lx=trench_dx, ly=trench_width), ] # Define the interface in Masque terms: two ports at the left/right extents. extent = lattice_constant * xy_size[0] pat.ports = dict( input=Port((-extent, 0), rotation=0, ptype='pcwg'), output=Port((extent, 0), rotation=pi, ptype='pcwg'), ) ports_to_data(pat) return pat def waveguide( lattice_constant: float, hole: str, length: int, mirror_periods: int, ) -> Pattern: """ Generate a `Pattern` representing a photonic crystal line-defect waveguide. Args: lattice_constant: Distance between nearest neighbor holes hole: name of a `Pattern` containing a single hole length: Distance (number of mirror periods) between the input and output ports. Ports are placed at lattice sites. mirror_periods: Number of hole rows on each side of the line defect Returns: `Pattern` object representing the waveguide. """ # Generate the normalized lattice locations for the line defect. xy = pcgen.waveguide(length=length, num_mirror=mirror_periods) # Build the pattern by placing repeated references to the same hole cell. pat = Pattern() pat.refs[hole] += [ Ref(offset=(lattice_constant * x, lattice_constant * y)) for x, y in xy] # Publish the device interface as two ports at the outer edges. extent = lattice_constant * length / 2 pat.ports = dict( left=Port((-extent, 0), rotation=0, ptype='pcwg'), right=Port((extent, 0), rotation=pi, ptype='pcwg'), ) ports_to_data(pat) return pat def bend( lattice_constant: float, hole: str, mirror_periods: int, ) -> Pattern: """ Generate a `Pattern` representing a 60-degree counterclockwise bend in a photonic crystal line-defect waveguide. Args: lattice_constant: Distance between nearest neighbor holes hole: name of a `Pattern` containing a single hole mirror_periods: Minimum number of mirror periods on each side of the line defect. Returns: `Pattern` object representing the waveguide bend. Ports are named 'left' (input) and 'right' (output). """ # Generate the normalized lattice locations for the bend. xy = pcgen.wgbend(num_mirror=mirror_periods) # Build the pattern by instancing the shared hole cell. pat = Pattern() pat.refs[hole] += [ Ref(offset=(lattice_constant * x, lattice_constant * y)) for x, y in xy] # Publish the bend interface as two ports. extent = lattice_constant * mirror_periods pat.ports = dict( left=Port((-extent, 0), rotation=0, ptype='pcwg'), right=Port((extent / 2, extent * numpy.sqrt(3) / 2), rotation=pi * 4 / 3, ptype='pcwg'), ) ports_to_data(pat) return pat def y_splitter( lattice_constant: float, hole: str, mirror_periods: int, ) -> Pattern: """ Generate a `Pattern` representing a photonic crystal line-defect waveguide y-splitter. Args: lattice_constant: Distance between nearest neighbor holes hole: name of a `Pattern` containing a single hole mirror_periods: Minimum number of mirror periods on each side of the line defect. Returns: `Pattern` object representing the y-splitter. Ports are named 'in', 'top', and 'bottom'. """ # Generate the normalized lattice locations for the splitter. xy = pcgen.y_splitter(num_mirror=mirror_periods) # Build the pattern by instancing the shared hole cell. pat = Pattern() pat.refs[hole] += [ Ref(offset=(lattice_constant * x, lattice_constant * y)) for x, y in xy] # Publish the splitter interface as one input and two outputs. extent = lattice_constant * mirror_periods pat.ports = { 'in': Port((-extent, 0), rotation=0, ptype='pcwg'), 'top': Port((extent / 2, extent * numpy.sqrt(3) / 2), rotation=pi * 4 / 3, ptype='pcwg'), 'bot': Port((extent / 2, -extent * numpy.sqrt(3) / 2), rotation=pi * 2 / 3, ptype='pcwg'), } ports_to_data(pat) return pat def main(interactive: bool = True) -> None: # First make a couple of reusable primitive cells. shape_lib = { 'smile': basic_shapes.smile(RADIUS), 'hole': basic_shapes.hole(RADIUS), } # Then build a small library of higher-level devices from those primitives. a = LATTICE_CONSTANT devices = {} devices['wg05'] = waveguide(lattice_constant=a, hole='hole', length=5, mirror_periods=5) devices['wg10'] = waveguide(lattice_constant=a, hole='hole', length=10, mirror_periods=5) devices['wg28'] = waveguide(lattice_constant=a, hole='hole', length=28, mirror_periods=5) devices['wg90'] = waveguide(lattice_constant=a, hole='hole', length=90, mirror_periods=5) devices['bend0'] = bend(lattice_constant=a, hole='hole', mirror_periods=5) devices['ysplit'] = y_splitter(lattice_constant=a, hole='hole', mirror_periods=5) devices['l3cav'] = perturbed_l3(lattice_constant=a, hole='smile', hole_lib=shape_lib, xy_size=(4, 10)) # uses smile :) # Turn the device mapping into a `Library`. # That gives us convenience helpers for hierarchy inspection and abstract views. lib = Library(devices) # # Build a circuit # # Create a `Builder`, and register the resulting top cell as "my_circuit". circ = Builder(library=lib, name='my_circuit') # Start by placing a waveguide and renaming its ports to match the circuit-level # names we want to use while assembling the design. circ.place('wg10', offset=(0, 0), port_map={'left': 'in', 'right': 'signal'}) # Extend the signal path by attaching another waveguide. # Because `wg10` only has one unattached port left after the plug, Masque can # infer that it should keep the name `signal`. circ.plug('wg10', {'signal': 'left'}) # We could have done the following instead: # circ_pat = Pattern() # lib['my_circuit'] = circ_pat # circ_pat.place(lib.abstract('wg10'), ...) # circ_pat.plug(lib.abstract('wg10'), ...) # but `Builder` removes some repeated `lib.abstract(...)` boilerplate and keeps # the assembly code focused on port-level intent. # Attach a y-splitter to the signal path. # Since the y-splitter has 3 ports total, we can't auto-inherit the # port name, so we have to specify what we want to name the unattached # ports. We can call them "signal1" and "signal2". circ.plug('ysplit', {'signal': 'in'}, {'top': 'signal1', 'bot': 'signal2'}) # Add a waveguide to both signal ports, inheriting their names. circ.plug('wg05', {'signal1': 'left'}) circ.plug('wg05', {'signal2': 'left'}) # Add a bend to both branches. # Our bend primitive is defined with a specific orientation, so choosing which # port to plug determines whether the path turns clockwise or counterclockwise. # We could also mirror one instance instead of using opposite ports. circ.plug('bend0', {'signal1': 'right'}) circ.plug('bend0', {'signal2': 'left'}) # We add some waveguides and a cavity to "signal1". circ.plug('wg10', {'signal1': 'left'}) circ.plug('l3cav', {'signal1': 'input'}) circ.plug('wg10', {'signal1': 'left'}) # `signal2` gets a single waveguide of equivalent overall length. circ.plug('wg28', {'signal2': 'left'}) # Now bend both branches back towards each other. circ.plug('bend0', {'signal1': 'right'}) circ.plug('bend0', {'signal2': 'left'}) circ.plug('wg05', {'signal1': 'left'}) circ.plug('wg05', {'signal2': 'left'}) # To join the branches, attach a second y-junction. # This succeeds only if both chosen ports agree on the same translation and # rotation for the inserted device; otherwise Masque raises an exception. circ.plug('ysplit', {'signal1': 'bot', 'signal2': 'top'}, {'in': 'signal_out'}) # Finally, add some more waveguide to "signal_out". circ.plug('wg10', {'signal_out': 'left'}) # Bake the top-level port metadata into labels so it survives GDS export. # These labels appear on the circuit cell; individual child devices keep their # own port labels in their own cells. ports_to_data(circ.pattern) # Check if we forgot to include any patterns... ooops! if dangling := lib.dangling_refs(): print('Warning: The following patterns are referenced, but not present in the' f' library! {dangling}') print('We\'ll solve this by merging in shape_lib, which contains those shapes...') lib.add(shape_lib) assert not lib.dangling_refs() # We can visualize the design directly, though opening the written GDS is often easier. if interactive: print('Visualizing... this step may be slow') circ.pattern.visualize(lib) # Write out only the subtree reachable from our top cell. subtree = lib.subtree('my_circuit') # don't include wg90, which we don't use check_valid_names(subtree.keys()) writefile(subtree, 'circuit.gds', **GDS_OPTS) if __name__ == '__main__': main()