feat: add routine explorer jupyter widget (#44)

* Add initial work on LaTeX support * fixed latex tests * Remove unnecessary comments and add CR * Remove unnecessary Optional * Remove unused import * Remove leftover comments * Update CR * Move latex to integration subpackage * fix latex issue for names with underscores * feat(latex): add missing returns * feat(latex): get latex render looking nice in jupyter notebooks and lab * feat(latex): fix some issues with underscores in param names * feat(integrations): implemented basic Routine explorer jupyter widget * build(extras): added optional extras for jupyter dependencies * docs(installation): add installation information for jupyter extras * update lock file * update tutorials to include routine_explorer * build(poetry): regenerate lockfile * ci(tests): install package using jupyter extras * bug(latex): remove backslashes from f-string replacement field * refactor(tests): extract parametrize instances to variable * test(latex): fixed broken latex tests * ci(mypy): install jupyter extra requirement * docs: move API reference to end * fix: update readme * fix: multiple style issues * fix: add qref back to tool.mypy.overrides * feat: add pipeline for testing tutorials * fix: add jupyter dependency to tutorials action * fix: add missing dev dependencies * fix: add missing dev dependencies * fix: update tutorials action * fix: update function name in tutorial * fix: add deque to explore_routine * fix: remove event_log from routine_explorer --------- Co-authored-by: Konrad Jałowiecki <[email protected]> Co-authored-by: mstechly <[email protected]>
PsiQ · May 29, 2024 · 1dfac28 · 1dfac28
1 parent 8356648
commit 1dfac28
Show file tree

Hide file tree

Showing 19 changed files with 733 additions and 386 deletions.
diff --git a/.flake8 b/.flake8
@@ -23,6 +23,9 @@ ignore =
     # Line break after the binary operator
     W503,
     W504,
+    # Docstrings for public modules and packages
+    D100,
+    D104,
 per-file-ignores =
-    tests/**/test_*.py:D103,D102,D101
+    tests/*:D100,D101,D102,D103,D104
     __init__.py:F401
diff --git a/.github/workflows/quality_checks.yaml b/.github/workflows/quality_checks.yaml
@@ -30,7 +30,7 @@ jobs:
       - name: Install dependencies and the package
         run: |
           python -m pip install --upgrade pip poetry
-          poetry install
+          poetry install -E jupyter
       - name: Run unit tests
         run: poetry run pytest
 
@@ -46,7 +46,7 @@ jobs:
         uses: abatilo/actions-poetry@v2
       - name: Run checks
         run: |
-          poetry install
+          poetry install -E jupyter
           pip install pre-commit
           pre-commit install
           pre-commit run -a
@@ -68,3 +68,22 @@ jobs:
           poetry install --with docs
       - name: Build docs
         run: poetry run mkdocs build
+
+
+  test_tutorials_run:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.9"
+      - uses: actions/checkout@v2
+      - name: Setup poetry
+        uses: abatilo/actions-poetry@v2
+      - name: Install package and deps
+        run: |
+          poetry install -E jupyter
+      - name: Convert notebooks to scripts and run them
+        run: |
+          poetry run jupyter nbconvert --to python docs/tutorials/*.ipynb --execute
+
diff --git a/README.md b/README.md
@@ -8,11 +8,11 @@ Bartiq is a library that allows to analyze a quantum routines and calculate symb
 
 To install `bartiq` run: `pip install bartiq`.
 
-In order to install it from source clone the repo by running `git clone git@github.com:PsiQ/qref.git` and then run `pip install .` from the main directory.
+In order to install it from source clone the repo by running `git clone https://github.com/PsiQ/bartiq.git` and then run `pip install .` from the main directory.
 
 ```bash
-# Clone bartiq repo (you can use HTTP link as well)
-git clone git@github.com:PsiQ/bartiq.git
+# Clone bartiq repo (you can use SSH link as well)
+git clone https://github.com/PsiQ/bartiq.git
 cd bartiq
 pip install .
 ```

diff --git a/docs/installation.md b/docs/installation.md
@@ -2,12 +2,16 @@
 
 ## Basic
 
-To install `bartiq` run: 
+To install `bartiq` run:
 
 ```bash
 pip install bartiq
 ```
 
+!!! info
+
+    If you wish to use the package's jupyter integrations, run `pip install "bartiq[jupyter]"` instead.
+
 ## From Source
 
 For a source install run:
@@ -19,9 +23,13 @@ cd bartiq
 pip install .
 ```
 
+!!! info
+
+    If you wish to use the package's jupyter integrations, run `pip install ".[jupyter]"` instead.
+
 ## Development
 
-For development we recommend installing using `poetry`: 
+For development we recommend installing using `poetry`:
 
 ```bash
 git clone [email protected]:PsiQ/bartiq.git
@@ -30,7 +38,12 @@ pip install poetry
 poetry install
 ```
 
-This will create a virtual environment for you and install all developer and docs dependencies within it.
+!!! info
+
+    If you wish to use the package's jupyter integrations, run `poetry install -E jupyter` instead.
+
+This will create a virtual environment for you and install all developer and
+docs dependencies within it.
 
 To enter this environment run:
 

diff --git a/docs/reference.md b/docs/reference.md
@@ -9,3 +9,5 @@
 ::: bartiq.routing
 
 ::: bartiq.errors
+
+::: bartiq.integrations
diff --git a/docs/tutorials/02_alias_sampling_basic.ipynb b/docs/tutorials/02_alias_sampling_basic.ipynb
@@ -455,6 +455,104 @@
     "And now we finally have some concrete numbers!"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "33ef184a-f3a5-4c8f-8f9d-423b5d506556",
+   "metadata": {},
+   "source": [
+    "## Exploring the estimates\n",
+    "\n",
+    "If we just interact with bare python objects, getting a quick idea of the values of various fields might be a bit cumbersome.\n",
+    "That's where `explore_routine` functions might be helpful. Try it out using the snippet below.\n",
+    "\n",
+    "<div class=\"alert alert-block alert-info admonition note\"> <p class=\"admonition-title\"><b>NOTE:</b></p>\n",
+    "This is an interactive feature and will not render in the static version of the docs. To use it you need to run this tutorial as a jupyter notebook.\n",
+    "</div>\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "id": "1a346534-4f97-4855-8262-2c5df824eb27",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "0abdf57a3f6c40318de80a701c9e3610",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "HBox(children=(_RoutineTree(multiple_selection=False, nodes=(Node(name='', nodes=(Node(name='usp'), Node(name=…"
+      ]
+     },
+     "execution_count": 14,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from bartiq.integrations import explore_routine\n",
+    "explore_routine(evaluated_routine)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c35b2019-aa78-478b-b320-f6515b9b6276",
+   "metadata": {},
+   "source": [
+    "If you'd prefer a static representation, you can also simply export routine to latex:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "id": "a925abe0-9026-4079-9c5a-8ef5e087a551",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/latex": [
+       "$\\displaystyle \\begin{align}\n",
+       "&\\text{Routine \\textrm{()}}\\newline\n",
+       "&\\underline{\\text{Input ports:}}\\\\\n",
+       "&\\text{In\\_0} = R\\\\\n",
+       "&\\text{In\\_1} = 8\\\\\n",
+       "&\\text{In\\_2} = R\\\\\n",
+       "&\\text{In\\_3} = 8\\\\\n",
+       "&\\text{In\\_4} = 1\\newline\n",
+       "&\\underline{\\text{Output ports:}}\\\\\n",
+       "&\\text{out\\_0} = R\\\\\n",
+       "&\\text{temp\\_0} = 8\\\\\n",
+       "&\\text{temp\\_1} = R\\\\\n",
+       "&\\text{temp\\_2} = 8\\\\\n",
+       "&\\text{temp\\_3} = 1\\newline\n",
+       "&\\underline{\\text{Resources:}}\\\\\n",
+       "&rotations = 2\\\\\n",
+       "&T_{\\text{gates}} = \\operatorname{log}_{2}{\\left(120 \\right)} + 824\\\\\n",
+       "&\\text{usp}.\\!T_{\\text{gates}} = 320\\\\\n",
+       "&\\text{usp}.\\!rotations = 2\\\\\n",
+       "&\\text{qrom}.\\!T_{\\text{gates}} = 476\\\\\n",
+       "&\\text{compare}.\\!T_{\\text{gates}} = 28\\\\\n",
+       "&\\text{swap}.\\!T_{\\text{gates}} = \\operatorname{log}_{2}{\\left(120 \\right)}\n",
+       "\\end{align}$"
+      ],
+      "text/plain": [
+       "<IPython.core.display.Math object>"
+      ]
+     },
+     "execution_count": 15,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from bartiq.integrations import routine_to_latex\n",
+    "from IPython.display import Math\n",
+    "Math(routine_to_latex(evaluated_routine))"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "3756e437-22fe-47b4-8fc3-009785d2ea8d",
@@ -464,7 +562,8 @@
     "Let's sum up what we covered in this tutorial:\n",
     "\n",
     "- How to take an algorithm from a paper and compile it into `bartiq`\n",
-    "- How to create a routine with multiple resources, `local_variables` and custom functions"
+    "- How to create a routine with multiple resources, `local_variables` and custom functions\n",
+    "- How to use `explore_routine` and latex integration to get most out of `bartiq`"
    ]
   },
   {

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -29,9 +29,9 @@ nav:
       - tutorials/index.md
       - tutorials/01_basic_example.ipynb
       - tutorials/02_alias_sampling_basic.ipynb
-  - reference.md
   - troubleshooting.md
   - limitations.md
+  - reference.md
 
 
 plugins:
Original file line number	Diff line number	Diff line change
Expand Up		@@ -9,3 +9,5 @@
		::: bartiq.routing

		::: bartiq.errors

		::: bartiq.integrations