diff --git a/docs/source/developer/index.rst b/docs/source/developer/index.rst new file mode 100644 index 00000000..45f6f894 --- /dev/null +++ b/docs/source/developer/index.rst @@ -0,0 +1,36 @@ +.. SQuADDS + Copyright (C) 2023, Sadman Ahmed Shanto & Eli Levenson-Falk + +.. _developers: + +.. note:: + + Everyone is welcome to contribute to SQuADDS. Please see review the following section for more information or contact us! + + +Contribution Items +================== + +| **Bug Reports** - Please report any bugs you find in the code or documentation by opening an issue on GitHub. +| **Feature Requests** - If you have an idea for a new feature, please open an issue on GitHub. +| **Pull Requests** - We welcome pull requests from the community. If you submit a pull request, please be patient as we review your work. If you have any questions about contributing, please contact us! +| **Documentation** - We welcome contributions to the documentation. If you find any typos or errors, please open an issue on GitHub. +| **Implementation of Next Release** - If you would like to help in implementing the next version of SQuADDS, please look at `In the Works`_ + + +Developers +=========== + +| `Sadman Ahmed Shanto `_ (University of Southern California) + + +.. _developers-contributors: + +Contributors +============ + + +| **Eli Levenson-Falk** (University of Southern California) - Eternal Guidance Provider 🙏🏽 +| **Andre Kuo** (University of Southern California) - Code contributor +| **Clark Miyamoto** (New York University) - Code contributor +| **Madison Howard** (California Institute of Tech) - Bug Hunter \ No newline at end of file diff --git a/docs/source/explanations/index.rst b/docs/source/explanations/index.rst deleted file mode 100644 index 759e5622..00000000 --- a/docs/source/explanations/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -Explanations -============ - -List of Topics --------------- - -1. **Topic Name 1** - Brief description of the topic. -2. **Topic Name 2** - Another brief description. - -... and so on for each topic. diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 0d2b5393..9ed9c0bc 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -7,22 +7,36 @@ Getting Started with SQuADDS Installation ------------ -1. **Install Qiskit-Metal**: - See `here `_. +SQuADDS can be installed using pip. -2. **Clone Repository**: +.. code-block:: bash + + pip install SQuADDS + +Alternatively, you can install SQuADDS from source. + +1. **Clone Repository**: Navigate to your chosen directory and clone the repository. .. code-block:: bash - cd + cd git clone https://github.com/shanto268/SQuADDS -3. **Install Dependencies**: +2. **Install Dependencies**: Activate your Qiskit Metal conda environment and install dependencies. .. code-block:: bash - conda activate + conda activate cd SQuADDS pip install . + + +FAQ +--- + +**Q:** Placeholder? + +**A:** Placeholder. + diff --git a/docs/source/how_to/index.rst b/docs/source/how_to/index.rst deleted file mode 100644 index 4509febe..00000000 --- a/docs/source/how_to/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -How-to Guides -============= - -List of Guides --------------- - -1. **Guide Name 1** - Brief description of what the guide covers. -2. **Guide Name 2** - Another brief description. - diff --git a/docs/source/index.rst b/docs/source/index.rst index 8e43c725..d9a707c4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,8 +12,7 @@ Overview SQuADDS: a Superconducting Qubit And Device Design and Simulation database --------------------------------------------------------------------------------------------------- -This open-source platform offers a rich collection of quantum device designs, primed for personalization. Seamlessly integrated with Qiskit Metal, each design is simulation-ready with advanced electromagnetic solvers. We ensure a dependable simulation process, with many designs backed by real-world testing. Navigate and adapt designs effortlessly through our intuitive interface, paving the way for researchers to innovate new device categories. - +SQuADDS is an open-source platform aimed at speeding up the design loop in the creation of superconducting quantum hardware. This tool bridges the gap between theoretical design and practical implementation, providing researchers and engineers with a well-characterized starting point for the development of device. SQuADDS enables rapid generation of "best-guess" and validated "pre-simulated" designs, underpinned by a vast repository of experimentally validated design and simulation parameters. SQuADDS aims to lowers the barrier to entry for research groups seeking to make a new class of devices by providing them a well-characterized starting point from which to refine their designs. .. toctree:: :hidden: @@ -21,16 +20,31 @@ This open-source platform offers a rich collection of quantum device designs, pr Documentation Home Getting Started Tutorials - How-to Guides API Reference - Explanations - Release Notes + Release Logs + Developer Notes + References GitHub +Citation +-------- + +If you use SQuADDS in your research, please support its continued development and maintenance. Use of scqubits in research publications is appropriately acknowledged by citing: + +.. code-block:: latex + + @article{SQuADDS, + title={SQuADDS: A validated design database and simulation workflow for superconducting qubit design}, + author={Sadman Ahmed Shanto, Andre Kuo, Clark Miyamoto, Haimeng Zhang, Vivek Maurya, Evangelos Vlachos, Malida Hecht, Chung Wa Shum and Eli Levenson-Falk}, + journal={arXiv preprint arXiv:}, + year={2023} + } + + Indices and tables ================== * :ref:`genindex` * :ref:`modindex` -* :ref:`search` +* :ref:`search` \ No newline at end of file diff --git a/docs/source/references/index.rst b/docs/source/references/index.rst new file mode 100644 index 00000000..cf6b04ba --- /dev/null +++ b/docs/source/references/index.rst @@ -0,0 +1,9 @@ +Explanations +============ + +List of Topics +-------------- + +1. **HuggingFace** - Brief description of the topic. +2. **** - Another brief description. + diff --git a/docs/source/release_notes.rst b/docs/source/release_notes.rst index 77b96de1..44795c06 100644 --- a/docs/source/release_notes.rst +++ b/docs/source/release_notes.rst @@ -1,10 +1,21 @@ Release Notes ============= -Version 0.0.1 (2023-09-06) +Version 0.1.0 (2023-12-20) -------------------- * **MVP Version** - - Feature 1 description. - - Feature 2 description. + + - Database hosted on `HuggingFac`_ + + - Pre-simulated data on TransmonCross, Cavity with Claw and Couplers only. + + - Closest pre-simulated design and interpolated design retrieval implemented + + - Interpolation logic based on our `paper`_ + + - Tutorials on basic usage, contribution, and simulation added + + - pypi package created + diff --git a/tutorials/Tutorial-1_getting_started_with_SQuADDS.ipynb b/tutorials/Tutorial-1_getting_started_with_SQuADDS.ipynb index b2c0a9b5..968cf963 100644 --- a/tutorials/Tutorial-1_getting_started_with_SQuADDS.ipynb +++ b/tutorials/Tutorial-1_getting_started_with_SQuADDS.ipynb @@ -71,6 +71,111 @@ "set_huggingface_api_key()" ] }, + { + "cell_type": "code", + "execution_count": 15, + "metadata": {}, + "outputs": [], + "source": [ + "from datasets import get_dataset_config_names\n", + "from datasets import load_dataset\n", + "\n", + "configs = get_dataset_config_names(\"SQuADDS/SQuADDS_DB\")" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['qubit-TransmonCross-cap_matrix',\n", + " 'cavity_claw-RouterMeander-eigenmode',\n", + " 'coupler-NCap-cap_matrix']" + ] + }, + "execution_count": 13, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "configs" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "DatasetDict({\n", + " train: Dataset({\n", + " features: ['notes', 'design', 'contributor', 'sim_results', 'sim_options'],\n", + " num_rows: 1934\n", + " })\n", + "})" + ] + }, + "execution_count": 22, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "qubit_data = load_dataset(\"SQuADDS/SQuADDS_DB\", configs[0])\n", + "qubit_data" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "notes has keys:\n", + "design has keys:\n", + "\tdesign_options\n", + "\tdesign_tool\n", + "contributor has keys:\n", + "\tPI\n", + "\tdate_created\n", + "\tgroup\n", + "\tinstitution\n", + "\tuploader\n", + "sim_results has keys:\n", + "\tclaw_to_claw\n", + "\tclaw_to_ground\n", + "\tcross_to_claw\n", + "\tcross_to_cross\n", + "\tcross_to_ground\n", + "\tground_to_ground\n", + "\tunits\n", + "sim_options has keys:\n", + "\trenderer_options\n", + "\tsetup\n", + "\tsimulator\n" + ] + } + ], + "source": [ + "# print all the nested keys of qubit_data[\"train\"][0]\n", + "for key in qubit_data[\"train\"][0].keys():\n", + " try:\n", + " print(f\"{key} has keys:\")\n", + " for k in qubit_data[\"train\"][0][key].keys():\n", + " print(f\"\\t{k}\")\n", + " except:\n", + " pass" + ] + }, { "cell_type": "code", "execution_count": null, diff --git a/tutorials/Tutorial-2_Contributing_to_SQuADDS.ipynb b/tutorials/Tutorial-2_Contributing_to_SQuADDS.ipynb index c745008f..a96a2a5e 100644 --- a/tutorials/Tutorial-2_Contributing_to_SQuADDS.ipynb +++ b/tutorials/Tutorial-2_Contributing_to_SQuADDS.ipynb @@ -116,69 +116,20 @@ "- Adding to SQuADDS_DB" ] }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Contributing to an existing database node " - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Hugging Face Native Solution:\n", - "\n", - "**To append to an existing configuration:**\n", - "\n", - "1. Modify the existing `YourDatasetConfig` if needed.\n", - "2. Update the `_split_generators` and `_generate_examples` methods to include your additions.\n", - "3. Test your changes locally to ensure the dataset loads correctly.\n", - "4. Update the documentation (`README.md`) to include your new configuration.\n", - "5. Create a pull request with your changes.\n", - "\n", - "### SQuADDS API:" - ] - }, { "cell_type": "code", - "execution_count": 6, + "execution_count": null, "metadata": {}, "outputs": [], - "source": [ - "import glob" - ] + "source": [] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Creating a new database node \n", + "---\n", "\n", - "### HuggingFace Native Solution:\n", - "\n", - "One can use workflows developed by HuggingFace to create a new **configuration** to the SQuADDS_DB Dataset. The following is a list of steps to follow: \n", - "\n", - "**To add a new configuration:**\n", - "\n", - "1. Add a new `YourDatasetConfig` to `BUILDER_CONFIGS` with a unique name, version, and description.\n", - "2. Update `_URLs` with the download URL for the new configuration.\n", - "3. Modify `_split_generators` and `_generate_examples` methods to handle the new configuration.\n", - "4. Test your changes locally to ensure the dataset loads correctly.\n", - "5. Update the documentation (`README.md`) to include your new configuration.\n", - "6. Create a pull request with your changes.\n", - "\n", - "\n", - "### SQuADDS API:\n", - "\n", - "You can also use the SQuADDS API to create a new configuration. The following cells will walk you through the process." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "#### Step 1: Standardizing your data\n", + "## Data Processing:\n", "\n", "We want the data to be in a `json` format with **AT LEAST** to have the following fields. You can add as many more supplementary fields as you want.\n", "\n", @@ -209,9 +160,85 @@ "```\n", "\n", "If all the `sim_results` has the same units you can just use a `\"units\":units` field instead of repeating the unit for each result.\n", - "\n" + "\n", + "---\n" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Adding to an Existing Configuration " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "1. **Clone/Fork the Repository**: If you have not already forked or cloned the repository, do so.\n", + "\n", + "2. **Create or Checkout a Branch**: If adding new data, it might be best to do it on a new branch:\n", + "\n", + " ```sh\n", + " git checkout -b add_to_configuration\n", + " ```\n", + "\n", + "3. **Modify the Configuration**: Add or modify the data files as necessary for the configuration. Make sure to follow any guidelines provided by the dataset maintainers for the specific structure and format required.\n", + "\n", + "4. **Commit and Push Your Changes**: Commit the new data and push it to your fork:\n", + "\n", + " ```sh\n", + " git add .\n", + " git commit -m \"Add new data to configuration Y\"\n", + " git push origin add_to_configuration\n", + " ```\n", + "\n", + "5. **Pull Request**: Create a pull request against the original repository." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Contributing a New Configuration \n", + "\n", + "1. **Fork the Dataset Repository**: On the Hugging Face Hub, fork the dataset repository you want to contribute to.\n", + "\n", + "2. **Clone Your Fork Locally**: Clone the forked repository to your local machine using the following command:\n", + "\n", + " ```sh\n", + " git clone https://huggingface.co/datasets/YOUR_USERNAME/DATASET_NAME\n", + " ```\n", + "\n", + "3. **Create a New Branch**: It's a good practice to create a new branch for your configuration contribution:\n", + "\n", + " ```sh\n", + " git checkout -b new_configuration\n", + " ```\n", + "\n", + "4. **Add Your Configuration**: Depending on the dataset's structure, this might involve adding new files or modifying existing ones. If the dataset uses the `datasets` library's builder configurations, you will need to modify the Python script that defines the configurations.\n", + "\n", + "5. **Commit Your Changes**: Commit the changes with a clear commit message:\n", + "\n", + " ```sh\n", + " git add .\n", + " git commit -m \"Add new configuration for circuit element X\"\n", + " ```\n", + "\n", + "6. **Push to Your Fork**: Push your new branch to your fork on the Hugging Face Hub:\n", + "\n", + " ```sh\n", + " git push origin new_configuration\n", + " ```\n", + "\n", + "7. **Create a Pull Request**: Go to the Hugging Face Hub, navigate to your fork, and create a pull request for your new branch. The pull request will be reviewed by the dataset maintainers." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [] + }, { "cell_type": "markdown", "metadata": {},