# How to Set Up Qiskit-Metal DesignPlanar for Superconducting Component Simulation in SQuADDS

> Learn to set up Qiskit-Metal DesignPlanar for superconducting component simulation in SQuADDS. Bridge Qiskit-Metal geometry with Ansys HFSS for robust electromagnetic analysis.

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

---

**Instantiate `metal.designs.design_planar.DesignPlanar()`, enable `overwrite_enabled = True`, and pass the design object to SQuADDS simulation helpers like `simulate_whole_device()` to bridge Qiskit-Metal geometry with Ansys HFSS electromagnetic analysis.**

SQuADDS (Superconducting QUantum Design and Simulation) uses **Qiskit-Metal** as its underlying geometry engine for planar microwave layouts. Configuring a **Qiskit-Metal DesignPlanar for superconducting component simulation** is the required first step before running eigenmode or lumped oscillator model analyses. This guide follows the exact implementation patterns found in the `lfl-lab/squadds` repository, from design instantiation through simulation execution.

## What is DesignPlanar in SQuADDS?

The `DesignPlanar` class from `qiskit_metal.designs.design_planar` serves as the central object representing planar quantum device layouts. In [`squadds/simulations/ansys_simulator.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/ansys_simulator.py) (line 88), the `AnsysSimulator` class initializes this object to manage component placement and geometric relationships. All high-level simulation pipelines in SQuADDS—including `simulate_whole_device`, `run_eigenmode`, and `run_xmon_LOM`—expect this design instance as their primary input.

## Step-by-Step Setup Guide

### Importing Qiskit-Metal and SQuADDS

Start by importing the metal module and the simulation helpers. The source code in [`squadds/simulations/ansys_simulator.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/ansys_simulator.py) (line 9) demonstrates the standard import pattern used throughout the library.

```python
import qiskit_metal as metal
from squadds.simulations.objects import simulate_whole_device
from squadds.core.utils import deepcopy

```

### Instantiating the Design Object

Create a fresh `DesignPlanar` instance. This object holds all geometric components including qubits, cavities, and couplers for the duration of the simulation workflow.

```python
design = metal.designs.design_planar.DesignPlanar()

```

### Configuring the Design Environment

Enable component overwriting to allow iterative parameter sweeps without manual cleanup. Optionally launch the **Metal GUI** for visual inspection of the layout before simulation.

```python
design.overwrite_enabled = True  # Essential for component replacement during sweeps

gui = metal.MetalGUI(design)     # Optional: interactive visual debugging

```

This configuration mirrors the setup found in [`squadds/simulations/ansys_simulator.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/ansys_simulator.py) (lines 88-91), where `AnsysSimulator.__init__` prepares the design for automated geometry building.

### Building the Geometry

SQuADDS provides factory functions in [`squadds/simulations/utils.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/utils.py) to construct specific superconducting components. When you call high-level simulation helpers, they internally invoke `create_qubitcavity`, `create_claw`, `create_cpw`, and coupler generators like `create_clt_coupler` or `create_ncap_coupler`. The `simulate_whole_device` function in [`squadds/simulations/objects.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/objects.py) (lines 38-45) orchestrates these geometry builders based on your device dictionary.

### Running Simulations

Pass the configured design to simulation helpers. The `simulate_whole_device` function (lines 86-124 in [`squadds/simulations/objects.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/objects.py)) automatically renders geometry to Ansys HFSS, runs the specified analyses, and returns structured results.

## Complete Working Example

The following example demonstrates the full workflow: creating the design, configuring a device dictionary with qubit and cavity parameters, and executing a complete simulation pipeline.

```python

# 1️⃣ Import Qiskit-Metal and SQuADDS helpers

import qiskit_metal as metal
from squadds.simulations.objects import simulate_whole_device
from squadds.core.utils import deepcopy

# 2️⃣ Define a device dictionary (geometry + simulation setup)

device_dict = {
    "design_options_qubit": {
        "cross_gap": "5um",
        "cross_width": "10um",
        "cross_length": "300um",
        "claw_opts": {"claw_gap": "2um", "claw_length": "30um"},
        "cpw_opts": {"total_length": "500um", "width": "10um"},
    },
    "design_options_cavity_claw": {
        "cpw_opts": {"total_length": "2000um", "width": "15um"},
        "claw_opts": {"claw_gap": "2um", "claw_length": "40um"},
    },
    "coupler_type": "CLT",  # or "NCap"

    "setup": {
        "max_passes": 30,
        "max_delta_f": 0.02,
        "min_converged_passes": 3,
    },
}

# 3️⃣ Instantiate the DesignPlanar

design = metal.designs.design_planar.DesignPlanar()
design.overwrite_enabled = True  # Allow component replacement

# (optional) open a GUI to inspect the layout

# gui = metal.MetalGUI(design)

# 4️⃣ Run a full device simulation (eigenmode + LOM)

results, lom_obj, emode_obj = simulate_whole_device(
    design,
    deepcopy(device_dict),  # deep-copy prevents side-effects

    emode_setup=None,
    lom_setup=None,
    open_gui=False,
    generate_plots=False,
)

# 5️⃣ Inspect the key outputs

print("Cavity frequency (GHz):", results["sim_results"]["cavity_frequency_GHz"])
print("Q factor:", results["sim_results"]["Q"])
print("Coupling g (MHz):", results["sim_results"]["g_MHz"])

```

## Key Source Files and Implementation Details

Understanding where specific functionality resides helps when customizing simulations:

- **[`squadds/simulations/ansys_simulator.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/ansys_simulator.py)** – Contains `AnsysSimulator.__init__` (lines 88-91) where the `DesignPlanar` is instantiated and configured with `overwrite_enabled`.
- **[`squadds/simulations/objects.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/objects.py)** – Houses `simulate_whole_device` (lines 86-124), `run_eigenmode` (lines 143-191), and `run_xmon_LOM` for executing specific analysis types.
- **[`squadds/simulations/utils.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/utils.py)** – Provides geometry factories: `create_qubitcavity`, `create_claw`, `create_cpw`, `create_clt_coupler`, and `create_ncap_coupler`.
- **[`squadds/components/qubits.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/components/qubits.py)** – Defines the `TransmonCross` component used in X-mon LOM analyses.
- **[`squadds/core/utils.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/utils.py)** – Contains helper utilities including the `deepcopy` wrapper used when passing device dictionaries to simulation functions.

## Summary

- **Import** `qiskit_metal as metal` to access the Qiskit-Metal design engine.
- **Instantiate** `DesignPlanar()` and immediately set `overwrite_enabled = True` to support iterative geometry updates during parameter sweeps.
- **Visualize** layouts using `MetalGUI(design)` when debugging geometric configurations.
- **Build** geometry implicitly by passing the design to `simulate_whole_device()` or explicitly through factory functions in [`utils.py`](https://github.com/lfl-lab/squadds/blob/main/utils.py).
- **Execute** simulations using the returned design object with specific runners like `run_eigenmode()` or `run_xmon_LOM()`.

## Frequently Asked Questions

### What is the purpose of overwrite_enabled in DesignPlanar?

Setting `design.overwrite_enabled = True` allows new components to replace existing ones with identical names without clearing the entire design canvas. This capability is essential for automated parameter sweeps where geometry must update iteratively between simulation runs, as implemented in [`squadds/simulations/ansys_simulator.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/ansys_simulator.py).

### How do I visualize the design before running simulations?

After instantiating your `DesignPlanar`, pass it to `metal.MetalGUI(design)` to open an interactive viewer. This step—shown in [`ansys_simulator.py`](https://github.com/lfl-lab/squadds/blob/main/ansys_simulator.py) (line 90)—enables visual inspection of qubits, cavities, and transmission lines before invoking Ansys HFSS, helping catch geometric errors early in the workflow.

### Where are the geometry building functions located in SQuADDS?

The factory functions `create_qubitcavity`, `create_claw`, `create_cpw`, and coupler generators (`create_clt_coupler`, `create_ncap_coupler`) reside in [`squadds/simulations/utils.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/utils.py). The `TransmonCross` component definition referenced by LOM analyses is located in [`squadds/components/qubits.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/components/qubits.py).

### Can I use DesignPlanar for single-qubit simulations without the full device?

Yes. Instead of the comprehensive `simulate_whole_device`, use the granular helpers `run_eigenmode()` or `run_xmon_LOM()` defined in [`squadds/simulations/objects.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/objects.py) (lines 143-191). These functions accept the same `DesignPlanar` instance but target specific electromagnetic analyses without requiring a complete device dictionary.