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

> Learn to load capacitance matrix data for TransmonCross qubits from the SQuADDS database with the load_hf_dataset helper. Easily access and filter qubit capacitance for your research.

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

---

**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`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/globals.py). The singleton `SQuADDS_DB` in [`squadds/core/db.py`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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.

```python
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:

```python
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.

```python
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`](https://github.com/lfl-lab/squadds/blob/main/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]`.

```python
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`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py). These functions compute coupling strengths and charging energies directly from the capacitance values in fF.

```python
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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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).