Shape Primitives

Every piece of geometry in a laylight cell is a shape: a primitive with arguments, defined inside a layer block and placed once.

cell Demo {
    layer si {
        shape rect with width = 10um, height = 500nm as core   # named arguments
        shape rect with 10um, 500nm as copy                     # the same, positional
        place core.left_center at self.origin
        place copy.bottom_left at core.top_left offset (0, 1um)
    }
}

The primitive set is the union of the geometric primitives of gdsfactory, gdstk, Luceda IPKISS and Nazca Design. Where those tools offer several functions for closely related shapes (a rectangle, a rounded rectangle, a rectangular frame), laylight has one primitive with optional parameters. The reference at the end maps every function of the four tools to its laylight form.

The examples on this page are the bodies of a layer block. Each one is compiled in your browser; the drawing next to it is the result, and + marks the shape's local origin.

Conventions

Arguments. Arguments can be positional, in the order of the signatures below, or named (key = value). Parameters marked ? are optional. Lengths need a unit (500nm, 2um), angles too (90deg); the literal 0 works as any zero. String options such as ends and profile are checked while you type when you write them as literals.

Local coordinates and anchors. Each primitive is defined in its own coordinate system, described per primitive below. Every shape has the anchors origin, center, left_center, right_center, top_center, bottom_center, bottom_left, bottom_right, top_left and top_right (from its bounding box, all pointing along +x), and the sizes width and height. Waveguide primitives also have start and end: frames whose direction is the tangent of the waveguide there, pointing downstream, so place b.start at a.end chains two pieces.

Curves. Curved outlines are written as polygons. segments sets the number of straight segments of each curved part: the whole circle or arc, each rounded corner, each half circle of a racetrack, each rounded path corner, the whole Euler, S-bend or Bézier curve, or each edge of a curved taper. Without it, the segment count follows from a chord error of at most 1 DBU (1 nm by default), with at most 45° per segment on circles; free-form curves are sampled more densely where they bend more.

Shared variants. Closed shapes take corner_radius, which rounds the corners, and line_width, which draws the boundary as a line of that width centered on it, as one polygon. Circles and ellipses take angle and start_angle for sectors (positive angles are counter-clockwise).

Closed shapes

rect

rect(width, height, corner_radius?, line_width?, segments?)

A rectangle centered at the origin. It stays a GDS box under right-angle placements.

shape rect with 12um, 6um as box
place box at (0, 0)

shape rect with 12um, 6um, corner_radius = 2um as rounded
shape rect with 12um, 6um, corner_radius = 3um as stadium
shape rect with 12um, 6um, corner_radius = 1um, line_width = 1um as frame
place rounded at (0, 0)
place stadium at (0, -9um)
place frame at (0, -18um)

To give a rectangle by two corners (x1, y1) and (x2, y2), place its corner anchor: shape rect with x2 - x1, y2 - y1 as r and place r.bottom_left at (x1, y1).

polygon

polygon(points, corner_radius?, line_width?, segments?)

A polygon through points (at least 3), in local coordinates.

shape polygon with [(0, 0), (14um, 0), (4um, 10um)] as plain
shape polygon with [(0, 0), (14um, 0), (4um, 10um)], corner_radius = 2um as rounded
shape polygon with [(0, 0), (14um, 0), (4um, 10um)], line_width = 800nm as outline
place plain at (0, 0)
place rounded at (18um, 0)
place outline at (36um, 0)

Points can be computed in a loop, which covers parametric shapes that have no primitive of their own:

define star: [point] = []
for i in 0..10 {
    define r = 6um - 3um * (i % 2)
    star.append((r * cos(i * 36deg + 90deg), r * sin(i * 36deg + 90deg)))
}
shape polygon with star as s
place s at (0, 0)

regular_polygon

regular_polygon(sides, radius?, side_length?, rotation?, corner_radius?, line_width?, segments?)

A regular polygon centered at the origin. Give either the circumradius radius or the side_length, not both. Unrotated, the bottom edge is horizontal: vertex k sits at −90° + 180°/n + k·360°/n. So an unrotated square is axis-aligned and a triangle points up.

shape regular_polygon with 3, radius = 5um as triangle
shape regular_polygon with 6, side_length = 5um as hexagon
shape regular_polygon with 8, radius = 5um, rotation = 22.5deg, line_width = 1um as octagon
shape regular_polygon with 5, radius = 5um, corner_radius = 1um as pentagon
place triangle at (0, 0)
place hexagon at (12um, 0)
place octagon at (24um, 0)
place pentagon at (36um, 0)

circle

circle(radius, segments?, angle?, start_angle?)

A disk centered at the origin, or with angle a sector (a pie slice, including the center) that starts at start_angle and sweeps angle counter-clockwise; negative angles sweep clockwise.

shape circle with 5um as disk
shape circle with 5um, angle = 270deg, start_angle = 45deg as pie
shape circle with 5um, angle = 60deg as slice
place disk at (0, 0)
place pie at (13um, 0)
place slice at (22um, -3um)

ellipse

ellipse(rx, ry, segments?, angle?, start_angle?, line_width?)

An ellipse centered at the origin with semi-axes rx along x and ry along y. Sector angles are polar angles, as in gdstk: angle = 90deg covers exactly the first quadrant.

shape ellipse with 8um, 4um as oval
shape ellipse with 8um, 4um, angle = 90deg as quadrant
shape ellipse with 8um, 4um, line_width = 800nm as outline
shape ellipse with 8um, 4um, angle = 180deg, line_width = 800nm as arch
place oval at (0, 0)
place quadrant at (12um, -2um)
place outline at (0, -11um)
place arch at (20um, -11um)

ring

ring(radius, width, segments?, angle?, start_angle?)

An annulus centered at the origin. radius is the centerline radius, as in gdsfactory: the ring spans radius ± width/2. A full ring is one polygon with a zero-width cut at start_angle; with angle it is an annular sector.

shape ring with 5um, 1um as full
shape ring with 5um, 2um, angle = 120deg, start_angle = 30deg as segment
place full at (0, 0)
place segment at (13um, -3um)

racetrack

racetrack(radius, length, width, segments?)

A closed waveguide loop centered at the origin: two half circles of centerline radius joined by straight sections of length along x, drawn with width. The zero-width cut is at the middle of the bottom straight. length = 0 gives a ring.

shape racetrack with 5um, 10um, 1um as track
place track at (0, 0)

A filled racetrack (a stadium) is a rect whose corner_radius is half its height.

cross

cross(length, arm_width)

A plus sign centered at the origin: two arms of arm_width, each length long from tip to tip, as one 12-vertex polygon.

shape cross with 10um, 3um as plus
place plus at (0, 0)

trapezoid

trapezoid(width, height, top_width, offset?)

A trapezoid height tall, centered on y = 0. The bottom edge is width long and centered on x = 0; the top edge is top_width long and centered on x = offset. A top_width of 0 gives a triangle; a top_width equal to width with an offset gives a parallelogram.

shape trapezoid with 10um, 6um, 4um as trapezoid
shape trapezoid with 10um, 6um, 0 as triangle
shape trapezoid with 10um, 6um, 10um, offset = 3um as parallelogram
shape trapezoid with 10um, 6um, 0, offset = -5um as right_triangle
place trapezoid at (0, 0)
place triangle at (13um, 0)
place parallelogram at (27um, 0)
place right_triangle at (42um, 0)

Shapes described by base angles convert directly. Nazca's trapezoid(length, height, angle1, angle2) is trapezoid with length, height, length - height / tan(angle1) - height / tan(angle2), offset = (height / tan(angle1) - height / tan(angle2)) / 2, and a parallelogram with base angle a has offset = height / tan(a).

Waveguides and paths

All of these have the start and end anchors.

path

path(points, width, ends?, bend_radius?, segments?)

A polyline of width through points. The start and end anchors are at the first and last points, facing along the first and last segments.

shape path with [(0, 0), (8um, 0), (8um, 6um)], 1um as flush
shape path with [(0, 0), (8um, 0), (8um, 6um)], 1um, ends = "square" as square
shape path with [(0, 0), (8um, 0), (8um, 6um)], 1um, ends = "round" as round
place flush at (0, 0)
place square at (12um, 0)
place round at (24um, 0)

shape path with [(0, 0), (10um, 0), (10um, 10um), (20um, 10um)], 1um, bend_radius = 4um as route
place route at (0, 0)

Joins are mitered, as in GDS. L- and C-shaped outlines (gdsfactory's L and C) are flush paths through the arm centerlines.

arc

arc(radius, width, angle, segments?)

A circular bend that starts at the origin heading +x, with its center of curvature at (0, radius) for positive angles: positive angles turn left, negative angles turn right. end lies at (radius · sin angle, radius · (1 − cos angle)).

shape arc with 8um, 1um, 90deg as left
shape arc with 8um, 1um, -45deg as right
place left.start at (0, 0)
place right.start at (12um, 0)

euler

euler(radius?, width, angle, p?, segments?, min_radius?)

An Euler bend: from the origin heading +x, the curvature grows linearly with arc length (a clothoid), stays constant through a circular section, and falls back to zero. The ends therefore join straight waveguides without a curvature jump. p is the fraction of the turn spent in the two clothoids; p = 1 is a pure Euler bend, p = 0 the circular arc.

Give the size in one of two ways:

• radius: the effective radius. The bend ends exactly where an arc of that radius would, so the two are drop-in replacements. This is gdsfactory's bend_euler default (with_arc_floorplan=True).
• min_radius: the smallest radius of curvature, reached in the circular section. This is IPKISS's default and gdsfactory's with_arc_floorplan=False. For a 90° bend with p = 1, the effective radius is 1.8701 times the minimum radius.

shape arc with 10um, 800nm, 90deg as circular
shape euler with 10um, 800nm, 90deg as half
shape euler with 10um, 800nm, 90deg, p = 1 as full
place circular.start at (0, 0)
place half.start at (0, 0)
place full.start at (0, 0)

The three bends above share their end points; the Euler bends swing further into the corner.

sbend

sbend(length, offset, width, profile?, segments?)

An S-bend from the origin heading +x to (length, offset), level at both ends. Positive offsets go to the left. With t = x / length and H = offset, the profiles are:

The radius of curvature must stay above half the width; a bend that is too short for its offset is an error.

shape sbend with 20um, 6um, 800nm as bezier
shape sbend with 20um, 6um, 800nm, profile = "sine" as sine
shape sbend with 20um, 6um, 800nm, profile = "cosine" as cosine
shape sbend with 20um, 6um, 800nm, profile = "circular" as circular
place bezier.start at (0, 0)
place sine.start at (0, -4um)
place cosine.start at (0, -8um)
place circular.start at (0, -12um)

bezier

bezier(points, width, segments?)

A waveguide of width along the Bézier curve with control points points, of any degree (2 points is a straight line, 3 a quadratic, 4 a cubic curve). The curve passes through the first and last points; start and end face along the first and last distinct control-point directions.

shape bezier with [(0, 0), (12um, 0), (0, 12um), (12um, 12um)], 1um as cubic
shape bezier with [(0, 0), (10um, 10um), (20um, 0)], 1um as quadratic
place cubic.start at (0, 0)
place quadratic.start at (18um, 0)

taper

taper(length, width1, width2, profile?, segments?)

A width transition from width1 at x = 0 to width2 at x = length, symmetric about the x axis. start is at the origin and end at (length, 0), both facing +x.

shape taper with 16um, 1um, 6um as linear
shape taper with 16um, 1um, 6um, profile = "parabolic" as parabolic
shape taper with 16um, 1um, 6um, profile = "exponential" as exponential
place linear.start at (0, 0)
place parabolic.start at (0, -8um)
place exponential.start at (0, -16um)

gdsfactory's taper_parabolic uses another law, w1 + (w2 − w1) · t^0.5 (its exp parameter); write that as a polygon from a loop if you need it exactly.

Text

text

text(text, size)

Polygon text in a built-in 5×7 pixel font: printable ASCII and \n for new lines. size is the height of a capital letter (7 pixels). Characters advance by 6 pixels, lines by 11, and descenders reach 2 pixels below the baseline. The origin is at the start of the first line's baseline. Each run of pixels is written as a GDS box.

shape text with "laylight\nDSL 0.1", 3500nm as label
place label at (0, 0)

Align text with its anchors, for example place label.top_center at device.bottom_center offset (0, -2um). Text that should not be fabricated belongs in a marker, which is written as a GDS TEXT on the marker layer.

Recipes

Some shapes of the other tools are compositions rather than primitives:

• Spiral. Compute the centerline in a loop and draw it with path. An Archimedean spiral (gdsfactory's spiral_archimedean):

define turns: [point] = []
for i in 0..200 {
    define a = i * 9deg
    define r = 2um + 1500nm * i * 9 / 360
    turns.append((r * cos(a), r * sin(a)))
}
shape path with turns, 500nm as spiral
place spiral.start at (0, 0)

• Parametric curves (gdstk's parametric, Curve): the same pattern, feeding the points to polygon, path or bezier.
• L, C and die frames: flush paths, or rect with line_width.
• Rectangle from two corners: size the rect from the corners and place its bottom_left.
• Boolean operations and offsets (gdstk's boolean and offset, KLayout regions) are derived shapes; see Boolean and Morphological Operations.

Reference: equivalents in other tools

One table per tool maps its shape functions to the laylight primitive and the arguments that give the same geometry. Versions: gdsfactory 9, gdstk 0.9, Luceda IPKISS 3 (import ipkiss3.all as i3) and Nazca Design 0.6 (nazca.geometries as geom, interconnects as ic). width in the laylight column is the waveguide width, which the other tools often take from a cross-section. A dash means laylight has no counterpart yet.

gdsfactory

gdstk

gdstk angles are radians; laylight angles carry a unit, so write a * 1rad or convert to degrees.

Luceda IPKISS

Nazca Design

Conventions that differ

Watch these when you port a layout. They are the places where the same name means different geometry.

• Angles. gdstk takes radians everywhere; laylight, gdsfactory, IPKISS and Nazca use degrees.
• Ring radius. laylight ring and gdsfactory ring use the centerline radius. Nazca's ring(radius, width) takes the outer radius and grows inward, so it equals laylight ring with radius - width / 2, width. IPKISS CirclePath is centered on its radius, like laylight.
• Racetrack radius. gdstk's racetrack(radius, inner_radius) takes the outer radius: racetrack with (radius + inner_radius) / 2, straight_length, radius - inner_radius.
• Regular polygon orientation. laylight and gdstk put a flat edge at the bottom. gdsfactory and IPKISS put a flat edge at the top, which differs for odd numbers of sides: add rotation = 180deg.
• Parabolic taper. laylight, IPKISS and Nazca change the square of the width linearly. gdsfactory's taper_parabolic changes the width with the square root of the length instead.
• Euler bend size. gdsfactory's bend_euler defaults to the effective radius (laylight radius). IPKISS's EulerRoundingAlgorithm defaults to the minimum radius (laylight min_radius). Nazca's euler is a half bend from straight to curved; euler_arc_euler is the symmetric one.
• S-bend. gdsfactory's bend_s is laylight's default "bezier" profile. Nazca's sinebend is the "sine" profile. Nazca's sbend(radius, offset) uses two arcs of a given radius with a straight section between them. The "circular" profile instead picks the radius that fills length without a straight section.
• Ellipse angles. laylight and gdstk take polar angles; IPKISS's EllipseArcPath takes parametric ones.
• Text size. laylight's size and gdsfactory's text size are the height of a capital letter. gdstk's size is the full font height, with capitals about 0.75 of it. Nazca's height is scaled by the font's line height. gdsfactory's text_rectangular size is one pixel.
• Rectangle origin. laylight shapes are centered (rect) or start at the origin (waveguides). gdsfactory's rectangle defaults to its lower-left corner at the origin, and Nazca's rectangles take a keypad position (1 = lower left, 5 = center).
• Point density. segments corresponds to gdsfactory's npoints / angle_resolution, gdstk's tolerance, IPKISS's angle_step (1° by default) and Nazca's N (20 by default).