# How to Access the Measured Device Database and Fabrication Recipes from SQuADDS

> Access the measured device database and fabrication recipes from SQuADDS using the SQuADDS_DB singleton class. Retrieve experimental data and view recipes easily.

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

---

**Use the `SQuADDS_DB` singleton class from [`squadds/core/db.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/db.py) to load the Hugging Face dataset `SQuADDS/SQuADDS_DB` and call `get_measured_devices()`, `view_measured_devices()`, or `view_recipe_of(device_name)` to retrieve experimental data and fabrication recipes.**

SQuADDS (Superconducting Quantum Atomic-scale Design Database System) stores comprehensive experimental device information—including design codes, fabrication recipes, and foundry data—in a centralized Hugging Face dataset. This guide explains how to access the measured device database and fabrication recipes from SQuADDS using the high-level Python API implemented in the `SQuADDS_DB` class.

## Understanding the Database Architecture

The measured device database in SQuADDS follows a layered architecture that separates data storage from user interaction.

### Hugging Face Dataset Storage

All measured device entries are stored in the **`SQuADDS/SQuADDS_DB`** dataset under the `measured_device_database` configuration. Each entry contains fields such as `design_code`, `foundry`, `fabrication_recipe`, `substrate`, `materials`, `junction_style`, and `junction_material`. The dataset is hosted on Hugging Face and requires authentication via the `check_login` helper.

### The SQuADDS_DB Singleton

The **`SQuADDS_DB`** class in [`squadds/core/db.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/db.py) acts as a database façade using the singleton pattern (`SingletonMeta`). This class centralizes authentication, caches the dataset locally, and provides Pythonic methods to query the measured device database without manual HTTP calls.

## Initializing the Database Connection

To begin, import the `SQuADDS_DB` class and instantiate the singleton. The class automatically handles Hugging Face authentication and dataset caching.

```python
from squadds.core.db import SQuADDS_DB

# Returns the same singleton instance on every call

db = SQuADDS_DB()

```

## Querying Measured Devices

Once initialized, you can retrieve device information using two complementary approaches: as a pandas DataFrame for programmatic analysis or as a formatted table for quick inspection.

### Retrieve Data as a pandas DataFrame

Call **`get_measured_devices()`** to load the entire catalogue into a DataFrame. This method returns columns including `Name`, `Design Code`, `Paper Link`, `Image`, `Foundry`, `Substrate`, `Materials`, `Junction Style`, and `Junction Materials`.

```python
import pandas as pd

# Load the measured device database

df = db.get_measured_devices()

# Inspect the first few entries

print(df.head())

```

### Display a Formatted Table

For quick CLI inspection, use **`view_measured_devices()`**, which internally calls `tabulate` to print a human-readable table of the same dataset.

```python
db.view_measured_devices()

```

## Accessing Fabrication Recipes

Fabrication recipes contain step-by-step instructions, layout GDS files, and mask specifications required to reproduce devices. SQuADDS stores these in GitHub folders linked to each device's design code.

### View Recipe for a Specific Device

The **`view_recipe_of(device_name)`** method prints a three-column table showing the foundry, Fabublox link, and GitHub URL for the fabrication recipe folder.

```python
device_name = "Xmon-v2"  # Use the exact name from the Name column

db.view_recipe_of(device_name)

```

Sample output:

```

+----------------+----------------------+-----------------------------------------------------------+
| Foundry        | Fabublox Link       | Fabrication Recipe Links                                 |
+----------------+----------------------+-----------------------------------------------------------+
| Foundry A      | fab_link_here       | https://github.com/LFL-Lab/SQuADDS/.../Fabrication       |
+----------------+----------------------+-----------------------------------------------------------+

```

The GitHub URL follows the pattern `https://github.com/LFL-Lab/SQuADDS/tree/main/Fabrication/{design_code}`.

### Programmatically Fetch Recipe URLs

If you need the recipe URL for automation, extract the `design_code` from the DataFrame and construct the URL as implemented in [`squadds/core/db.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/db.py):

```python
def get_recipe_url(device_name: str) -> str | None:
    dataset = db.get_measured_devices()
    row = dataset[dataset["Name"] == device_name]
    if not row.empty:
        design_code = row.iloc[0]["Design Code"]
        return f"https://github.com/LFL-Lab/SQuADDS/tree/main/Fabrication/{design_code}"
    return None

url = get_recipe_url("Xmon-v2")
print(url)  # Output: https://github.com/LFL-Lab/SQuADDS/tree/main/Fabrication/X001

```

## Key Implementation Files

The database functionality is implemented across these source files:

- **[`squadds/core/db.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/db.py)**: Contains the `SQuADDS_DB` singleton class with methods `get_measured_devices` (lines 31-89), `view_measured_devices`, and `view_recipe_of` (lines 730-754).
- **[`squadds/core/utils.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/utils.py)**: Provides helper functions like `flatten_df_second_level` for DataFrame processing.
- **[`pyproject.toml`](https://github.com/lfl-lab/squadds/blob/main/pyproject.toml)**: Declares runtime dependencies including `pandas`, `datasets`, and `tabulate`.

## Summary

- **Dataset Location**: Measured device data is stored in the Hugging Face dataset `SQuADDS/SQuADDS_DB` under the `measured_device_database` configuration.
- **Entry Point**: Use the `SQuADDS_DB` singleton from [`squadds/core/db.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/db.py) to interact with the database.
- **Data Retrieval**: Call `get_measured_devices()` for a pandas DataFrame or `view_measured_devices()` for formatted console output.
- **Recipe Access**: Use `view_recipe_of(device_name)` to display fabrication details, or construct URLs manually using the `design_code` field pointing to `github.com/LFL-Lab/SQuADDS/tree/main/Fabrication/`.

## Frequently Asked Questions

### Where is the SQuADDS measured device database stored?

The database is hosted as a Hugging Face dataset named `SQuADDS/SQuADDS_DB` with the configuration `measured_device_database`. Each entry contains experimental metadata including foundry information, materials, and links to fabrication recipes stored in the repository.

### How does the SQuADDS_DB class handle authentication?

The `SQuADDS_DB` singleton automatically calls `check_login` when loading data, prompting for Hugging Face credentials if not already cached. This occurs transparently in methods like `get_measured_devices()` and `view_recipe_of()` according to the implementation in [`squadds/core/db.py`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/db.py).

### What information is included in a fabrication recipe?

Fabrication recipes include the foundry name, Fabublox process links, and a GitHub URL pointing to a folder containing layout GDS files, mask specifications, and step-by-step fabrication instructions for reproducing the specific device design.

### Can I query the database without installing pandas?

While `get_measured_devices()` returns a pandas DataFrame, you can use `view_measured_devices()` which relies only on `tabulate` for formatted output. However, `pandas` is a declared dependency in [`pyproject.toml`](https://github.com/lfl-lab/squadds/blob/main/pyproject.toml) and is required for most programmatic interactions with the measured device database.