GDSII Tool Kit (gdstk)

Common errors

• TypeError: 'builtin_function_or_method' object is not subscriptable

  cause Attempting to access elements of a GDSII/OASIS library (e.g., cells) using square brackets directly on the `Library.cells` attribute, which is a list, not a dictionary. `lib.cells` returns a list of Cell objects. [5]
  fix To access cells by name, convert `lib.cells` to a dictionary or iterate through the list. Example: `cells_by_name = {c.name: c for c in lib.cells}; my_cell = cells_by_name['CELL_NAME']` or `for cell in lib.cells: if cell.name == 'CELL_NAME': my_cell = cell; break`.

• gdstk.gdstk.GdsError: Invalid GDSII file or corrupted stream.

  cause The GDSII file being read is either malformed, corrupted, or not a valid GDSII format, preventing gdstk from parsing it correctly.
  fix Ensure the GDSII file is valid and not corrupted. Try opening it with a different GDSII viewer (e.g., KLayout) to confirm its integrity. If generated by another tool, check that tool's output settings.

• ValueError: Layer or datatype must be a non-negative integer.

  cause Layer or datatype arguments to geometric functions (e.g., `gdstk.rectangle`, `gdstk.Polygon`) were provided with `None` or a non-integer value.
  fix Always provide non-negative integer values for `layer` and `datatype` parameters when creating GDSII elements. For example, `gdstk.rectangle((0,0), (1,1), layer=0, datatype=0)`.

Warnings

• gotcha Older GDSII formats have a hard limit of 199 vertices per polygon. While gdstk supports modern GDSII which often ignores this, generated files for older systems might fail to open or render incorrectly if this limit is exceeded. [6]
  Fix: When writing GDSII files, set the `max_points` argument in `lib.write_gds(..., max_points=199)` to ensure polygons are fractured if they exceed this limit, ensuring compatibility with older GDSII readers. Alternatively, verify target tool chain supports modern GDSII.
• gotcha GDSII files only support 'weakly simple' polygons (segments can intersect but not cross). Complex shapes with holes or self-intersecting boundaries are not directly supported as GDSII paths and might be stored as polygonal objects, losing path information. [6]
  Fix: Be aware that complex paths might be converted to polygons upon saving. Use `gdstk.boolean` and `gdstk.offset` operations carefully to manage complex geometries and ensure they conform to GDSII's weakly simple polygon definition.
• gotcha Performing boolean operations (`gdstk.boolean`) inside a Python loop for many individual polygons can be significantly slower than expected compared to batch processing or native CAD tools. This is a common performance bottleneck. [11]
  Fix: Where possible, collect all polygons into lists and perform boolean operations on entire lists of polygons at once. This allows `gdstk` to optimize the underlying C++ computations. For example, `gdstk.boolean(list_of_polygons_1, list_of_polygons_2, 'or')`.
• breaking Some users have reported issues with OASIS files losing paths or containing missing shapes after being read and then written back by gdstk, potentially leading to DRC errors in production flows. [12]
  Fix: Verify the integrity of OASIS files after read/write cycles, especially with complex or high-volume designs, by comparing with original files or performing design rule checks. Monitor GitHub issues for updates and consider upgrading to versions with specific fixes for OASIS file handling.

Install

• pip install gdstk Install with pip

Imports

• gdstk

  import gdstk

  The entire library is typically imported as 'gdstk'.
• gdstk.Cell

  cell = gdstk.Cell('my_cell')

  Commonly used classes like Cell, Library, and Polygon are accessed directly as attributes of the 'gdstk' module.

Quickstart

This quickstart creates a simple GDSII file named 'first.gds' containing a library with a single cell named 'FIRST'. This cell contains a rectangle on layer 1 and a triangle (polygon) on layer 2. It demonstrates the basic steps of creating a library, adding a cell, adding geometric shapes, and writing the output to a GDSII file. [6, 9]

import gdstk

# Create a new library
lib = gdstk.Library()

# Create a new cell and add it to the library
cell = lib.new_cell('FIRST')

# Create a rectangle and add it to the cell
rectangle = gdstk.rectangle((0, 0), (2, 2), layer=1, datatype=0)
cell.add(rectangle)

# Create a polygon from vertices and add it to the cell
polygon_points = [(3, 0), (5, 2), (5, 0)]
polygon = gdstk.Polygon(polygon_points, layer=2)
cell.add(polygon)

# Save the library to a GDSII file
lib.write_gds('first.gds')

print("Generated first.gds with a rectangle and a polygon.")