gdstk

GDSTK (GDSII Tool Kit) is a C++ library designed for the creation and manipulation of GDSII and OASIS files. It is also available as a Python module and serves as the successor to gdspy.

Key Features

• Boolean operations on polygons: Supports AND, OR, NOT, and XOR operations using a clipping algorithm.
• Polygon offset: Allows for inward and outward rescaling of polygons.
• Efficient point-in-polygon solutions: Optimized for large array sets.

Typical Applications

• Electronic chip design
• Planar lightwave circuit design
• Mechanical engineering

Gdstk (GDSII Tool Kit) is a library designed for the creation and manipulation of GDSII and OASIS files. It is available as both a C++ library and a Python module (intended as a successor to gdspy).

Key features include:

• Boolean operations on polygons: Supports AND, OR, NOT, and XOR operations using a clipping algorithm.
• Polygon offset: Allows for inward and outward rescaling of polygons.
• Point-in-polygon testing: Provides efficient solutions for large sets of points.

Common use cases include electronic chip design, planar lightwave circuit design, and mechanical engineering.

GDSTK provides several classes and functions for creating and manipulating geometric objects.

Geometric Classes:

• gdstk.Polygon: Represents a polygon.
• gdstk.Curve: Represents a geometric curve.
• gdstk.FlexPath: Represents a path with variable width.
• gdstk.RobustPath: Represents a path with robust geometry.
• gdstk.Repetition: Used for creating repetitive geometric patterns.

Geometric Functions:

• Primitive creation: gdstk.rectangle, gdstk.cross, gdstk.regular_polygon, gdstk.ellipse, gdstk.racetrack, gdstk.text.
• Advanced manipulation: gdstk.contour, gdstk.offset, gdstk.boolean, gdstk.slice, gdstk.inside, gdstk.all_inside, gdstk.any_inside.

GDSTK uses a hierarchical structure to organize geometry into files.

Library Organization Classes:

• gdstk.Library: The top-level container for a GDSII/OASIS file.
• gdstk.Cell: A container for geometric objects and references.
• gdstk.RawCell: A cell containing raw geometry without references.
• gdstk.Reference: A reference to a cell placed within another cell.
• gdstk.Label: A text label placed within a cell.
• gdstk.GdsWriter: A utility for writing GDSII files.

File I/O and Metadata Functions:

• Reading files: gdstk.read_gds, gdstk.read_oas, gdstk.read_rawcells.
• Metadata and validation: gdstk.gds_units, gdstk.gds_info, gdstk.gds_timestamp, gdstk.oas_precision, gdstk.oas_validate.

Gdstk does not have a dedicated ParametricCell class. Instead, you can implement parametric cells by using the full flexibility of your programming language (Python or C++). You define functions that take user-defined parameters and return a gdstk.Cell containing the generated geometry.

This approach allows for highly complex, rule-based geometry generation that can be reused throughout your layouts.

# Example pattern for a parametric cell in Python
def grating(width, length, period):
    # ... geometry generation logic ...
    cell = gdstk.Cell('GRATING')
    # ... add polygons/paths to cell ...
    return cell

# Usage
my_cell = grating(10, 50, 2)
library.add(my_cell)

For complex geometries, use the gdstk.Curve class instead of manually listing vertices. Its syntax is inspired by the SVG path specification.

Key features:

• Step-by-step construction: Draw shapes incrementally.
• Coordinate types: You can use complex numbers for coordinate pairs (real part = x, imaginary part = y), which is useful for polar coordinates.
• Bézier curves: Supports cubic, quadratic, and general-degree Bézier curves.
• Interpolation: Use gdstk.Curve.interpolation to calculate a smooth interpolating curve with configurable shape control.

The gdstk.Repetition class allows you to instantiate repetitive geometry without the overhead of creating a new gdstk.Cell for every instance.

Creating a gdstk.Reference as an array is essentially a shortcut for creating a single reference with rectangular or regular repetition. This is highly effective for keeping memory usage low during layout construction.

Note: Geometry operations (like scaling or rotation) are not automatically applied to elements within a repetition. If you need to transform the repeated elements, you must manually apply the repetition before executing the operation.

# Example of using Repetition
# (Conceptual pattern)
rep = gdstk.Repetition(element, columns=10, rows=10, spacing=(5, 5))
cell.add(rep)

Gdstk uses a custom dynamic memory management interface. When working with structures that Gdstk may reallocate or free, you must use the provided allocation functions rather than standard malloc or free.

If you need to change how memory is handled globally, you can replace the default implementations in allocator.h and allocator.cpp with your own functions.

Available memory management functions:

• void* allocate(uint64_t size): Equivalent to malloc.
• void* reallocate(void* ptr, uint64_t size): Equivalent to realloc.
• void* allocate_clear(uint64_t size): Equivalent to calloc.
• void free_allocation(void* ptr): Equivalent to free.

// Example of using the allocation API
void* ptr = allocate(1024);
// ... use memory ...
free_allocation(ptr);

You can transform geometry at two levels:

1. Individual Elements: Use methods on specific objects like gdstk.Polygon.scale, gdstk.FlexPath.rotate, or gdstk.RobustPath.translate.
2. Entire Cells:
   • gdstk.Reference (Recommended): Create a reference to a cell with a desired transformation. This is memory-efficient because it does not create actual copies of the geometry.
   • gdstk.Cell.copy: Creates a transformed copy of the cell. Use this if you need to modify the contents of the transformed cell without affecting the original.

# Using a Reference for memory-efficient transformation
ref = gdstk.Reference(original_cell, (x, y), rotation=90)
new_cell.add(ref)

# Using copy for independent modification
new_cell = original_cell.copy()
# ... modify new_cell without affecting original_cell ...

To create a hierarchical design and reduce file size, use gdstk.Reference. Instead of copying geometry, a reference allows a cell to be reused multiple times within another cell (e.g., stamping a transistor shape throughout a circuit).

References allow you to:

• Reuse the same cell content.
• Apply individual transformations (rotation, mirroring, scaling) to each instance.
• Create full 2D arrays of cells using a single entity.

GDSTK handles various geometric shapes with specific behaviors:

• Polygons: Defined by an ordered list of vertices. Vertex orientation (CW/CCW) is handled internally.
• Holes: Since GDSII only supports weakly simple polygons, holes must be defined by connecting their boundary to the boundary of the enclosing shape.
• Circles and Ellipses: Created using gdstk.ellipse. The tolerance argument controls the number of vertices used to approximate the curve.

Important GDSII Limitation: When saving via lib.write_gds, if a polygon has more than max_points vertices (default is 199), it will be fractured into multiple smaller polygons. OASIS files do not have this limit and can automatically convert polygonal circles back to true circles if they fall within a predefined tolerance.