Add a full-featured serializer from a qiskit.QuantumCircuit to a `q…

…uantum-viz.js` JSON (#44)

.gitignore

@@ -76,6 +76,7 @@ web_modules/
 # dotenv environment variables file
 .env
 .env.test
+.*[v]env/
 
 # parcel-bundler cache (https://parceljs.org/)
 .cache

quantum-viz/README.md

@@ -48,6 +48,39 @@ widget # Display the widget
 
 ![quantum-viz example](https://user-images.githubusercontent.com/4041805/137230540-b523dc76-29c7-48e2-baa3-34d4ee0a17a1.PNG)
 
+## Qiskit Integration
+
+By installing the optional `[qiskit]` dependency, you can leverage Qiskit's `QuantumCircuit` APIs
+to define the circuit and render it using the `Viewer` widget on Jupyter, for example:
+
+```python
+from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
+from quantum_viz import Viewer
+
+qr = QuantumRegister(3, 'q')
+anc = QuantumRegister(1, 'ancilla')
+cr = ClassicalRegister(3, 'c')
+qc = QuantumCircuit(qr, anc, cr)
+
+
+qc.h(qr[0:3])
+qc.x(anc[0])
+qc.h(anc[0])
+qc.cx(qr[0:3], anc[0])
+qc.h(qr[0:3])
+qc.barrier(qr)
+qc.measure(qr, cr)
+
+Viewer(qc)
+```
+
+Optionally, you can also import the `display` method from `quantum_viz.utils` to render the circuit on a new browser window:
+
+```python
+from quantum_viz.utils import display
+display(qc)
+```
+
 ## Contributing
 
 Check out our [contributing guidelines](./CONTRIBUTING.md) to find out how you can contribute to quantum-viz.

quantum-viz/examples/Qiskit.ipynb

@@ -0,0 +1,100 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Display a Qiskit circuit\n",
+    "\n",
+    "This sample shows how to visualizes a circuit built using Qiskit using the Viewer widget.\n",
+    "\n",
+    "First, create any Qiskit circuit:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit\n",
+    "\n",
+    "qr = QuantumRegister(3, 'q')\n",
+    "anc = QuantumRegister(1, 'ancilla')\n",
+    "cr = ClassicalRegister(3, 'c')\n",
+    "qc = QuantumCircuit(qr, anc, cr)\n",
+    "\n",
+    "\n",
+    "qc.h(qr[0:3])\n",
+    "qc.x(anc[0])\n",
+    "qc.h(anc[0])\n",
+    "qc.cx(qr[0:3], anc[0])\n",
+    "qc.h(qr[0:3])\n",
+    "qc.barrier(qr)\n",
+    "qc.measure(qr, cr)\n",
+    "\n",
+    "qc.draw()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Then use the `Viewer` to render the circuit on Jupyter:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from quantum_viz import Viewer\n",
+    "\n",
+    "Viewer(qc)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Optionally, you can import the `display` method to render the circuit on a new browser window:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from quantum_viz.utils import display\n",
+    "\n",
+    "display(qc)"
+   ]
+  }
+ ],
+ "metadata": {
+  "interpreter": {
+   "hash": "2c5b1a7a6495a30544972baa96a8850cbe45fafa3dce99d03214c29b73e345ae"
+  },
+  "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.9.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

quantum-viz/examples/display_example.py

@@ -0,0 +1,17 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+##
+# This script shows how to display a Qiskit circuit on a new browser window rendered using the Viewer.
+##
+from qiskit.circuit.random import random_circuit
+from qiskit.circuit.reset import Reset
+from quantum_viz.utils import display
+
+qc = random_circuit(4, 5, measure=False, reset=True, conditional=False)
+qc.barrier()
+qc.rccx(0, 3, 2)
+qc.sxdg(1)
+qc.append(Reset(), [1])
+
+print(qc.draw())
+display(qc, skip_barriers=False, style="BlackAndWhite", version="1.0.2")

quantum-viz/noxfile.py

@@ -1,3 +1,5 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
 """Nox sessions."""
 import shutil
 import sys
@@ -19,7 +21,7 @@
     raise SystemExit(dedent(message))
 
 
-package = "quantum_viz"
+package = "quantum-viz"
 python_versions = ["3.9", "3.8", "3.7"]
 nox.needs_version = ">= 2021.6.6"
 nox.options.sessions = (
@@ -140,7 +142,7 @@ def mypy(session: Session) -> None:
 @session(python=python_versions)
 def tests(session: Session) -> None:
     """Run the test suite."""
-    session.install(".")
+    session.install(".[qiskit]")
     session.install("coverage[toml]", "pytest", "pygments")
     try:
         session.run("coverage", "run", "--parallel", "-m", "pytest", *session.posargs)
@@ -165,7 +167,7 @@ def coverage(session: Session) -> None:
 @session(python=python_versions)
 def typeguard(session: Session) -> None:
     """Runtime type checking using Typeguard."""
-    session.install(".")
+    session.install(".[qiskit]")
     session.install("pytest", "typeguard", "pygments")
     session.run("pytest", f"--typeguard-packages={package}", *session.posargs)