# How to Generate GDS Layout Files from SQuADDS Design Options for Fabrication

> Learn to generate GDS layout files from SQuADDS Python designs. This guide details using component-specific to_gds methods and the built-in GDS renderer for fabrication-ready files.

- Repository: [Levenson-Falk Lab/squadds](https://github.com/lfl-lab/squadds)
- Tags: how-to-guide
- Published: 2026-03-06

---

**SQuADDS converts Python-based design configurations into fabrication-ready GDSII files using component-specific `to_gds` methods that leverage the library's built-in GDS renderer.**

SQuADDS (Superconducting QUantum Architecture Design & Development Suite) provides a programmatic framework for defining superconducting quantum device geometries. When you generate GDS layout files from SQuADDS design options, you transform abstract parametric definitions into industry-standard mask data suitable for foundry submission. This workflow captures everything from qubit geometries to feedline routing in a single exportable format.

## The SQuADDS-to-GDS Workflow

The standard fabrication pipeline follows five distinct stages implemented across the repository. According to the SQuADDS source code, the process moves from component selection through optional post-processing:

1. **Select a component or system** (e.g., `CoupledSystem` combining a qubit with a feedline)
2. **Configure design options** using the component's constructor parameters
3. **Instantiate the design** to build the internal `Design` object holding geometric primitives
4. **Clean the layout** using helper functions in [`squadds/gds/processing.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/gds/processing.py) (optional)
5. **Export to GDS** via the component's `to_gds` method, which writes `<filename>.gds` to disk

The `to_gds` method internally accesses `self.design.renderers.gds`, disables optional "cheese" visualization layers, and handles wire-bond pad removal before calling the underlying `export_to_gds` function.

## Step-by-Step: Exporting a CoupledSystem to GDS

The `CoupledSystem` class in [`squadds/components/coupled_systems.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/components/coupled_systems.py) demonstrates the complete export pattern. This component combines a qubit, feedline, and optional airbridge structures into a unified layout.

### Configure Design Options

Define the geometric and layer parameters through a nested dictionary structure. The constructor accepts specifications for each sub-component:

```python
from squadds.components.coupled_systems import CoupledSystem

options = {
    "qubit": {
        "junction_type": "xmon",
        "junction_width_um": 0.2,
        "junction_length_um": 0.3,
        "pad_width_um": 200,
        "pad_length_um": 300,
    },
    "feedline": {
        "width_um": 10,
        "gap_um": 6,
    },
    "airbridge": {
        "count": 4,
        "spacing_um": 20,
    },
}

```

### Instantiate and Export

Create the component instance and call `to_gds` to generate the fabrication file. The method automatically appends the `.gds` extension and removes wire-bond pads unless explicitly instructed otherwise:

```python

# Build the design

cs = CoupledSystem(**options)

# Export to GDS (creates my_coupled_system.gds)

cs.to_gds("my_coupled_system")

```

The implementation in [`squadds/components/coupled_systems.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/components/coupled_systems.py) (lines 58-72) handles pad removal by deleting the `"wb_top"` component from the design hierarchy before export. To retain wire-bond pads, pass `include_wirebond_pads=True` to the `to_gds` method.

## Post-Processing GDS Files for Fabrication

After initial export, you often need to flatten hierarchy or add alignment borders before mask submission. The [`squadds/gds/processing.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/gds/processing.py) module provides utility functions for these operations.

### Flattening Hierarchy

Convert nested cell structures into a single top-level cell to simplify foundry processing:

```python
from squadds.gds.processing import flatten_to_top_cell

# Produces my_coupled_system_flattened.gds

flatten_to_top_cell("my_coupled_system.gds")

```

### Adding Fabrication Borders

Include dicing borders or alignment marks using geometric utilities:

```python
from squadds.gds.processing import add_square_border_to_gds

# Add a 5 mm border around the chip

add_square_border_to_gds(
    input_gds_file="my_coupled_system_flattened.gds",
    output_gds_file="my_coupled_system_bordered.gds",
    size_um=5000,
    thickness_um=10,
    layer_number=1,
    datatype=0,
)

```

## Alternative Components and Methods

While `CoupledSystem` provides a complete system-level export, other components implement similar GDS generation capabilities. The [`cavity_claw.py`](https://github.com/lfl-lab/squadds/blob/main/cavity_claw.py) module in `squadds/components/` offers another example of the `to_gds` interface for resonator-based designs.

All components share the same underlying renderer architecture: they instantiate a `Design` object from Qiskit-Metal (or compatible backends), populate it with geometric primitives, and access the GDS renderer through the `design.renderers.gds` attribute.

## Summary

- **Primary export method**: Component classes provide `to_gds(filename)` methods that write GDSII files to disk
- **Source location**: Implementation resides in [`squadds/components/coupled_systems.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/components/coupled_systems.py) with post-processing utilities in [`squadds/gds/processing.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/gds/processing.py)
- **Automatic cleanup**: The export process removes wire-bond pads and visualization layers unless configured otherwise
- **Post-processing**: Use `flatten_to_top_cell` and `add_square_border_to_gds` to prepare files for specific foundry requirements
- **File naming**: The system automatically appends `.gds` extensions to output filenames

## Frequently Asked Questions

### How does SQuADDS handle wire-bond pads during GDS export?

The `to_gds` method in [`squadds/components/coupled_systems.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/components/coupled_systems.py) automatically removes wire-bond pads by deleting the `"wb_top"` component from the design hierarchy before calling the GDS renderer. This produces a bare device suitable for fabrication. To retain wire-bond pads in the output file, pass `include_wirebond_pads=True` when calling `to_gds`.

### What post-processing functions are available for SQuADDS GDS files?

The [`squadds/gds/processing.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/gds/processing.py) module provides several fabrication-ready utilities including `flatten_to_top_cell` for hierarchy simplification and `add_square_border_to_gds` for adding dicing borders or alignment frames. These functions read existing GDS files and write modified versions with the specified geometric alterations.

### Can I generate GDS from components other than CoupledSystem?

Yes. Multiple component classes in the `squadds/components/` directory implement the `to_gds` interface, including the cavity-claw system defined in [`squadds/components/cavity_claw.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/components/cavity_claw.py). Any component that builds a valid `Design` object with geometric primitives can export to GDS using the same renderer-based approach.

### What dependencies are required for GDS generation in SQuADDS?

GDS functionality requires the optional `gds` dependency group. Install these components using `uv sync --extra gds` or the equivalent pip command with the `gds` extra. The rendering backend relies on Qiskit-Metal's GDS renderer, which interfaces with standard GDSII libraries to produce mask-ready output.