# How to Understand the Relationship Between Geometric Parameters and Hamiltonian Values in SQuADDS

> Unlock the link between geometric parameters and Hamiltonian values in SQuADDS. Learn how capacitances map to energy parameters and coupling for quantum circuit design.

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

---

**SQuADDS converts raw geometric capacitances into quantum Hamiltonian parameters through a pipeline that maps cross-to-claw and cross-to-ground capacitances to charging energy \(E_C\), derives Josephson energy \(E_J\) from target frequencies, and calculates coupling \(g\) via vectorized capacitance-matrix operations.**

SQuADDS (Superconducting Qubit Automated Design Database System) bridges physical layout geometry with quantum Hamiltonian parameters for transmon qubits. Understanding how geometric parameters translate to Hamiltonian values enables precise targeting of qubit frequencies, anharmonicities, and coupling strengths. This article traces the exact calculation pipeline implemented in the `lfl-lab/squadds` repository, following how capacitance values in femtofarads become the \(E_C\), \(E_J\), and \(g\) parameters that define superconducting circuits.

## The Geometry-to-Hamiltonian Pipeline

The conversion from geometric layout to Hamiltonian values follows a six-step pipeline orchestrated by [`squadds/core/analysis.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/analysis.py) and implemented in [`squadds/calcs/transmon_cross.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py). Each step transforms specific geometric measurements into energy scales or coupling rates.

### Step 1: Extracting Geometric Capacitances

The pipeline begins with two numeric columns stored in the SQuADDS dataset: `cross_to_claw` (capacitance between the cross-shaped island and the readout claw) and `cross_to_ground` (capacitance between the island and the ground plane). These values are extracted from electromagnetic simulations and stored in the dataframe within [`squadds/core/analysis.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/analysis.py) at lines 151-158.

### Step 2: Computing Charging Energy \(E_C\)

The `TransmonCrossHamiltonian.EC()` method converts the sum of geometric capacitances into a charging energy expressed in GHz. This calculation uses **pyEPR**'s `Convert.Ec_from_Cs` function to transform capacitance in femtofarads to energy. The implementation in [`squadds/calcs/transmon_cross.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py) (lines 66-80) handles the unit conversion and returns \(E_C\) as a fundamental energy scale for the transmon qubit.

### Step 3: Solving for Target Josephson Energy \(E_J\)

Given user-specified targets for `qubit_frequency_GHz` and `anharmonicity_MHz`, the system solves for the required Josephson energy. The `TransmonCrossHamiltonian._calculate_target_qubit_params` method (lines 81-95) calls `Transmon.find_EJ_EC` from the **scqubits** library to invert the transmon Hamiltonian and determine the `EJ_target` value that would produce the desired quantum properties.

### Step 4: Deriving Qubit Parameters

The `add_qubit_H_params()` method (lines 60-66) loops over dataset rows to compute complete qubit Hamiltonians. For each design, it applies the previously calculated \(E_C\) and the constant `EJ_target` to the cached function `get_transmon_E01_alpha`. This yields the actual qubit transition frequency `E01` and anharmonicity `α`, which are stored alongside `EC` and `EJ` columns in the dataframe. A chunked version `add_qubit_H_params_chunk` (lines 123-137) handles large datasets efficiently.

### Step 5: Calculating Coupling Strength \(g\)

For cavity-coupled systems identified by `selected_resonator_type` values of `"half"` or `"quarter"`, the pipeline invokes `add_cavity_coupled_H_params()` (lines 69-78). This method repeats the qubit energy calculations, then applies the **vectorized Numba** routine `g_from_cap_matrix_vectorized` (lines 164-176) to evaluate the capacitance-matrix formula mapping geometric parameters and resonator frequency onto the coupling strength `g_MHz`. This implements the physics described in Equation 9 of the SQuADDS paper.

### Step 6: Final Dataframe Assembly

The `Analyzer.get_complete_df` method (lines 300-314) returns a dataframe containing both raw geometric columns (`cross_to_claw`, `cross_to_ground`) and derived Hamiltonian columns (`EC`, `EJ`, `qubit_frequency_GHz`, `anharmonicity_MHz`, `g_MHz`). This unified dataset enables querying, sorting, and closest-match searches against target Hamiltonian specifications.

## Implementation Details and Performance Optimizations

The SQuADDS pipeline implements several computational strategies to handle libraries containing millions of designs efficiently.

### LRU Caching for Hamiltonian Solves

The function `get_transmon_E01_alpha` is wrapped in an LRU cache (`_cached_transmon_E01_alpha`) that stores results for specific \((E_J, E_C)\) pairs. Since many geometric designs may share similar capacitance values, repeated calculations are eliminated, reducing compute time from seconds to milliseconds for duplicate parameter sets.

### Numba Vectorization for Coupling Calculations

The heavy-weight coupling calculation in `g_from_cap_matrix_vectorized` uses Numba's `prange` for parallel CPU execution. This avoids Python loop overhead and provides approximately 10× speedup on large libraries compared to scalar implementations, making it feasible to compute coupling strengths across entire design databases interactively.

### Modular Architecture

Geometry-to-energy conversion lives in the `TransmonCrossHamiltonian` class within [`squadds/calcs/transmon_cross.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py), while high-level orchestration—including system selection and column management—resides in the `Analyzer` class within [`squadds/core/analysis.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/analysis.py). This separation maintains testability and allows the physics layer to evolve independently from the database interface.

## Working with the SQuADDS Analysis Pipeline

The `Analyzer` class provides the primary interface for transforming geometric datasets into Hamiltonian parameter spaces. Below are practical implementations for common use cases.

### Computing Qubit-Only Hamiltonians

To generate Hamiltonian parameters for a library of isolated qubits:

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

# Initialize analyzer with default SQuADDS database

ana = Analyzer()

# Configure for qubit-only analysis

ana.selected_system = "qubit"
ana.target_params = {
    "qubit_frequency_GHz": 5.0,
    "anharmonicity_MHz": 250.0,
}

# Generate complete dataframe with EC, EJ columns

df_full = ana.get_complete_df(ana.target_params)
print(df_full[["cross_to_claw", "cross_to_ground", "EC", "EJ"]].head())

```

This invokes `add_qubit_H_params()` to populate charging and Josephson energies based on the geometric capacitances and your target frequency specifications.

### Processing Cavity-Coupled Systems

For transmons coupled to half-wave or quarter-wave resonators:

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

ana = Analyzer()
ana.selected_system = ["qubit", "cavity_claw"]
ana.selected_resonator_type = "half"

ana.target_params = {
    "qubit_frequency_GHz": 5.2,
    "anharmonicity_MHz": 230.0,
    "cavity_frequency_GHz": 7.0,
    "g_MHz": 40.0,
}

# Triggers vectorized coupling calculation

df = ana.get_complete_df(ana.target_params)
print(df[["EC", "EJ", "g_MHz", "cavity_frequency_GHz"]].head())

```

This configuration triggers `add_cavity_coupled_H_params()`, which computes the coupling strength \(g\) using the capacitance-matrix formalism while respecting the specific resonator geometry.

### Finding Closest Designs to Target Parameters

To identify the geometric design that best matches desired Hamiltonian values:

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

ana = Analyzer()
ana.selected_system = ["qubit", "cavity_claw"]
ana.selected_resonator_type = "quarter"

target = {
    "qubit_frequency_GHz": 5.1,
    "anharmonicity_MHz": 240.0,
    "cavity_frequency_GHz": 7.2,
    "g_MHz": 38.0,
}

# Euclidean distance search in Hamiltonian parameter space

closest = ana.find_closest(
    target_params=target, 
    num_top=1, 
    metric="Euclidean"
)
print("Closest design options:", closest.iloc[0]["design_options"])

```

The `find_closest` method (implemented in [`squadds/core/analysis.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/analysis.py)) searches the complete Hamiltonian dataframe for designs minimizing the distance to your target parameters in the multi-dimensional space of \(f_q\), \(\alpha\), \(f_r\), and \(g\).

## Key Source Files

Understanding the relationship between geometry and Hamiltonians requires familiarity with these specific modules:

- **[`squadds/core/analysis.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/analysis.py)**: Contains the `Analyzer` class that loads the database, delegates Hamiltonian calculations, and exposes `get_complete_df` and `find_closest` methods.
- **[`squadds/calcs/transmon_cross.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py)**: Implements the physics layer with `TransmonCrossHamiltonian`, including `EC()` calculations, target parameter solving, and the Numba-vectorized `g_from_cap_matrix_vectorized` coupling routine.
- **[`squadds/calcs/qubit.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/qubit.py)**: Defines the abstract `QubitHamiltonian` base class establishing the API contract for all qubit-type implementations.
- **`squadds/database/`**: Contains caching helpers and configuration management for `selected_system` and `selected_resonator_type` states.
- **[`squadds/ui/app.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/ui/app.py)**: Provides the web interface for inputting target Hamiltonian values and visualizing matching geometric designs.

## Summary

- **Geometric capacitances** (`cross_to_claw`, `cross_to_ground`) serve as the independent variables in SQuADDS, measured in femtofarads from electromagnetic simulations.
- **Charging energy \(E_C\)** derives directly from geometric capacitances using pyEPR conversion utilities in `TransmonCrossHamiltonian.EC()`.
- **Josephson energy \(E_J\)** solves backwards from target qubit frequencies and anharmonicities using scqubits' transmon solvers.
- **Coupling strength \(g\)** emerges from a capacitance-matrix formula evaluated via Numba-vectorized operations that map geometry and resonator frequency to interaction rates.
- **Performance optimization** relies on LRU caching of transmon diagonalizations and parallel Numba execution for coupling calculations, enabling interactive searches across million-row datasets.
- **The `Analyzer` class** in [`squadds/core/analysis.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/analysis.py) orchestrates the entire pipeline, exposing simple methods to convert geometric libraries into queryable Hamiltonian parameter spaces.

## Frequently Asked Questions

### How does SQuADDS convert femtofarads to charging energy?

SQuADDS uses the `Convert.Ec_from_Cs` function from the **pyEPR** library within the `TransmonCrossHamiltonian.EC()` method. This function applies the standard formula \(E_C = e^2/(2C)\) with appropriate physical constants to convert total capacitance in femtofarads to charging energy in GHz. The calculation appears in [`squadds/calcs/transmon_cross.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py) at lines 66-80.

### What determines the Josephson energy in SQuADDS calculations?

The Josephson energy \(E_J\) solves from the inverse problem: given your target `qubit_frequency_GHz` and `anharmonicity_MHz`, the `TransmonCrossHamiltonian._calculate_target_qubit_params` method uses **scqubits**' `Transmon.find_EJ_EC` to find the \(E_J\) value that produces those quantum properties. This target \(E_J\) remains constant across the dataset while \(E_C\) varies with geometry.

### Why is the coupling calculation vectorized?

The coupling strength \(g\) calculation uses **Numba**'s `prange` parallelization in `g_from_cap_matrix_vectorized` because it must evaluate capacitance-matrix equations across potentially millions of geometric designs. Vectorization avoids Python loop overhead and achieves approximately 10× speedup, making interactive database queries feasible.

### Can I use SQuADDS for qubit designs without resonators?

Yes. Set `ana.selected_system = "qubit"` on your `Analyzer` instance. This invokes `add_qubit_H_params()` rather than `add_cavity_coupled_H_params()`, computing only \(E_C\), \(E_J\), and the resulting qubit frequency and anharmonicity without calculating coupling terms or requiring resonator frequency specifications.