# How to Compute Qubit-Resonator Coupling Strength (g_MHz) in SQuADDS

> Learn how to compute qubit-resonator coupling strength g_MHz in SQuADDS using the g_from_cap_matrix method. Derive g from physical capacitances and resonator parameters.

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

---

**In SQuADDS, you compute the qubit-resonator coupling strength g (in MHz) using the `g_from_cap_matrix` method of the `TransmonCrossHamiltonian` class, which implements the capacitance-matrix formalism to derive g from physical capacitances, Josephson energy, and resonator parameters.**

SQuADDS (Superconducting Qubit Automated Design and Device Simulation) provides a complete framework for designing transmon qubits coupled to microwave resonators. To compute the qubit-resonator coupling strength g_MHz—the critical parameter that determines how quickly excitations swap between the qubit and cavity—you must use the capacitance-matrix formalism implemented in the Hamiltonian calculation modules.

## Understanding the Capacitance-Matrix Formalism

The coupling strength calculation relies on treating the qubit and resonator as a coupled system described by a capacitance matrix. In [`squadds/calcs/transmon_cross.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py), the implementation converts geometric capacitances (extracted from electromagnetic simulations) into the Hamiltonian coupling parameter g. This approach accounts for the qubit charging energy, the resonator frequency, and the mutual capacitance between the two subsystems.

## The g_from_cap_matrix Method Implementation

The core calculation resides in the `g_from_cap_matrix` method of the `TransmonCrossHamiltonian` class (lines 72–95 of [`squadds/calcs/transmon_cross.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py)). This method executes the full physics pipeline from raw capacitances to the final coupling strength in MHz.

### Input Parameters and Unit Conversions

The method accepts the qubit self-capacitance `C_Q` and coupling capacitance `C_g` in femtofarads, converting them to farads internally (lines 96–98). It calculates the total qubit capacitance as `C_q_total = C_Q + C_g`. The resonator angular frequency `ω_r` is derived from the input frequency `f_r` (in GHz) as `ω_r = 2π * f_r * 10^9` rad/s (line 104).

### Resonator Capacitance Calculation

Using the transmission-line model (lines 108–112), the method computes the resonator capacitance `C_r` using the formula `C_r = π / (N * ω_r * Z_0)`, where `N = 2` for half-wave resonators and `N = 4` for quarter-wave resonators, and `Z_0` is the characteristic impedance (default 50 Ω).

### Coupling Energy and Final Conversion

The method forms the capacitance matrix determinant (line 118) as `(C_q_total) * (C_r + C_g) - C_g^2`. It derives the effective qubit capacitance `C_q_eff = det(C) / (C_r + C_g)` and computes the charging energy `E_C` using `Convert.Ec_from_Cs` (line 124).

The coupling energy in joules is calculated using the formula from Koch et al. (line 131), combining the capacitance ratio, resonator frequency, and the `E_J / 8E_C` ratio. Finally, the method converts this energy to frequency in MHz (lines 131–132) by dividing by `ħ` and `2π`, then scaling to megahertz.

## Practical Code Examples

### Direct Calculation with g_from_cap_matrix

To compute g directly from known capacitances and energies:

```python
from squadds.calcs.transmon_cross import TransmonCrossHamiltonian

# Parameters (example values)

C_q   = 120.0   # qubit self-capacitance, fF

C_c   = 5.0     # coupling capacitance, fF

E_J   = 20.0    # Josephson energy, GHz

f_r   = 7.0     # resonator frequency, GHz

res_type = "half"   # "half" or "quarter"

Z0    = 50.0    # characteristic impedance, Ω

ham = TransmonCrossHamiltonian(analysis=None)   # analysis object optional for plotting

g_MHz = ham.g_from_cap_matrix(C_q, C_c, E_J, f_r, res_type, Z0)
print(f"Coupling strength g = {g_MHz:.2f} MHz")

```

### Solving for Target Coupling with calculate_target_quantities

When designing for a specific coupling strength, use the `calculate_target_quantities` function (lines 38–59 of [`squadds/calcs/transmon_cross.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py)), which employs a Brent root-finder to solve for the required coupling capacitance:

```python
from squadds.calcs.transmon_cross import calculate_target_quantities

# Desired target coupling strength

target_g = 30.0   # MHz

# Other required parameters

f_res   = 7.0     # resonator frequency, GHz

alpha   = 0.3     # anharmonicity, GHz (300 MHz)

w_q     = 5.0     # qubit frequency, GHz

N       = 1       # number of photons (default for single-photon case)

# Compute the required design quantities (including C_c)

C_q_fF, C_c_fF, EJ, EC, EJ_EC_ratio = calculate_target_quantities(
    f_res, alpha, target_g, w_q, N, Z_0=50
)

print(f"Required coupling capacitance C_c = {C_c_fF:.3f} fF")
print(f"Resulting g (check) = {target_g} MHz")

```

### High-Level Analysis Pipeline

For batch processing of design DataFrames, use the `Analysis` class from [`squadds/core/analysis.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/analysis.py):

```python
from squadds.core.analysis import Analysis

# Create an analysis object with a DataFrame of designs (simplified)

analysis = Analysis()

# Assume `analysis.df` already contains columns `cross_to_claw`, `cross_to_ground`, etc.

# Add cavity-coupled Hamiltonian parameters (including g) to the DataFrame:

analysis.add_cavity_coupled_H_params(num_chunks="auto", Z_0=50)

# Inspect the computed g column

print(analysis.df["g_MHz"].head())

```

## Key Source Files and Architecture

The coupling strength calculation spans multiple modules in the SQuADDS repository:

| File | Purpose |
|------|---------|
| [`squadds/calcs/transmon_cross.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py) | Core physics implementation containing `TransmonCrossHamiltonian.g_from_cap_matrix` (lines 72–95) and `calculate_target_quantities` (lines 38–59). Handles the capacitance-matrix determinant, charging energy conversion, and the Koch et al. coupling formula. |
| [`squadds/core/analysis.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/analysis.py) | High-level workflow orchestration. The `Analysis.add_cavity_coupled_H_params` method invokes the Hamiltonian calculations to enrich DataFrames with `g_MHz` values derived from geometric design parameters. |
| [`squadds/components/qubits.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/components/qubits.py) | Defines the `TransmonCross` geometry class, providing physical dimensions (cross lengths, claw positions) that feed into the capacitance calculations for `C_Q` and `C_g`. |
| [`squadds/simulations/utils.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/utils.py) | Provides numerical root-finding (`brentq`) used by `calculate_target_quantities` to solve for the required coupling capacitance given a target `g`. |
| [`squadds/calcs/qubit.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/qubit.py) | Abstract base class defining the Hamiltonian API (`g_and_alpha`, `g_from_cap_matrix`, etc.), ensuring consistent interfaces across different qubit implementations. |

## Summary

- The **qubit-resonator coupling strength** `g_MHz` in SQuADDS is computed via the **capacitance-matrix formalism** implemented in `TransmonCrossHamiltonian.g_from_cap_matrix`.
- The calculation converts geometric capacitances (fF) to the **Koch et al.** coupling formula, accounting for qubit charging energy `E_C`, Josephson energy `E_J`, and transmission-line resonator capacitance.
- Use **`calculate_target_quantities`** to solve the inverse problem: determining the required coupling capacitance `C_c` to achieve a target `g` value using Brent root-finding.
- For batch processing, **`Analysis.add_cavity_coupled_H_params`** automatically computes `g_MHz` across design DataFrames using the underlying Hamiltonian methods in [`squadds/calcs/transmon_cross.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py).

## Frequently Asked Questions

### What units does SQuADDS use for the coupling strength calculation?

SQuADDS accepts capacitances in **femtofarads (fF)** and energies in **gigahertz (GHz)**, but internally converts these to base SI units (farads and joules) within `g_from_cap_matrix`. The final output `g_MHz` is returned in **megahertz (MHz)** after converting the coupling energy from joules via division by `ħ` and `2π`, then scaling by `10⁻⁶`.

### How does SQuADDS determine the resonator capacitance from geometric parameters?

The resonator capacitance `C_r` is calculated using the **transmission-line model** in `g_from_cap_matrix` (lines 108–112). The formula `C_r = π / (N * ω_r * Z_0)` relates the resonator's angular frequency `ω_r` (derived from `f_r` in GHz), the characteristic impedance `Z_0` (default 50 Ω), and the mode number `N` (2 for half-wave, 4 for quarter-wave resonators).

### Can I calculate the coupling capacitance needed for a specific target g?

Yes. Instead of computing `g` from known capacitances, use the **`calculate_target_quantities`** function (lines 38–59 of [`squadds/calcs/transmon_cross.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py)). This function employs a **Brent root-finder** (`brentq` from [`squadds/simulations/utils.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/utils.py)) to solve for the coupling capacitance `C_c` that yields your desired `target_g` (in MHz), given constraints on qubit frequency, anharmonicity, and resonator frequency.

### Where is the abstract interface for Hamiltonian calculations defined?

The abstract base class defining the required API for Hamiltonian calculations—including methods like `g_from_cap_matrix` and `g_and_alpha`—is located in **[`squadds/calcs/qubit.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/qubit.py)**. This ensures that all qubit implementations in SQuADDS, such as `TransmonCrossHamiltonian`, expose consistent interfaces for computing coupling strengths and anharmonicities.