How to Find the Closest Qubit Design Matching Target Hamiltonian Parameters Using SQuADDS Analyzer

Use the Analyzer class from the SQuADDS library to compute distance metrics between your target Hamiltonian parameters and the curated database of simulated superconducting circuits, returning the top N matching geometries.

The SQuADDS (Superconducting QUantum Architecture Design & Data System) repository provides a structured database of pre-simulated qubit and cavity designs. The Analyzer component enables researchers to find the closest qubit design matching target Hamiltonian parameters by treating the search as a vector distance minimization problem across the Hamiltonian parameter space.

Understanding the SQuADDS Analyzer Architecture

The Analyzer class in squadds/core/analysis.py orchestrates the search workflow through four primary stages. First, it interfaces with the SQuADDS_DB singleton to load a filtered subset of the database containing only relevant component types (qubit-only, cavity-only, or qubit-cavity systems). Second, it augments the dataframe with target Hamiltonian parameter columns via _add_target_params_columns, which instantiates concrete Hamiltonian classes like TransmonCrossHamiltonian from squadds/calcs/transmon_cross.py to map geometric parameters to physical values. Third, it applies a configurable distance metric strategy (Euclidean, Manhattan, Chebyshev, Weighted-Euclidean, or custom) from squadds/core/metrics.py to compute vectorized distances between the target parameter vector and every design in the filtered set. Finally, it returns the num_top designs with smallest distances and caches the result for downstream visualization or export.

Step-by-Step Workflow to Find Matching Designs

Initialize the Database and Select Components

Begin by instantiating the database singleton and applying filters to narrow the search space. The SQuADDS_DB class in squadds/core/db.py manages dataframes for qubits, cavities, and couplers.

from squadds.core.db import SQuADDS_DB

db = SQuADDS_DB()
db.select_system(["qubit", "cavity_claw"])
db.select_qubit("transmon_cross")
db.select_cavity_claw("claw_coupler")
db.select_resonator_type("quarter")
db.create_system_df()

The create_system_df() method merges the selected components into a unified dataframe that the Analyzer will search.

Configure Target Hamiltonian Parameters

Define your target Hamiltonian as a dictionary mapping parameter names to numerical values. The keys must match the Hamiltonian parameter columns added by the system-specific Hamiltonian class.

target_params = {
    "qubit_frequency_GHz": 5.2,
    "anharmonicity_MHz": -180.0,
    "cavity_frequency_GHz": 7.8,
    "kappa_kHz": 150.0,
    "g_MHz": 70.0
}

These parameters represent the desired operating point for your quantum system, typically derived from calibration requirements or theoretical models.

Execute the Search with Distance Metrics

Instantiate the Analyzer with the prepared database and invoke find_closest with your target parameters, the number of results desired, and the distance metric.

from squadds.core.analysis import Analyzer

analyzer = Analyzer(db)
closest_df = analyzer.find_closest(
    target_params=target_params,
    num_top=3,
    metric="Euclidean"
)

The metric parameter accepts "Euclidean", "Manhattan", "Chebyshev", "Weighted-Euclidean", or a custom metric class. The method returns a dataframe containing the closest designs sorted by ascending distance.

Complete Code Examples

Direct Analyzer API Usage

For batch processing or integration into existing design pipelines, use the direct API without the UI layer. This example demonstrates the complete workflow from database initialization to result extraction.

from squadds.core.analysis import Analyzer
from squadds.core.db import SQuADDS_DB

# Initialize and configure database

db = SQuADDS_DB()
db.select_system(["qubit", "cavity_claw"])
db.select_qubit("transmon_cross")
db.select_cavity_claw("claw_coupler")
db.select_resonator_type("quarter")
db.create_system_df()

# Create analyzer and define targets

analyzer = Analyzer(db)
target = {
    "qubit_frequency_GHz": 5.0,
    "anharmonicity_MHz": -200.0,
    "cavity_frequency_GHz": 8.5,
    "kappa_kHz": 100.0,
    "g_MHz": 65.0
}

# Find closest designs

results = analyzer.find_closest(target, num_top=5, metric="Euclidean")
print(results[["design_name", "qubit_frequency_GHz", "g_MHz"]])

Streamlit UI Integration with Caching

When building interactive applications, use the cached helper from squadds/ui/utils_query.py to avoid recomputing the database merge on every interaction.

from squadds.ui.utils_query import find_closest_cached

system_type = "Qubit-Cavity"
qubit_type = "transmon_cross"
cavity_type = "claw_coupler"
resonator_type = "quarter"

target_params = {
    "qubit_frequency_GHz": 5.0,
    "anharmonicity_MHz": -200.0,
    "cavity_frequency_GHz": 8.5,
    "kappa_kHz": 100.0,
    "g_MHz": 65.0,
    "resonator_type": resonator_type,
}

results, analyzer = find_closest_cached(
    system_type, qubit_type, cavity_type,
    resonator_type, target_params,
    num_results=5,
    num_cpu="auto",
    skip_df_gen=False
)

# Access specific design parameters

top_design = analyzer.get_design(results.iloc[0])
lj_values = analyzer.get_Ljs(results.iloc[0])

The find_closest_cached function handles the database initialization, dataframe generation, and analyzer instantiation while leveraging @st.cache_data to persist the heavy computation across Streamlit reruns.

Visualizing Results in Hamiltonian Space

After identifying closest designs, visualize their position relative to your target in the Hamiltonian parameter space using the built-in plotting method.

# Assuming analyzer and results exist from previous steps

analyzer.closest_design_in_H_space()

This method renders two-dimensional scatter plots showing the distribution of designs in the database against your target point, typically displaying quarter-wave and half-wave resonator results separately for clarity.

Key Implementation Files

File	Role	Key Components
squadds/core/analysis.py	Core analysis engine	Analyzer class, find_closest(), _add_target_params_columns(), metric selection logic
squadds/core/db.py	Database management	SQuADDS_DB singleton, select_system(), create_system_df()
squadds/core/metrics.py	Distance calculations	EuclideanMetric, ManhattanMetric, ChebyshevMetric, WeightedEuclideanMetric
squadds/calcs/transmon_cross.py	Hamiltonian computation	TransmonCrossHamiltonian class, parameter extraction from geometries
squadds/ui/utils_query.py	UI integration	find_closest_cached(), get_qubit_options(), get_Ljs()
squadds/ui/app.py	Streamlit interface	Form handling, result display, visualization calls

Summary

• The SQuADDS Analyzer treats qubit design search as a vector distance problem in Hamiltonian parameter space, enabling rapid identification of geometries that match target specifications.
• Database initialization requires selecting component types via SQuADDS_DB and calling create_system_df() to merge qubit, cavity, and coupler data.
• Target parameters must include Hamiltonian values such as qubit_frequency_GHz, anharmonicity_MHz, and g_MHz, which the analyzer compares against simulated database entries.
• Distance metrics are configurable via the metric parameter in find_closest(), supporting Euclidean, Manhattan, Chebyshev, and custom strategies implemented in squadds/core/metrics.py.
• Streamlit integration leverages find_closest_cached() in squadds/ui/utils_query.py to avoid recomputing the database merge during UI interactions.

Frequently Asked Questions

What Hamiltonian parameters can I target when searching for qubit designs?

You can target any parameter computed by the specific Hamiltonian class associated with your selected system type. For transmon cross qubits coupled to cavities, common parameters include qubit_frequency_GHz, anharmonicity_MHz, cavity_frequency_GHz, kappa_kHz, and g_MHz. The Analyzer._add_target_params_columns method dynamically adds these columns to the dataframe based on the Hamiltonian implementation in files like squadds/calcs/transmon_cross.py.

How does the Analyzer handle different distance metrics?

The Analyzer class delegates distance calculations to strategy classes defined in squadds/core/metrics.py. When you specify metric="Euclidean" (or "Manhattan", "Chebyshev", "Weighted-Euclidean"), the analyzer instantiates the corresponding class (e.g., EuclideanMetric) and calls its calculate_vectorized method to compute distances between the target vector and all designs in the filtered dataframe. You can also pass a custom metric class that implements this interface.

Can I use the Analyzer without the Streamlit UI?

Yes, the Analyzer class is fully functional outside the Streamlit environment. Import Analyzer from squadds.core.analysis and SQuADDS_DB from squadds.core.db, configure your database filters, create the system dataframe, and call analyzer.find_closest() directly. This approach is ideal for batch processing, automated design workflows, or integration into Jupyter notebooks where you need programmatic access to the closest qubit designs matching your target Hamiltonian parameters.

What is the difference between find_closest and find_closest_cached?

The find_closest method in squadds/core/analysis.py performs the actual distance computation and returns results immediately, while find_closest_cached in squadds/ui/utils_query.py wraps this functionality with Streamlit's @st.cache_data decorator. The cached version persists the expensive database initialization and dataframe generation steps across UI reruns, recomputing only when system type, qubit type, or cavity type selections change. Use find_closest_cached for interactive Streamlit apps and find_closest for scripts or when caching is unnecessary.

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