How to Load Capacitance Matrix Data for TransmonCross Qubits from the SQuADDS Database

To load capacitance matrix data for TransmonCross qubits from the SQuADDS database, use the load_hf_dataset helper to retrieve the measured_device_database, filter for entries where design.coupler_type equals "TransmonCross", and extract the capacitance values from the sim_results field.

SQuADDS (Superconducting Qubit Automated Design Database) stores every simulated device as a Hugging Face Dataset, including full capacitance matrices for TransmonCross qubits. When you need to calculate coupling strengths or charging energies, you must extract these matrices from the measured_device_database using the Python API. This guide demonstrates how to load capacitance matrix data for TransmonCross qubits from the SQuADDS database and convert the raw JSON entries into NumPy arrays ready for physics calculations.

Understanding the SQuADDS Database Architecture

Hugging Face Dataset Structure

The SQuADDS database is hosted as a Hugging Face Dataset repository defined by the REPO_NAME constant in squadds/core/globals.py. The singleton SQuADDS_DB in squadds/core/db.py manages the loaded dataset state and provides helper methods like get_dataset and filter_by_design. Each device entry contains nested dictionaries for design (geometric parameters) and sim_results (simulation outputs).

Key Data Fields for TransmonCross Qubits

For TransmonCross qubits, the design.coupler_type field is set to "TransmonCross". Older entries may use design.design_options.type with the value "cross". The capacitance matrix components reside in sim_results with specific keys: cross_to_ground, claw_to_ground, cross_to_claw, cross_to_cross, claw_to_claw, and ground_to_ground. All values are stored in femto-farads (fF).

Loading the Measured Device Database

To begin, import the dataset loader from squadds/database/HuggingFace.py. The load_hf_dataset function wraps the Hugging Face datasets library and automatically configures the repository name from your environment variables or the default public repository.

from squadds.database.HuggingFace import load_hf_dataset

# Load the measured device database

cap_dataset = load_hf_dataset(
    dataset_name="measured_device_database",
    config=None
)

Alternatively, you can use the SQuADDS_DB singleton for a more object-oriented approach:

from squadds.core.db import SQuADDS_DB

db = SQuADDS_DB()
cap_dataset = db.get_dataset("measured_device_database")

Filtering for TransmonCross Qubit Entries

Once loaded, filter the dataset to isolate TransmonCross designs. Check both the modern coupler_type field and the legacy design_options.type field to ensure compatibility with all database versions.

transmon_cross_entries = [
    entry for entry in cap_dataset
    if entry["design"].get("coupler_type") == "TransmonCross"
    or entry["design"].get("design_options", {}).get("type") == "cross"
]

Extracting and Constructing the Capacitance Matrix

Understanding the Matrix Components

The capacitance matrix for a TransmonCross qubit describes the electrostatic coupling between the cross pad, the claw coupler, and the ground plane. The SQuADDS database stores these as individual scalar values in sim_results generated by the run_xmon_LOM function in squadds/simulations/objects.py.

JSON Key	Physical Meaning	Unit
cross_to_ground	Capacitance between cross pad and ground	fF
claw_to_ground	Capacitance between claw and ground	fF
cross_to_claw	Coupling capacitance between cross and claw	fF
cross_to_cross	Self-capacitance of cross pad	fF
claw_to_claw	Self-capacitance of claw	fF
ground_to_ground	Ground-plane self-capacitance	fF

Building the 3×3 NumPy Matrix

Convert the JSON fields into a symmetric 3×3 matrix where indices correspond to [cross, claw, ground].

import numpy as np

def build_capacitance_matrix(entry):
    """Construct 3×3 capacitance matrix in fF from database entry."""
    r = entry["sim_results"]
    
    C = np.zeros((3, 3))
    # Diagonal elements (self-capacitance)

    C[0, 0] = r["cross_to_ground"] + r["cross_to_claw"]
    C[1, 1] = r["claw_to_ground"] + r["cross_to_claw"]
    C[2, 2] = r["ground_to_ground"]
    
    # Off-diagonal (coupling capacitance)

    C[0, 1] = C[1, 0] = -r["cross_to_claw"]
    
    return C

# Example usage

first_matrix = build_capacitance_matrix(transmon_cross_entries[0])
print(f"Capacitance matrix (fF):\n{first_matrix}")

Calculating Qubit Parameters from Capacitance Data

With the capacitance matrix loaded, pass the extracted values to the Numba-accelerated calculation utilities in squadds/calcs/transmon_cross.py. These functions compute coupling strengths and charging energies directly from the capacitance values in fF.

from squadds.calcs.transmon_cross import g_from_cap_matrix_numba

# Extract parameters from the matrix

C_q = first_matrix[0, 0]  # Total qubit capacitance (fF)

C_c = abs(first_matrix[0, 1])  # Coupling capacitance (fF)

# Calculate coupling strength

EJ_GHz = 20.0          # Josephson energy

f_res_GHz = 6.5        # Resonator frequency

res_type = "half"      # Half-wave resonator

g_MHz = g_from_cap_matrix_numba(C_q, C_c, EJ_GHz, f_res_GHz, res_type)
print(f"Coupling strength g = {g_MHz:.2f} MHz")

The EC_numba function similarly calculates the charging energy from the total capacitance, enabling full characterization of the TransmonCross qubit Hamiltonian parameters.

Summary

• SQuADDS stores TransmonCross qubit simulations as Hugging Face datasets, with capacitance matrices located in the measured_device_database.
• Use load_hf_dataset from squadds/database/HuggingFace.py or the SQuADDS_DB singleton to access the data.
• Filter entries by checking design.coupler_type == "TransmonCross" or the legacy design.design_options.type == "cross".
• Extract capacitance values from sim_results using keys: cross_to_ground, claw_to_ground, cross_to_claw, cross_to_cross, claw_to_claw, and ground_to_ground (all in fF).
• Construct a 3×3 capacitance matrix and pass the values to g_from_cap_matrix_numba or EC_numba in squadds/calcs/transmon_cross.py for physics calculations.

Frequently Asked Questions

What units does SQuADDS use for capacitance values?

All capacitance values in the SQuADDS database are stored in femto-farads (fF). This includes the matrix entries cross_to_ground, claw_to_ground, and cross_to_claw found in the sim_results field. Because the values are already in fF, they can be passed directly into the calculation utilities in squadds/calcs/transmon_cross.py without unit conversion.

How do I handle older database entries with different JSON schemas?

Older entries may use design.design_options.type with the value "cross" instead of the modern design.coupler_type field set to "TransmonCross". When filtering the dataset, check both conditions to ensure compatibility across all database versions. The SQuADDS_DB singleton in squadds/core/db.py provides helper methods like filter_by_design that abstract these schema differences.

Can I use this data with Qiskit-Metal simulations?

Yes. The capacitance matrix data extracted from SQuADDS corresponds directly to the lumped element parameters used in Qiskit-Metal's TransmonCross component. The simulation engine in squadds/simulations/objects.py (specifically the run_xmon_LOM function) generates the same JSON structure that populates the database, ensuring consistency between simulated designs and the stored capacitance matrices.

Where are the calculation utilities for TransmonCross qubits located?

The physics calculation utilities are located in squadds/calcs/transmon_cross.py. This module contains Numba-accelerated functions including g_from_cap_matrix_numba for calculating coupling strengths and EC_numba for computing charging energies. These functions accept capacitance values in fF directly from the database and return results in standard units (MHz for coupling, GHz for charging energy).

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