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

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 (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 (line 9) demonstrates the standard import pattern used throughout the library.

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.

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.

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 (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 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 (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) 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.

# 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 – Contains AnsysSimulator.__init__ (lines 88-91) where the DesignPlanar is instantiated and configured with overwrite_enabled.
• 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 – Provides geometry factories: create_qubitcavity, create_claw, create_cpw, create_clt_coupler, and create_ncap_coupler.
• squadds/components/qubits.py – Defines the TransmonCross component used in X-mon LOM analyses.
• 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.
• 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.

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 (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. The TransmonCross component definition referenced by LOM analyses is located in 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 (lines 143-191). These functions accept the same DesignPlanar instance but target specific electromagnetic analyses without requiring a complete device dictionary.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}