Tutorial 4: Contributing Measured Devices’ Data to the SQuADDS Database#

This tutorial covers how to contribute experimentally-validated devices to the SQuADDS database. These devices are essential for validating simulations and expanding the SQuADDS’s design capabilities.

You can contribute your experimentally-verified device results to the measured_device_database configuration on HuggingFace either via a pull request or by using the SQuADDS native API, as explained in this tutorial.

Let’s start with the available devices in the database to which we plan to contribute our device results.

[1]:

from squadds import SQuADDS_DB

db = SQuADDS_DB()
db.get_measured_devices()

[1]:

	Name	Design Code	Paper Link	Image	Foundry	Substrate	Materials	Junction Style	Junction Materials
0	WM1	https://github.com/LFL-Lab/design_schema_WM1	https://arxiv.org/pdf/2312.13483	https://github.com/LFL-Lab/design_schema_WM1/b...	SQUILL	Silicon	Aluminium	Dolan	Al-AlOx-Al
1	“dissipator”	https://github.com/LFL-Lab/design_schema_dissi...	https://journals.aps.org/prxquantum/abstract/1...	https://github.com/LFL-Lab/design_schema_dissi...	USC Nanofab	Silicon 111	Aluminium	Manhattan	Al-AlOx-Al
2	MUNNIN	https://github.com/LFL-Lab/design_schema_MUNNIN	https://journals.aps.org/prl/abstract/10.1103/...	https://github.com/LFL-Lab/design_schema_MUNNI...	SQUILL	Silicon	Aluminium	Dolan	Al-AlOx-Al

Contribution Guidelines#

To add your measured device results to the SQuADDS database, follow these steps:

Create a GitHub Repository:
- Use the Template Repository: Start by creating your repository from this template. This will provide the necessary structure and files.
- Naming Convention: Rename your repository to design_schema_DEVICENAME or design_schema_DEVICENAME_squadds.
- Visibility: Set the repository to public.
- README File: Update the README with a brief description, key measured results, and any relevant links.
Organize Repository Contents:
- Assets Folder:
  - Add an image of the device (e.g., SEM image, design diagram).
  - (Optional) Include the GDS file.
- Design Folder:
  - Include design-related notebooks or Python scripts.
- Simulations Folder (Optional):
  - Add any simulation code.
Submit to HuggingFace:
- Ensure the repository structure matches the template repository.
- Use either a pull request on the measured_device_database config or the SQuADDS API as described in the next section.

Contributing via SQuADDS API#

To automate the contribution process, you need to generate a GitHub token. This token allows secure access to your repositories and is essential for submitting your device data to the SQuADDS database.

Generate a GitHub Token#

Go to GitHub Settings:
- Click on your profile picture in the top-right corner and select Settings.
Navigate to Developer Settings:
- Scroll down to Developer settings in the left sidebar and click on it.
Create a New Token:
- Click on Personal access tokens, then select Tokens (classic).
- Click on Generate new token.
Set the Permissions:
- Enable the following permissions:
  - ``repo``: Full control of repositories (required for submitting data and making changes).
  - ``workflow``: Access to workflow-related permissions.
- Click Generate token at the bottom.
Copy the Token:
- Important: Copy the generated token immediately as it will only be shown once. Store it securely on your PC, as this token will be used to authenticate your API requests.

Note: We do not store or have access to your token. It is simply needed for the automation of the contribution process and remains on your PC. You have full control over it and can revoke or regenerate the token at any time via your GitHub settings.

Once you have your GitHub token, run the following command to add it to your runtime environment (this needs to be done only once - as the token will be stored in your .env file)

[5]:

from squadds.core.utils import set_github_token

set_github_token()

Token already exists in .env file.

Great! Now we are ready to contribute to the SQuADDS database. First, authenticate using your GitHub token by running the following code cell:

[1]:

from squadds.database.github import (
    login_to_github,
    contribute_measured_data
)

# Authenticate with GitHub using your token from the .env file
github = login_to_github()

Contributing Measured Data#

Before contributing, structure your device data using the template below:

{
    "design_code": "GITHUB REPOSITORY LINK",
    "contrib_info": {
        "group": "GROUP NAME",
        "PI": "PRINCIPAL INVESTIGATOR",
        "institution": "INSTITUTION NAME",
        "uploader": "YOUR NAME",
        "measured_by": ["RESEARCHER 1", "RESEARCHER 2"],
        "date_created": "YYYY-MM-DD",
        "name": "DEVICE NAME" // A unique identifier for your device
    },
    "measured_results": [
        {
            "H_params": [
                // Your measured parameters go here
            ]
        }
    ],
    "sim_results": [
        "SIMULATION_1",
        "SIMULATION_2" // Leave empty if there are no associated simulations
    ],
    "image": "IMAGE LINK FROM GITHUB",
    "paper_link": "PUBLICATION LINK",
    "foundry": "FOUNDRY NAME",
    "fabrication_recipe": "FABRICATION RECIPE LINK", // Optional
    "substrate": "Silicon", // Optional
    "materials": "Aluminium", // Optional
    "junction_style": "Dolan", // Optional
    "junction_material": "Al-AlOx-Al" // Optional
    "notes": "ADDITIONAL NOTES" // Optional
}

Guidelines for Consistency#

Required Fields: Ensure the structure above is followed. If any data is not available, use None.
Custom Fields: You can add additional fields as needed, but please maintain the core structure for uniformity.

Details on Each Field#

``design_code``: Link to your device’s GitHub repository.
``contrib_info``:
- ``group``: Contributing research group.
- ``PI``: Principal Investigator.
- ``institution``: Affiliated institution.
- ``uploader``: Person uploading the data.
- ``measured_by``: Who measured the device.
- ``date_created``: Device creation date.
- ``name``: Device identifier.
``measured_results``: Key measured data, formatted in JSON.
``sim_results``: Associated simulations (leave blank if none).
``image``: Link to device image on GitHub.
``paper_link``: Link to related papers.
``foundry``: Name of the fabricating foundry.
``fabrication_recipe`` (Optional): Link to the fabrication recipe (use Fabublox if available).
``substrate`` (Optional): Substrate material.
``materials`` (Optional): Device materials.
``junction_style`` (Optional): Junction style (e.g., Dolan).
``junction_material`` (Optional): Junction material (e.g., Al-AlOx-Al).
``notes`` (Optional): Additional device details.

Below is an example device entry (new_device_entry) that illustrates how to format and contribute your own data to the SQuADDS database.

[2]:

import datetime

new_device_entry = {
    "design_code": "https://github.com/your_username/design_schema_DEVICENAME",  # Replace with your forked repo URL
    "contrib_info": {
        "group": "Your Research Group",
        "PI": "Dr. Jane Smith",
        "institution": "Your University",
        "uploader": "Your Name",
        "measured_by": ["Researcher A", "Researcher B"],
        "date_created": datetime.date.today().isoformat(),  # Current date in ISO format
        "name": "Device_XYZ"  # A unique name for your device
    },
    "measured_results": [
        {
            "H_params": [
                {
                    "qubit_1": {
                        "F_res_GHz": 6.116,
                        "F_01_GHz": 4.216,
                        "Anharmonicity_MHz": -153,
                        "punchout_shift_MHz": 1.6672,
                        "Extracted_g_MHz": 61,
                        "Estimated_Dispersive_shift_KHz": 303,
                        "L_j_nH": 9.686
                    }
                    # Add more qubits as necessary
                }
            ]
        }
    ],
    "sim_results": [],
    "image": "https://raw.githubusercontent.com/your_username/design_schema_DEVICENAME/main/assets/device_image.png",  # Replace with the URL of your device image
    "paper_link": "https://arxiv.org/abs/1234.5678",  # Replace with the link to your associated paper
    "foundry": "Your Foundry Name",
    "fabrication_recipe": "https://fabublox.com/your_recipe",  # Replace with the link to your fabrication recipe
    "substrate": "Silicon",
    "materials": "Aluminium",
    "junction_style": "Dolan",
    "junction_material": "Al-AlOx-Al",
    "notes": "Additional notes about the device."
}

Now it’s time to share your device dataset with our wonderful quantum community!

The below function call forks our GitHub repository of measured device designs, creates a local clone on your machine, adds your data, and submits a request for review. This allows us to check your data before officially adding it to the SQuADDS datasets family!

[3]:

pr_title="Adding DEVICENAME to SQuADDS_DB"

contribute_measured_data(new_device_entry, pr_title)

Forking the repository: LFL-Lab/SQuADDS_DB to NxtGenLegend's account...
Repository forked successfully: https://github.com/NxtGenLegend/SQuADDS_DB
Cloning repository from https://github.com/NxtGenLegend/SQuADDS_DB into ./temp_forked_repo...
Checking out the main branch...
Reading JSON file from ./temp_forked_repo/measured_device_database.json...
Appending new entry to JSON data...
Saving updated JSON data to ./temp_forked_repo/measured_device_database.json...
Staging and committing changes to measured_device_database.json...
Commit successful with message: Update JSON dataset with new entry - 2024-09-28 09:49:05
Updated remote URL with token for authentication
Pushing changes to the remote main branch...
Push successful.
Successfully pushed changes to the remote repository.
Creating a pull request from NxtGenLegend/SQuADDS_DB:main to LFL-Lab/SQuADDS_DB:main...
Pull request created successfully
Pull request URL: https://github.com/LFL-Lab/SQuADDS_DB/pull/5

We truly thank you for contributing to superconducting quantum research and open-source projects. We look forward to seeing your device data and the incredible impact it will have on the quantum community!

License#

This code is a part of SQuADDS

Developed by Sadman Ahmed Shanto

This tutorial is written by Sadman Ahmed Shanto, Adhish Chakravorty and Elizabeth Kunz

This code is licensed under the MIT License. You may obtain a copy of this license in the LICENSE.txt file in the root directory of this source tree.

Any modifications or derivative works of this code must retain thiscopyright notice, and modified files need to carry a notice indicatingthat they have been altered from the originals.