# How to Create Multi-Component Systems with Qubits, Cavity_Claw, and Couplers in SQuADDS

> Learn to build multi-component systems with qubits, cavity_claw, and couplers in SQuADDS. Connect transmon qubits, waveguides, and couplers using Qiskit Metal's interface.

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

---

**To create multi-component systems in SQuADDS, instantiate the `CavityClaw` class to assemble transmon qubits, couplers (CLT or CAPN/NCAP), and coplanar waveguides, then connect multiple instances via their registered pins using Qiskit Metal's design interface.**

SQuADDS (Superconducting QUantum Architecture Design and Development Suite) provides a high-level Python API for building complex superconducting circuits directly within Qiskit Metal. The `CavityClaw` component serves as the foundational building block for coupled qubit-cavity systems, encapsulating all necessary sub-components into a single configurable object. By instantiating multiple `CavityClaw` objects and linking them through Qiskit Metal's pin-connection interface, you can rapidly prototype scalable quantum processor layouts.

## Understanding the CavityClaw Architecture

The `CavityClaw` class, defined in [`squadds/components/cavity_claw.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/components/cavity_claw.py), orchestrates three critical sub-components that form a complete qubit-cavity system.

### TransmonClaw Qubit

The **TransmonClaw** generates a transmon-style qubit with customizable claw pads. This component is defined in [`squadds/components/claw_coupler.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/components/claw_coupler.py) and is instantiated internally when you call `make_qubit()`. You can customize pad geometries, connection types, and orientation through the `qubit_options` dictionary.

### Coupler Interface

The **Coupler** provides the electromagnetic link between the qubit and the cavity. SQuADDS supports two primary types:

- **CLT** (Coupled-Line-Tee): A transmission-line based coupling structure
- **CAPN** / **NCAP**: Capacitive inter-digital tee couplers

The coupler selection and configuration occur in `make_coupler()`, which dynamically imports the appropriate Qiskit Metal coupler class based on your `coupler_type` setting.

### Coplanar Waveguide Routing

**CPWs** (Coplanar Waveguides) route microwave signals to and from the qubit-cavity pair. The `make_cpws()` method generates left and optional right meandered transmission lines, automatically sizing them based on the chosen coupler geometry and the `total_length` parameter in `cpw_opts`.

## Step-by-Step Implementation

Follow this workflow to instantiate your first multi-component system.

### 1. Initialize the Design Plane

All components register to a Qiskit Metal design object that stores the generated geometry.

```python
from qiskit_metal import designs
design = designs.DesignPlanar()

```

### 2. Configure Component Options

Each component inherits a `default_options` dictionary. Use the `copier` helper to recursively merge your custom parameters without overriding the entire defaults structure.

```python
from squadds.components.cavity_claw import CavityClaw

my_opts = {
    "cavity_claw_options": {
        "coupler_type": "CLT",
        "coupler_options": {"orientation": "180", "coupling_length": "250um"},
        "cpw_opts": {
            "total_length": "5000um",
            "left_options": {"lead": {"start_straight": 0, "end_straight": 0}},
            "right_options": {"meander": {"spacing": "120um"}}
        },
    },
    "qubit_options": {
        "connection_pads": {"q1": {"connector_type": 0, "claw_length": "40um"}},
        "orientation": "180",
        "pos_y": "1500um",
    },
}

```

### 3. Instantiate and Build Components

Create the `CavityClaw` instance and invoke the build sequence.

```python
cav1 = CavityClaw(design, "cav_system_1", options=my_opts)
cav1.make()  # Triggers make_qubit(), make_coupler(), make_cpws(), make_pins()

```

Calling `make()` executes the internal construction pipeline:
1. `make_qubit()` creates the `TransmonClaw` using parsed `qubit_options`
2. `make_cavity()` delegates to `make_coupler()` and `make_cpws()`
3. `make_pins()` extracts `prime_start` and `prime_end` pins from the coupler and registers them on the design

## Connecting Multiple Components

To create multi-component systems, instantiate additional `CavityClaw` objects and link them via their registered pins. The pin names follow the format `{component_name}.prime_start` and `{component_name}.prime_end`.

```python

# Create a second cavity system with default options

cav2 = CavityClaw(design, "cav_system_2")
cav2.make()

# Connect the output of cav1 to the input of cav2

design.connect_pins(f"{cav1.name}.prime_end", f"{cav2.name}.prime_start")

```

This approach enables complex topologies such as:
- Multiple `CavityClaw` units linked via a common feedline
- Readout resonators coupled to specific cavity pins
- Custom interconnects using wire-bond launch pads

### Adding Wire-Bond Launch Pads

For packaging and measurement accessibility, generate wire-bond pads on both sides of the coupler:

```python
cav1.make_wirebond_pads()

```

## Exporting and Visualizing Designs

Once your multi-component system is assembled, export the geometry for fabrication or simulation.

```python

# Visualize in the Qiskit Metal GUI

design.visualize()

# Export to GDSII format for mask generation

design.export_gds("multicavity_system.gds")

```

All geometry is stored in Qiskit Metal's `qgeometry` tables, compatible with downstream electromagnetic simulation tools.

## Summary

- **CavityClaw** is the core component in [`squadds/components/cavity_claw.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/components/cavity_claw.py) that encapsulates qubits, couplers, and CPWs.
- The `make()` method orchestrates construction through `make_qubit()`, `make_coupler()`, `make_cpws()`, and `make_pins()`.
- Supported coupler types include **CLT** and **CAPN/NCAP**, selected via `coupler_type` in the options dictionary.
- Multi-component systems are built by instantiating multiple `CavityClaw` objects and connecting them via `design.connect_pins()` using the `prime_start` and `prime_end` pins.
- Customization occurs through the `default_options` hierarchy, merged using the internal `copier` method.

## Frequently Asked Questions

### How do I connect two CavityClaw instances together?

After calling `make()` on each instance, use `design.connect_pins(cav1.name + ".prime_end", cav2.name + ".prime_start")`. This links the output pin of the first cavity to the input pin of the second, creating a continuous transmission line without manual geometry stitching.

### What coupler types are supported in SQuADDS?

SQuADDS supports **CLT** (Coupled-Line-Tee) and **CAPN** / **NCAP** (capacitive inter-digital tees). Specify your choice in the `cavity_claw_options.coupler_type` field. The system dynamically instantiates the corresponding Qiskit Metal coupler class during the `make_coupler()` phase.

### Can I customize the transmon qubit geometry?

Yes. Pass a `qubit_options` dictionary when instantiating `CavityClaw`. This overrides specific fields in the `TransmonClaw` defaults defined in [`squadds/components/claw_coupler.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/components/claw_coupler.py), such as `claw_length`, `connection_pads`, and `orientation`.

### How do I export the final design to GDSII?

Call `design.export_gds("filename.gds")` on your `DesignPlanar` instance. This exports all generated geometry from the `qgeometry` tables, including all `CavityClaw` components, couplers, and wire-bond pads, into a standard GDSII format suitable for fabrication.