{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Tutorial 4: Contributing Measured Devices' Data to the SQuADDS Database\n", "\n", "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.\n", "\n", "You can contribute your experimentally-verified device results to the `measured_device_database` [configuration on HuggingFace](https://huggingface.co/datasets/SQuADDS/SQuADDS_DB/viewer/measured_device_database) either via a pull request or by using the SQuADDS native API, as explained in this tutorial. \n", "\n", "---\n", "\n", "Let's start with the available devices in the database to which we plan to contribute our device results." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [ { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "2209d6f87c7646b7af97b6dc230cfc4c", "version_major": 2, "version_minor": 0 }, "text/plain": [ "Downloading readme: 0%| | 0.00/2.75k [00:00\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
NameDesign CodePaper LinkImageFoundrySubstrateMaterialsJunction StyleJunction Materials
0WM1https://github.com/LFL-Lab/design_schema_WM1https://arxiv.org/pdf/2312.13483https://github.com/LFL-Lab/design_schema_WM1/b...SQUILLSiliconAluminiumDolanAl-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 NanofabSilicon 111AluminiumManhattanAl-AlOx-Al
2MUNNINhttps://github.com/LFL-Lab/design_schema_MUNNINhttps://journals.aps.org/prl/abstract/10.1103/...https://github.com/LFL-Lab/design_schema_MUNNI...SQUILLSiliconAluminiumDolanAl-AlOx-Al
\n", "" ], "text/plain": [ " Name Design Code \\\n", "0 WM1 https://github.com/LFL-Lab/design_schema_WM1 \n", "1 “dissipator” https://github.com/LFL-Lab/design_schema_dissi... \n", "2 MUNNIN https://github.com/LFL-Lab/design_schema_MUNNIN \n", "\n", " Paper Link \\\n", "0 https://arxiv.org/pdf/2312.13483 \n", "1 https://journals.aps.org/prxquantum/abstract/1... \n", "2 https://journals.aps.org/prl/abstract/10.1103/... \n", "\n", " Image Foundry \\\n", "0 https://github.com/LFL-Lab/design_schema_WM1/b... SQUILL \n", "1 https://github.com/LFL-Lab/design_schema_dissi... USC Nanofab \n", "2 https://github.com/LFL-Lab/design_schema_MUNNI... SQUILL \n", "\n", " Substrate Materials Junction Style Junction Materials \n", "0 Silicon Aluminium Dolan Al-AlOx-Al \n", "1 Silicon 111 Aluminium Manhattan Al-AlOx-Al \n", "2 Silicon Aluminium Dolan Al-AlOx-Al " ] }, "execution_count": 1, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from squadds import SQuADDS_DB\n", "\n", "db = SQuADDS_DB()\n", "db.get_measured_devices()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Contribution Guidelines\n", "\n", "To add your measured device results to the SQuADDS database, follow these steps:\n", "\n", "1. **Create a GitHub Repository:**\n", " - **Use the Template Repository:** Start by [creating your repository from this template](https://github.com/LFL-Lab/design_schema_SQuADDS). This will provide the necessary structure and files.\n", " - **Naming Convention:** Rename your repository to `design_schema_DEVICENAME` or `design_schema_DEVICENAME_squadds`.\n", " - **Visibility:** Set the repository to **public**.\n", " - **README File:** Update the README with a brief description, key measured results, and any relevant links.\n", "\n", "2. **Organize Repository Contents:**\n", " - **Assets Folder:**\n", " - Add an image of the device (e.g., SEM image, design diagram).\n", " - (Optional) Include the GDS file.\n", " - **Design Folder:**\n", " - Include design-related notebooks or Python scripts.\n", " - **Simulations Folder (Optional):**\n", " - Add any simulation code.\n", "\n", "3. **Submit to HuggingFace:**\n", " - Ensure the repository structure matches the template repository.\n", " - Use either a pull request on the `measured_device_database` config or the SQuADDS API as described in the next section." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Contributing via SQuADDS API\n", "\n", "To automate the contribution process, you need to generate a [GitHub token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). This token allows secure access to your repositories and is essential for submitting your device data to the SQuADDS database.\n", "\n", "### Generate a GitHub Token\n", "\n", "1. **Go to GitHub Settings:**\n", " - Click on your profile picture in the top-right corner and select **Settings**.\n", "\n", "2. **Navigate to Developer Settings:**\n", " - Scroll down to **Developer settings** in the left sidebar and click on it.\n", "\n", "3. **Create a New Token:**\n", " - Click on **Personal access tokens**, then select **Tokens (classic)**.\n", " - Click on **Generate new token**.\n", "\n", "4. **Set the Permissions:**\n", " - Enable the following permissions:\n", " - **`repo`**: Full control of repositories (required for submitting data and making changes).\n", " - **`workflow`**: Access to workflow-related permissions.\n", "\n", " - Click **Generate token** at the bottom.\n", "\n", "5. **Copy the Token:**\n", " - **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.\n", "\n", "**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.\n", "\n", "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)" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Token already exists in .env file.\n" ] } ], "source": [ "from squadds.core.utils import set_github_token\n", "\n", "set_github_token()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Great! Now we are ready to contribute to the SQuADDS database. First, authenticate using your GitHub token by running the following code cell:" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "from squadds.database.github import (\n", " login_to_github,\n", " contribute_measured_data\n", ")\n", "\n", "# Authenticate with GitHub using your token from the .env file\n", "github = login_to_github()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Contributing Measured Data\n", "\n", "Before contributing, structure your device data using the template below:\n", "\n", "```json\n", "{\n", " \"design_code\": \"GITHUB REPOSITORY LINK\",\n", " \"contrib_info\": {\n", " \"group\": \"GROUP NAME\",\n", " \"PI\": \"PRINCIPAL INVESTIGATOR\",\n", " \"institution\": \"INSTITUTION NAME\",\n", " \"uploader\": \"YOUR NAME\",\n", " \"measured_by\": [\"RESEARCHER 1\", \"RESEARCHER 2\"],\n", " \"date_created\": \"YYYY-MM-DD\",\n", " \"name\": \"DEVICE NAME\" // A unique identifier for your device\n", " },\n", " \"measured_results\": [\n", " {\n", " \"H_params\": [\n", " // Your measured parameters go here\n", " ]\n", " }\n", " ],\n", " \"sim_results\": [\n", " \"SIMULATION_1\",\n", " \"SIMULATION_2\" // Leave empty if there are no associated simulations\n", " ],\n", " \"image\": \"IMAGE LINK FROM GITHUB\",\n", " \"paper_link\": \"PUBLICATION LINK\",\n", " \"foundry\": \"FOUNDRY NAME\",\n", " \"fabrication_recipe\": \"FABRICATION RECIPE LINK\", // Optional\n", " \"substrate\": \"Silicon\", // Optional\n", " \"materials\": \"Aluminium\", // Optional\n", " \"junction_style\": \"Dolan\", // Optional\n", " \"junction_material\": \"Al-AlOx-Al\" // Optional\n", " \"notes\": \"ADDITIONAL NOTES\" // Optional\n", "}\n", "```\n", "\n", "#### Guidelines for Consistency\n", "\n", "- **Required Fields:** Ensure the structure above is followed. If any data is not available, use `None`.\n", "- **Custom Fields:** You can add additional fields as needed, but please maintain the core structure for uniformity." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Details on Each Field\n", "\n", "1. **`design_code`**: Link to your device's GitHub repository.\n", "2. **`contrib_info`**: \n", " - **`group`**: Contributing research group.\n", " - **`PI`**: Principal Investigator.\n", " - **`institution`**: Affiliated institution.\n", " - **`uploader`**: Person uploading the data.\n", " - **`measured_by`**: Who measured the device.\n", " - **`date_created`**: Device creation date.\n", " - **`name`**: Device identifier.\n", "3. **`measured_results`**: Key measured data, formatted in JSON.\n", "4. **`sim_results`**: Associated simulations (leave blank if none).\n", "5. **`image`**: Link to device image on GitHub.\n", "6. **`paper_link`**: Link to related papers.\n", "7. **`foundry`**: Name of the fabricating foundry.\n", "8. **`fabrication_recipe`** (Optional): Link to the fabrication recipe (use [Fabublox](https://fabublox.com) if available).\n", "9. **`substrate`** (Optional): Substrate material.\n", "10. **`materials`** (Optional): Device materials.\n", "11. **`junction_style`** (Optional): Junction style (e.g., Dolan).\n", "12. **`junction_material`** (Optional): Junction material (e.g., Al-AlOx-Al).\n", "13. **`notes`** (Optional): Additional device details.\n", "\n", "--- " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Below is an example device entry (`new_device_entry`) that illustrates how to format and contribute your own data to the SQuADDS database." ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "import datetime\n", "\n", "new_device_entry = {\n", " \"design_code\": \"https://github.com/your_username/design_schema_DEVICENAME\", # Replace with your forked repo URL\n", " \"contrib_info\": {\n", " \"group\": \"Your Research Group\",\n", " \"PI\": \"Dr. Jane Smith\",\n", " \"institution\": \"Your University\",\n", " \"uploader\": \"Your Name\",\n", " \"measured_by\": [\"Researcher A\", \"Researcher B\"],\n", " \"date_created\": datetime.date.today().isoformat(), # Current date in ISO format\n", " \"name\": \"Device_XYZ\" # A unique name for your device\n", " },\n", " \"measured_results\": [\n", " {\n", " \"H_params\": [\n", " {\n", " \"qubit_1\": {\n", " \"F_res_GHz\": 6.116,\n", " \"F_01_GHz\": 4.216,\n", " \"Anharmonicity_MHz\": -153,\n", " \"punchout_shift_MHz\": 1.6672,\n", " \"Extracted_g_MHz\": 61,\n", " \"Estimated_Dispersive_shift_KHz\": 303,\n", " \"L_j_nH\": 9.686\n", " }\n", " # Add more qubits as necessary\n", " }\n", " ]\n", " }\n", " ],\n", " \"sim_results\": [],\n", " \"image\": \"https://raw.githubusercontent.com/your_username/design_schema_DEVICENAME/main/assets/device_image.png\", # Replace with the URL of your device image\n", " \"paper_link\": \"https://arxiv.org/abs/1234.5678\", # Replace with the link to your associated paper\n", " \"foundry\": \"Your Foundry Name\",\n", " \"fabrication_recipe\": \"https://fabublox.com/your_recipe\", # Replace with the link to your fabrication recipe\n", " \"substrate\": \"Silicon\",\n", " \"materials\": \"Aluminium\",\n", " \"junction_style\": \"Dolan\",\n", " \"junction_material\": \"Al-AlOx-Al\",\n", " \"notes\": \"Additional notes about the device.\"\n", "}" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now it’s time to share your device dataset with our wonderful quantum community!\n", "\n", "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!" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Forking the repository: LFL-Lab/SQuADDS_DB to NxtGenLegend's account...\n", "Repository forked successfully: https://github.com/NxtGenLegend/SQuADDS_DB\n", "Cloning repository from https://github.com/NxtGenLegend/SQuADDS_DB into ./temp_forked_repo...\n", "Checking out the main branch...\n", "Reading JSON file from ./temp_forked_repo/measured_device_database.json...\n", "Appending new entry to JSON data...\n", "Saving updated JSON data to ./temp_forked_repo/measured_device_database.json...\n", "Staging and committing changes to measured_device_database.json...\n", "Commit successful with message: Update JSON dataset with new entry - 2024-09-28 09:49:05\n", "Updated remote URL with token for authentication\n", "Pushing changes to the remote main branch...\n", "Push successful.\n", "Successfully pushed changes to the remote repository.\n", "Creating a pull request from NxtGenLegend/SQuADDS_DB:main to LFL-Lab/SQuADDS_DB:main...\n", "Pull request created successfully\n", "Pull request URL: https://github.com/LFL-Lab/SQuADDS_DB/pull/5\n" ] } ], "source": [ "pr_title=\"Adding DEVICENAME to SQuADDS_DB\"\n", "\n", "contribute_measured_data(new_device_entry, pr_title)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "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!" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## License\n", "\n", "
\n", "

This code is a part of SQuADDS

\n", "

Developed by Sadman Ahmed Shanto

\n", "

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

\n", "

© Copyright Sadman Ahmed Shanto & Eli Levenson-Falk 2023.

\n", "

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.

\n", "

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

\n", "
" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.8" } }, "nbformat": 4, "nbformat_minor": 2 }