[tutorial] include a repetition and update docs

examples/tutorial/basic_shapes.py

@@ -2,9 +2,8 @@
 import numpy
 from numpy import pi
 
-from masque import (
-    layer_t, Pattern, Circle, Arc, Polygon,
-    )
+from masque import layer_t, Pattern, Circle, Arc, Polygon, Ref
+from masque.repetition import Grid
 import masque.file.gdsii
 
 
@@ -37,6 +36,45 @@ def hole(
     return pat
 
 
+def hole_array(
+        radius: float,
+        num_x: int = 5,
+        num_y: int = 3,
+        pitch: float = 2000,
+        layer: layer_t = (1, 0),
+        ) -> Pattern:
+    """
+    Generate an array of circular holes using `Repetition`.
+
+    Args:
+        radius: Circle radius.
+        num_x, num_y: Number of holes in x and y.
+        pitch: Center-to-center spacing.
+        layer: Layer to draw the holes on.
+
+    Returns:
+        Pattern containing a grid of holes.
+    """
+    # First, make a pattern for a single hole
+    hpat = hole(radius, layer)
+
+    # Now, create a pattern that references it multiple times using a Grid
+    pat = Pattern()
+    pat.refs['hole'] = [
+        Ref(
+            offset=(0, 0),
+            repetition=Grid(a_vector=(pitch, 0), a_count=num_x,
+                            b_vector=(0, pitch), b_count=num_y)
+        )]
+
+    # We can also add transformed references (rotation, mirroring, etc.)
+    pat.refs['hole'].append(
+        Ref(offset=(0, -pitch), rotation=pi / 4, mirrored=True)
+    )
+
+    return pat, hpat
+
+
 def triangle(
         radius: float,
         layer: layer_t = (1, 0),
@@ -58,9 +96,7 @@ def triangle(
         ]) * radius
 
     pat = Pattern()
-    pat.shapes[layer].extend([
-        Polygon(offset=(0, 0), vertices=vertices),
-        ])
+    pat.polygon(layer, vertices=vertices)
     return pat
 
 
@@ -109,9 +145,13 @@ def main() -> None:
     lib['smile'] = smile(1000)
     lib['triangle'] = triangle(1000)
 
+    # Use a Grid to make many holes efficiently
+    lib['grid'], lib['hole'] = hole_array(1000)
+
     masque.file.gdsii.writefile(lib, 'basic_shapes.gds', **GDS_OPTS)
 
     lib['triangle'].visualize()
+    lib['grid'].visualize(lib)
 
 
 if __name__ == '__main__':