[Doc][CI] Render the tutorial within the generated documentation (#102)

Author: Yoric

.github/workflows/publish.yml

@@ -67,6 +67,9 @@ jobs:
         - name: Install Hatch
           run: |
             pip install hatch
+        - name: Build Docs
+          run: |
+            cp examples/*.ipynb docs/
         - name: Deploy docs
           run: |
             git config user.name "GitHub Actions"

.gitignore

@@ -50,3 +50,6 @@ dataset/
 
 # Mkdocs
 site/
+docs/*.ipynb
+docs/ptcfm_processed_dataset.json
+docs/saved_data.json

README.md

@@ -80,8 +80,8 @@ model.fit(X_train, y_train)
 
 We have a two parts tutorial:
 
-1. [Using a Quantum Device to extract machine-learning features](https://github.com/pasqal-io/quantum-evolution-kernel/blob/main/examples/tutorial%201%20-%20Using%20a%20Quantum%20Device%20to%20Extract%20Machine-Learning%20Features.ipynb);
-2. [Machine Learning with the Quantum Evolution Kernel](https://github.com/pasqal-io/quantum-evolution-kernel/blob/main/examples/tutorial%202%20-%20Machine-Learning%20with%20the%20Quantum%20EvolutionKernel.ipynb)
+1. [Using a Quantum Device to extract machine-learning features](https://pasqal-io.github.io/quantum-evolution-kernel/latest/tutorial%201%20-%20Using%20a%20Quantum%20Device%20to%20Extract%20Machine-Learning%20Features);
+2. [Machine Learning with the Quantum Evolution Kernel](https://github.com/pasqal-io/quantum-evolution-kernel/blob/main/examples/tutorial%202%20-%20Machine-Learning%20with%20the%20Quantum%20EvolutionKernel/)
 
 See also the [full API documentation](https://pasqal-io.github.io/quantum-evolution-kernel/latest/).
 

docs/index.md

@@ -7,6 +7,13 @@ The core of the library is focused on the development of a classification algori
 
 Users setting their first steps into quantum computing will learn how to implement the core algorithm in a few simple steps and run it using the Pasqal Neutral Atom QPU. More experienced users will find this library to provide the right environment to explore new ideas - both in terms of methodologies and data domain - while always interacting with a simple and intuitive QPU interface.
 
+## Getting started
+
+We provide several tutorials:
+
+- [tutorial 1 - Using a Quantum Device to Extract Machine-Learning Features](tutorial 1 - Using a Quantum Device to Extract Machine-Learning Features.ipynb)
+- [tutorial 2 - Machine-Learning with the Quantum EvolutionKernel](tutorial 2 - Machine-Learning with the Quantum EvolutionKernel.ipynb)
+
 
 ## Getting in touch
 

docs/tutorials.md

@@ -28,6 +28,27 @@
     "As in any machine learning task, we first need to load and prepare data. QEK can work with many types of graphs, including molecular graphs. For this tutorial, we will use the PTC-FM dataset, which contains such molecular graphs, labeled with their toxicity."
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "ignore_warnings"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# Ignore warnings for this tutorial.\n",
+    "import logging\n",
+    "import os\n",
+    "import sys\n",
+    "\n",
+    "logger = logging.getLogger()\n",
+    "logger.disabled = True\n",
+    "\n",
+    "sys.stderr = open(os.devnull, 'w')"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/tutorial 1 - Using a Quantum Device to Extract Machine-Learning Features.ipynb

@@ -29,6 +29,25 @@
     "As in any machine learning task, we first need to load and prepare data. QEK can work with many types of graphs, including molecular graphs. For this tutorial, we will use the PTC-FM dataset, which contains such molecular graphs."
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "ignore_warnings"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# Ignore warnings for this tutorial.\n",
+    "import logging\n",
+    "import sys\n",
+    "\n",
+    "logger = logging.getLogger()\n",
+    "logger.disabled = True\n",
+    "sys.stderr.close()"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/tutorial 1a - Using a Quantum Device to Extract Machine-Learning Features - low-level.ipynb

@@ -53,6 +53,27 @@
     "\n"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "ignore_warnings"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# Ignore warnings for this tutorial.\n",
+    "import logging\n",
+    "import os\n",
+    "import sys\n",
+    "\n",
+    "logger = logging.getLogger()\n",
+    "logger.disabled = True\n",
+    "\n",
+    "sys.stderr = open(os.devnull, 'w')"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/tutorial 1b - Training SVM QEK - low-level - generic dataset.ipynb

@@ -50,10 +50,7 @@
    "id": "05e294f5",
    "metadata": {},
    "source": [
-    "We begin by loading a dataset that contains graph-structured data. Each data point is represented as a processed object with features (in this example, the quantum distribution excitation for a molecule) and a target value (in this example, the toxicity of the molecule). We will split the data into training and testing sets for model evaluation.\n",
-    "\n",
-    "- Each processed data point has a _state_dict_: This dictionary represents an approximation of the quantum state of the device for this graph after completion of the algorithm. From the state dictionary, we derive as machine-learning feature the _distribution of excitation_. We'll use these in the next step to define our kernel.\n",
-    "    "
+    "We begin by loading a dataset that contains graph-structured data. Each data point is represented as a processed object with features (in this example, the quantum distribution excitation for a molecule) and a target value (in this example, the toxicity of the molecule). We will split the data into training and testing sets for model evaluation.    "
    ]
   },
   {
@@ -80,8 +77,8 @@
     "from sklearn.model_selection import train_test_split\n",
     "\n",
     "# Prepare features (X) and targets (y)\n",
-    "X = [data for data in processed_dataset]  \n",
-    "y = [data.target for data in processed_dataset] \n",
+    "X = [data for data in processed_dataset] # Quantum distribution excitation.\n",
+    "y = [data.target for data in processed_dataset] # Toxicity.\n",
     "\n",
     "# Split data into training and testing sets\n",
     "X_train, X_test, y_train, y_test = train_test_split(X, y, stratify = y, test_size=0.2, random_state=42)"

examples/tutorial 2 - Machine-Learning with the Quantum EvolutionKernel.ipynb

@@ -7,7 +7,11 @@ nav:
   - Getting started:
     - Installation: installation.md
     - Usage: usage.md
-    - Tutorials: tutorials.md
+  - Tutorials:
+    - "Tutorial 1 - Using a Quantum Device to Extract Machine-Learning Features": "tutorial 1 - Using a Quantum Device to Extract Machine-Learning Features.ipynb"
+    - "(low-level variant) Tutorial 1a - Using a Quantum Device to Extract Machine-Learning Features": "tutorial 1a - Using a Quantum Device to Extract Machine-Learning Features - low-level.ipynb"
+    - "Tutorial 2 - Machine-learning with the Quantum Evolution Kernel": "tutorial 2 - Machine-Learning with the Quantum EvolutionKernel.ipynb"
+    - "(variant) Tutorial 2b - Training SVM QEK": "tutorial 1b - Training SVM QEK - low-level - generic dataset.ipynb"
   - Reference: $api/qek.***
   - Open-source:
     - Licence (MIT-Derived): LICENSE.md
@@ -53,6 +57,12 @@ markdown_extensions:
 plugins:
 - search
 - section-index
+- mkdocs-jupyter:
+    include: ["*.ipynb"]
+    execute: True
+    remove_tag_config:
+        remove_input_tags:
+              - ignore_warnings
 - markdown-exec
 - mkapi
 - mkdocstrings: