Clean up Notebooks repository (#266)

* add checkpoints to gitignore * add qujax vqe notebook to maintained notebooks * fix markdown headings in qujax example * set navigation_with_keys to true * Start resturcturing table of contents * Restructure TOC into subsections * remove key in config file * add updated heisenberg notebook * clean up headings in comparing_simulators example * impove example on conditional gates * clean up table of contents * change tket -> TKET * remove duplicate file name * change headings in benchmarking and VQE notebooks * consistent capitalisation * TKET Backends -> Backends * fix heading in comparing simulators * change some more captialisations * TOC edit * modify some more headings * modify spam example heading * add Getting started notebook * fix reference * change heading * fix README * more fixes * Update getting started notebook * another text edit * add tket -> qiskit example * don't execute notebook * add images directory * clean up tket benchmarking example * fix QPE example * clean up QPE example * delete legacy benchamarking example * clean up notebook * clean up pytket-qujax symbolic circuits * finally fix dodgy math formatting in qujax classification example * add clean pytket-qujax heisenberg example * add clean notebooks * remove outdated info from ansatz sequencing example * fix links at the bottom of QPE notebook * delete unused Hamiltonian JSON * delete benchmarking example from config file * Remove Other section from TOC, add Algorithms and Protocols * add Contributing.md * updates notebook titles * Ensure VQE notebooks are listed next to one another * Fix qujax qaoa and VQE notebooks * fix qujax classification example * remove uneeded lines from CONTRIBUTING section --------- Co-authored-by: isobelhooper <[email protected]>
CQCL · Nov 13, 2023 · 378bc85 · 378bc85
1 parent 4948899
commit 378bc85
Show file tree

Hide file tree

Showing 42 changed files with 429 additions and 1,427 deletions.
diff --git a/examples/README.md → examples/CONTRIBUTING.md b/examples/README.md → examples/CONTRIBUTING.md
@@ -1,9 +1,4 @@
-# pytket examples
-
-See the pytket examples built with jupyterbook [here](https://tket.quantinuum.com/examples).
-
-
-## Notes for developers
+# Contributing new notebooks
 
 The sources for all these notebooks are the Python scripts in the `python`
 directory. The notebook files are generated from them with the `gen-nb` script

diff --git a/examples/Forest_portability_example.ipynb b/examples/Forest_portability_example.ipynb
diff --git a/examples/Getting_started.ipynb b/examples/Getting_started.ipynb
@@ -0,0 +1,237 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "f5f6b50c-9dbc-4a85-afe2-1b1ff717d091",
+   "metadata": {},
+   "source": [
+    "# pytket examples"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e6d90a8a-4303-4d6d-9e51-ca8fcec0a2a5",
+   "metadata": {},
+   "source": [
+    "## Building a circuit with the `Circuit` class\n",
+    "\n",
+    "\n",
+    "You can create a circuit by creating an instance of the `Circuit` class and adding gates manually."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "32a81360-0002-4c82-9a9e-a0f90851f34b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pytket import Circuit\n",
+    "\n",
+    "ghz_circ = Circuit(3)\n",
+    "ghz_circ.H(0)\n",
+    "ghz_circ.CX(0, 1)\n",
+    "ghz_circ.CX(1, 2)\n",
+    "ghz_circ.add_barrier(ghz_circ.qubits)\n",
+    "ghz_circ.measure_all()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "147c590e-89e5-4e4e-9fb9-d10ac5689fec",
+   "metadata": {},
+   "source": [
+    "Now let's draw a nice picture of the circuit with the circuit renderer"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "92df4f4d-487c-4c56-a072-9a1d2e3c07fc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pytket.circuit.display import render_circuit_jupyter\n",
+    "\n",
+    "render_circuit_jupyter(ghz_circ)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bdec557e",
+   "metadata": {},
+   "source": [
+    "See also the [Circuit construction](https://tket.quantinuum.com/user-manual/manual_circuit.html) section of the user manual."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "820b0215-4ca8-450c-bc1a-62bed65e2740",
+   "metadata": {},
+   "source": [
+    "## Build a `Circuit` from a QASM file"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7c9089dc-cf4d-4efd-b90e-5485218f90a5",
+   "metadata": {},
+   "source": [
+    "Alternatively we can import a circuit from a QASM file using [pytket.qasm](https://tket.quantinuum.com/api-docs/qasm.html). There are also functions for generating a circuit from a QASM string or exporting to a qasm file.\n",
+    "\n",
+    "\n",
+    "Note that its also possible to import a circuit from quipper using [pytket.quipper](https://tket.quantinuum.com/api-docs/quipper.html) module."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1bf32877-f5e0-4b09-a12d-7aa8fa7d5d20",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pytket.qasm import circuit_from_qasm\n",
+    "\n",
+    "w_state_circ = circuit_from_qasm(\"qasm/W-state.qasm\")\n",
+    "render_circuit_jupyter(w_state_circ)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ef0c31c5-9203-475b-abe1-5a0b53dc5e87",
+   "metadata": {},
+   "source": [
+    "## Import a circuit from qiskit (or other SDK)\n",
+    "\n",
+    "Its possible to generate a circuit directly from a qiskit `QuantumCircuit` using the [qiskit_to_tk](https://tket.quantinuum.com/extensions/pytket-qiskit/api.html#pytket.extensions.qiskit.tk_to_qiskit) function."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "23e753f2-3f6e-4a3d-a2e7-ece869561249",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qiskit import QuantumCircuit\n",
+    "\n",
+    "qiskit_circ = QuantumCircuit(3)\n",
+    "qiskit_circ.h(range(3))\n",
+    "qiskit_circ.ccx(2, 1 ,0)\n",
+    "qiskit_circ.cx(0, 1)\n",
+    "print(qiskit_circ)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5357e5d4-e0d8-4a59-9fe8-426067f411e0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pytket.extensions.qiskit import qiskit_to_tk\n",
+    "\n",
+    "tket_circ = qiskit_to_tk(qiskit_circ)\n",
+    "\n",
+    "render_circuit_jupyter(tket_circ)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7688630f-89e2-48c7-9d1e-53a9dedf088a",
+   "metadata": {},
+   "source": [
+    "Note that pytket and qiskit use opposite qubit ordering conventions. So circuits which look identical may correspond to different unitary operations."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1eee94cb-d7a2-469d-9c48-747a6e9271a1",
+   "metadata": {},
+   "source": [
+    "Circuit conversion functions are also available for [pytket-cirq](https://tket.quantinuum.com/extensions/pytket-cirq/), [pytket-pennylane](https://tket.quantinuum.com/extensions/pytket-pennylane/), [pytket-braket](https://tket.quantinuum.com/extensions/pytket-braket/) and more."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ae85113b-5f8c-43b0-93c8-dc89002deece",
+   "metadata": {},
+   "source": [
+    "## Using Backends"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f2684ec5-30d9-4003-ad6a-624ec20bd268",
+   "metadata": {},
+   "source": [
+    "In pytket a `Backend` represents an interface to a quantum device or simulator.\n",
+    "\n",
+    "We will show a simple example of running the `ghz_circ` defined above on the `AerBackend` simulator."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "42f4e1f6-2281-4780-bb11-7132c4be5313",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "render_circuit_jupyter(ghz_circ)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "868189e3-197c-427b-843e-6a991d1cfec9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pytket.extensions.qiskit import AerBackend\n",
+    "\n",
+    "backend = AerBackend()\n",
+    "result = backend.run_circuit(ghz_circ)\n",
+    "print(result.get_counts())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "eadff4bc-a1d3-42d0-bc0e-6bf515f40715",
+   "metadata": {},
+   "source": [
+    "The `AerBackend` simulator is highly idealised having a broad gateset, and no restrictive connectivity or device noise.\n",
+    "\n",
+    "The Hadamard and CX gate are supported operations of the simulator so we can run the GHZ circuit without changing any of the operations. For more realistic cases a compiler will have to solve for the limited gateset of the target backend as well as other backend requirements."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3321855a-683b-4848-81bd-1d238626f45b",
+   "metadata": {},
+   "source": [
+    "See the [Running on Backends](https://tket.quantinuum.com/user-manual/manual_backend.html) section of the user manual and the [backends example notebook](https://tket.quantinuum.com/examples/backends_example.html) for more."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.10.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/examples/IBMTokyoArc.png b/examples/IBMTokyoArc.png
diff --git a/examples/IBMqx5Arc.png b/examples/IBMqx5Arc.png
diff --git a/examples/_config.yml b/examples/_config.yml
@@ -12,14 +12,14 @@ sphinx:
 
 execute:
   # Exclude some examples from execution (these are still deployed as html pages)
-  exclude_patterns: [".venv/*", "Forest_portability_example.ipynb", "backends_example.ipynb", "qiskit_integration.ipynb", "comparing_simulators.ipynb", "expectation_value_example.ipynb", "pytket-qujax_heisenberg_vqe.ipynb", "spam_example.ipynb", "tket_benchmarking.ipynb", "entanglement_swapping.ipynb", "pytket-qujax-classification.ipynb"]
+  exclude_patterns: [".venv/*", "Forest_portability_example.ipynb", "backends_example.ipynb", "qiskit_integration.ipynb", "comparing_simulators.ipynb", "expectation_value_example.ipynb", "pytket-qujax_heisenberg_vqe.ipynb", "spam_example.ipynb", "entanglement_swapping.ipynb", "pytket-qujax-classification.ipynb"]
   timeout: 90    # The maximum time (in seconds) each notebook cell is allowed to run.
 
 # Information about where the book exists on the web
 repository:
   url: https://github.com/CQCL/pytket  # Notebook files are located in pytket/examples
   path_to_book: docs  # Optional path to your book, relative to the repository root
-  branch: master  # Which branch of the repository should be used when creating links (optional)
+  branch: main  # Which branch of the repository should be used when creating links (optional)
 
 # Add GitHub buttons to your book
 # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository

diff --git a/examples/_toc.yml b/examples/_toc.yml
@@ -2,30 +2,38 @@
 # Learn more at https://jupyterbook.org/customize/toc.html
 
 format: jb-book
-root: README
-chapters:
-- file: ansatz_sequence_example
-- file: circuit_analysis_example
-- file: circuit_generation_example
-- file: compilation_example
-- file: conditional_gate_example
-- file: contextual_optimization
-- file: creating_backends
-- file: measurement_reduction_example
-- file: mapping_example
-- file: symbolics_example
-- file: ucc_vqe
-- file: pytket-qujax_qaoa
-- file: phase_estimation
-- file: benchmarking/README
-# The following notebooks are not executed
-- file: backends_example
-- file: comparing_simulators
-- file: qiskit_integration
-- file: Forest_portability_example
-- file: pytket-qujax-classification
-- file: expectation_value_example
-- file: entanglement_swapping
-- file: pytket-qujax_heisenberg_vqe
-- file: spam_example
-- file: tket_benchmarking
+root: Getting_started
+parts:
+  - caption: Building Quantum Circuits
+    chapters:
+    - file: circuit_generation_example
+    - file: circuit_analysis_example
+    - file: conditional_gate_example
+  - caption: Backends
+    chapters:
+    - file: backends_example
+    - file: comparing_simulators
+    - file: Forest_portability_example
+    - file: creating_backends
+    - file: qiskit_integration
+  - caption: Circuit Compilation
+    chapters:
+    - file: compilation_example
+    - file: symbolics_example
+    - file: mapping_example
+    - file: ansatz_sequence_example
+    - file: measurement_reduction_example
+    - file: contextual_optimization
+  - caption: Algorithms and Protocols
+    chapters:
+    - file: phase_estimation
+    - file: ucc_vqe
+    - file: pytket-qujax_heisenberg_vqe
+    - file: pytket-qujax-classification
+    - file: pytket-qujax_qaoa
+    - file: expectation_value_example
+    - file: entanglement_swapping
+    - file: spam_example
+  - caption: Contributing
+    chapters:
+    - file: CONTRIBUTING