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

> Find the closest qubit design matching target Hamiltonian parameters with SQuADDS Analyzer. Compute distance metrics and retrieve top N matching geometries from our simulated circuit database.

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

---

**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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/db.py) manages dataframes for qubits, cavities, and couplers.

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

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

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

```python
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`](https://github.com/lfl-lab/squadds/blob/main/squadds/ui/utils_query.py) to avoid recomputing the database merge on every interaction.

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

```python

# 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`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/analysis.py) | Core analysis engine | `Analyzer` class, `find_closest()`, `_add_target_params_columns()`, metric selection logic |
| [`squadds/core/db.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/db.py) | Database management | `SQuADDS_DB` singleton, `select_system()`, `create_system_df()` |
| [`squadds/core/metrics.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/metrics.py) | Distance calculations | `EuclideanMetric`, `ManhattanMetric`, `ChebyshevMetric`, `WeightedEuclideanMetric` |
| [`squadds/calcs/transmon_cross.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py) | Hamiltonian computation | `TransmonCrossHamiltonian` class, parameter extraction from geometries |
| [`squadds/ui/utils_query.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/ui/utils_query.py) | UI integration | `find_closest_cached()`, `get_qubit_options()`, `get_Ljs()` |
| [`squadds/ui/app.py`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/metrics.py).
- **Streamlit integration** leverages `find_closest_cached()` in [`squadds/ui/utils_query.py`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/analysis.py) performs the actual distance computation and returns results immediately, while `find_closest_cached` in [`squadds/ui/utils_query.py`](https://github.com/lfl-lab/squadds/blob/main/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.