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

Use the SQuADDS_DB singleton class from 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 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.

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.

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.

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.

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:

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: 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: Provides helper functions like flatten_df_second_level for DataFrame processing.
• 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 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.

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 and is required for most programmatic interactions with the measured device database.

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