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

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 and implemented in 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 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 (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, while high-level orchestration—including system selection and column management—resides in the Analyzer class within 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:

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:

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:

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

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