Adding a QuickStart guide. (#43)

Author: Yoric

.github/workflows/test.yml

@@ -35,6 +35,7 @@ jobs:
     - name: Run tests
       run: |
         hatch -v run test
+        hatch -v run test_readme
     - name: Upload coverage data
       uses: actions/upload-artifact@v4
       with:

README.md

@@ -42,7 +42,40 @@ $ pip install quantum-evolution-kernel
 $ pipx install quantum-evolution-kernel
 ```
 
-## Usage
+## QuickStart
+
+```python
+# Load a dataset
+import torch_geometric.datasets as pyg_dataset
+og_ptcfm = pyg_dataset.TUDataset(root="dataset", name="PTC_FM")
+
+# Setup a quantum feature extractor for this dataset.
+# In this example, we'll use QutipExtractor, to emulate a Quantum Device on our machine.
+import qek.data.graphs as qek_graphs
+import qek.data.extractors as qek_extractors
+extractor = qek_extractors.QutipExtractor(compiler=qek_graphs.PTCFMCompiler())
+
+# Add the graphs, compile them and look at the results.
+extractor.add_graphs(graphs=og_ptcfm)
+extractor.compile()
+processed_dataset = extractor.run().processed_data
+
+# Prepare a machine learning pipeline with Scikit Learn.
+from sklearn.model_selection import train_test_split
+from sklearn.svm import SVC
+
+X = [data for data in processed_dataset]  # Features
+y = [data.target for data in processed_dataset]  # Targets
+X_train, X_test, y_train, y_test = train_test_split(X, y, stratify = y, test_size=0.2, random_state=42)
+
+# Train a kernel
+from qek.kernel import QuantumEvolutionKernel as QEK
+kernel = QEK(mu=0.5)
+model = SVC(kernel=kernel, random_state=42)
+model.fit(X_train, y_train)
+```
+
+## Documentation
 
 We have a two parts tutorial:
 

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

@@ -122,8 +122,8 @@
     "#\n",
     "# On our test computer, the practical limit is around 10 qubits.\n",
     "max_qubits = 5\n",
-    "processed_dataset = extractor.run(max_qubits=max_qubits)\n",
-    "display(\"Extracted features from %s samples\"% (len(processed_dataset.states), ))"
+    "processed_dataset = extractor.run(max_qubits=max_qubits).processed_data\n",
+    "display(\"Extracted features from %s samples\"% (len(processed_dataset), ))"
    ]
   },
   {
@@ -173,12 +173,13 @@
     "    display(\"Compiled %s sequences\" % (len(compiled), ))\n",
     "\n",
     "    # Launch the execution.\n",
-    "    processed_dataset = extractor.run()\n",
+    "    extracted = extractor.run()\n",
     "    display(\"Work enqueued with ids %s\" % (extractor.batch_ids, ))\n",
     "\n",
     "    # ...and wait for the results.\n",
-    "    await processed_dataset\n",
-    "    display(\"Extracted features from %s samples\"% (len(processed_dataset.states), ))"
+    "    await extracted\n",
+    "    processed_data = extracted.processed_data\n",
+    "    display(\"Extracted features from %s samples\"% (len(processed_data), ))"
    ]
   },
   {

pyproject.toml

@@ -62,6 +62,7 @@ dependencies = [
   "pytest-cov",
   "pytest-xdist",
   "pytest-asyncio",
+  "pytest-markdown-docs",
   "nbconvert",
   "ipykernel",
   "pre-commit",
@@ -72,11 +73,12 @@ dependencies = [
 ]
 
 [tool.hatch.envs.default.scripts]
-test = "pytest -n auto --cov-report=term-missing --cov-config=pyproject.toml --cov=qek --cov=tests --ignore=./tests/test_examples.py --ignore=./tests/test_notebooks.py {args}"
+test = "pytest -n auto --cov-report=term-missing --cov-config=pyproject.toml --cov=qek --cov=tests --markdown-docs {args}"
+test_readme = "pytest --markdown-docs README.md"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = """-vvv --cov-report=term-missing --cov-config=pyproject.toml --cov=qek --cov=tests"""
+addopts = """-vvv --cov-report=term-missing --cov-config=pyproject.toml --cov=qek --cov=tests --markdown-docs"""
 xfail_strict = true
 filterwarnings = [
   "ignore:Call to deprecated create function FieldDescriptor",