Merge pull request #276 from zxcalc/master

Merge master to sfx

.gitignore

@@ -14,3 +14,4 @@ dist
 .env
 *.zxr
 .ipynb_checkpoints
+doc/_build/*

.readthedocs.yaml

@@ -0,0 +1,35 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#   - pdf
+#   - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: requirements.txt

README.md

@@ -1,4 +1,4 @@
-The [ZX-calculus](http://zxcalculus.com) gives us a handy way to represent and work with quantum computations. ZXLive is an interactive tool for working with ZX. Draw graphs or load circuits and apply ZX rules. Intended for experimenting, building proofs, helping to write papers, showing off, or simply learning about ZX and quantum computing. It is powered by the [pyzx](https://github.com/Quantomatic/pyzx) open source library under the hood.
+The [ZX-calculus](http://zxcalculus.com) gives us a handy way to represent and work with quantum computations. ZXLive is an interactive tool for working with ZX. Draw graphs or load circuits and apply ZX rules. Intended for experimenting, building proofs, helping to write papers, showing off, or simply learning about ZX and quantum computing. It is powered by the [pyzx](https://github.com/Quantomatic/pyzx) open source library under the hood. The documentation is available at https://zxlive.readthedocs.io/
 
 This project is in a pretty early stage, with lots more to come. Have a look at the [Issue Tracker](https://github.com/Quantomatic/zxlive/issues) to see what's in the pipeline.
 
@@ -13,3 +13,12 @@ To install from source, you need Python >= 3.9 and pip. If you have those, just
 
 Then, you can run ZXLive by typing `python3 -m zxlive`.
 
+# Documentation
+
+This project uses Sphinx to build a ReadTheDocs page. In addition, it uses the MyST preprocessor to allow us to write documentation in a Markdown-like format rather than Sphinx's native rich structured text format.
+
+The documentation can be built with
+
+```
+cd doc; make html
+```

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/conf.py

@@ -0,0 +1,49 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'zxlive'
+copyright = '2024, ZXLive team'
+author = 'ZXLive team'
+release = '0.1'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+              'sphinx.ext.autodoc',
+              'sphinx.ext.mathjax',
+              'sphinx.ext.napoleon',
+              'sphinx_rtd_theme',
+              'sphinx_autodoc_typehints',
+              'sphinxcontrib.rsvgconverter',
+              'myst_parser'
+]
+
+myst_enable_extensions = ["colon_fence"]
+
+add_function_parentheses = False
+set_type_checking_flag = True
+napoleon_use_rtype = False
+
+add_module_names = False
+
+source_suffix = ['.rst', '.md']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+htmlhelp_basename = 'zxlivedoc'

doc/gettingstarted.md

@@ -0,0 +1,106 @@
+# Getting started with ZXLive
+
+ZXLive is a visual proof assistant for ZX-diagrams. ZX-diagrams are a graphical language for reasoning about quantum processes. If you don't know what ZX-diagrams are, check out [the ZX-calculus website](https://zxcalculus.com/).
+
+You can install ZXLive using pip:
+
+```
+pip install zxlive
+```
+
+You can then run it using `python -m zxlive`.
+
+:::{warning} 
+ZXLive currently requires MacOS 11+, due to older version lacking support for the newer versions of Qt.
+:::
+
+When you open ZXLive for the first time, you will see a window that looks something like this:
+
+```{figure} _static/mainwindow.png
+:alt: The ZXLive editor window
+:align: center
+
+The ZXLive editor window
+```
+This is the ***editor mode***. In this mode you can freely edit the diagram. There are three main tools
+
+```{figure} _static/editor_window_toolbar.png
+:alt: The toolbar in the Editor window
+:align: center
+
+The editing tools are: 1. Select (s), 2. Add vertex (v), and 3. Add edge (e), 4. Undo (Ctrl-U), 5. Redo (Ctrl-Shift-U), 6. Import a circuit in the QASM format, 7. Enter "Proof mode" to start performing ZX rewrites.
+```
+With the Select tool active you can select any part of the graph by dragging a box, or directly clicking on vertices or edges, using the left mouse button. Control- or shift-clicking adds to the selection.
+
+## Demo: Three alternating CNOTs make a SWAP
+
+Let's suppose we want to show that three alternating CNOTs are equivalent to a SWAP gate.
+
+Start by deleting this graph by either click and dragging a selection rectangle around the graph element, or press `Ctrl-A` to select everything. Then press delete to delete them
+
+```{figure} _static/deletenodes.gif
+:alt: Deleting nodes in the Editor window
+:align: center
+
+Deleting nodes in the Editor window whilst in select mode.
+```
+
+Now to start the new graph, suppose we want to create the classic circuit of three alternating CNOTs.
+
+Select the Z spider vertex type from the vertex selection panel on the right hand side and enter vertex mode by pressing `v`. Then click the locations to place the spiders. Do the same for X spiders and boundary nodes and join them together with wires after pressing `e` to enter edge mode.
+
+```{figure} _static/create_alternating_cnots.gif
+:alt: Creating an alternating CNOT circuit
+:align: center
+
+Create a circuit comprised of three alternating CNOTs.
+```
+
+Now that we have created the three CNOTs, we can try to reduce them to the swap operation. Click "Start Derivation" to begin a new proof using the current ZX diagram.
+
+```{figure} _static/proof_window.png
+:alt: The ZXLive Proof window
+:align: center
+
+The ZXLive Proof window.
+```
+
+We can no longer add or remove nodes or edges in the graph directly. Intstead, we must perform ZX rewrites to reduce the graph to the desired state.
+
+```{figure} _static/proof_window_toolbar.png
+:alt: The Proof window's toolbar
+:align: center
+
+The Proof window's toolbar. 1. Select mode (s), 2. Magic wand (w), 3. The type of spider the magic wand creates when drawn over a plain wire, 4. Undo (Ctrl-U) / Redo (Ctrl-Shift-U).
+```
+
+First enter select mode by pressing `s`. Now simply drag and drop one of the Z spiders onto an X spider and ZXLive will automatically perform the bialgebra rule.
+
+```{figure} _static/bialgebra.gif
+:alt: The bialgebra rule
+:align: center
+
+Applying the bialgebra rule to two complementary spiders.
+```
+
+Notice that an entry has been added into the rewrite history panel on the right. You can click "START" up the top right to preview the previous state of the graph before applying the bialgebra rule.
+
+Now drag the adjacent Z and X spiders together to fuse them. Notice that there are some spiders with only two legs and are therefore are equal to the identity. We can remove these by either selecting the spider and clicking the "Basic rules > remove identity" rule in the rule panel on the left, or we could use the magic wand (`w`) and draw the wand over the identity to remove it.
+
+```{figure} _static/simplify_graph.gif
+:alt: Merging spiders and removing identities
+:align: center
+
+Simplify the graph by merge spiders of the same type and removing identity spiders.
+```
+
+Apply these techniques one more time to reduce the diagram to the SWAP operation. Notice in the animation before that after merging the X spiders, there should be two edges between the resulting Z and X spider --- however they both disappear. This is because ZXLive automatically applied the Hopf algebra rule to eliminate double wires between complementary spiders.
+
+```{figure} _static/simplify_to_swap.gif
+:alt: Simplify the graph to a SWAP
+:align: center
+
+Simplify the graph to a SWAP.
+```
+
+Our proof is now complete and we could either save it as a proof file ("File > Save") which could be loaded by ZXLive again later, or we could export the proof to tikz to be included in a LaTex document by selecting "File > Export to Tikz".

doc/index.rst

@@ -0,0 +1,22 @@
+.. zxlive documentation master file, created by
+   sphinx-quickstart on Wed Jun 12 18:31:52 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to zxlive's documentation!
+==================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   gettingstarted
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

pyproject.toml

@@ -29,7 +29,7 @@ classifiers = [
 ]
 dependencies = [
     "PySide6",
-    "pyzx >= 0.8.0",
+    "pyzx @ git+https://github.com/Quantomatic/pyzx.git",
     "networkx",
     "numpy",
     "shapely",
@@ -44,6 +44,13 @@ test = [
     "pylint",
     "pytest-qt",
 ]
+doc = [
+    "sphinx>=2.3,<7",  # see: https://github.com/readthedocs/readthedocs.org/issues/10279
+    "sphinx_autodoc_typehints>=1.10",
+    "sphinx_rtd_theme>=0.4,",
+    "sphinxcontrib-svg2pdfconverter>=1.2.2",
+    "myst-parser>=3.0.0"
+]
 
 [project.urls]
 Homepage = "https://github.com/Quantomatic/zxlive"

requirements.txt

@@ -10,3 +10,8 @@ pyperclip>=1.8.1
 mypy
 pylint
 pyproject-flake8
+sphinx>=2.3,<7  # see: https://github.com/readthedocs/readthedocs.org/issues/10279
+sphinx_autodoc_typehints>=1.10
+sphinx_rtd_theme>=0.4
+sphinxcontrib-svg2pdfconverter>=1.2.2
+myst-parser>=3.0.0

zxlive/base_panel.py

@@ -9,8 +9,8 @@
                                QToolBar, QVBoxLayout, QWidget)
 
 from .animations import AnimatedUndoStack
-from .commands import SetGraph
-from .common import GraphT
+from .commands import ChangeEdgeCurve, SetGraph
+from .common import GraphT, new_graph
 from .dialogs import FileFormat
 from .graphscene import GraphScene
 from .graphview import GraphView
@@ -34,6 +34,7 @@ def __init__(self, *args: QWidget | QAction, exclusive: bool = False) -> None:
 class BasePanel(QWidget):
     """Base class implementing functionality shared between the edit and
     proof panels."""
+    splitter_sizes = dict()
 
     graph_scene: GraphScene
     graph_view: GraphView
@@ -58,6 +59,7 @@ def __init__(self, *actions: QAction) -> None:
 
         self.splitter = QSplitter(self)
         self.layout().addWidget(self.splitter)
+        self.splitter.splitterMoved.connect(self.sync_splitter_sizes)
 
         self.file_path = None
         self.file_type = None
@@ -86,7 +88,7 @@ def _toolbar_sections(self) -> Iterator[ToolbarSection]:
         raise NotImplementedError
 
     def clear_graph(self) -> None:
-        empty_graph = GraphT()
+        empty_graph = new_graph()
         cmd = SetGraph(self.graph_view, empty_graph)
         self.undo_stack.push(cmd)
 
@@ -108,4 +110,14 @@ def copy_selection(self) -> GraphT:
         return copied_graph
 
     def update_colors(self) -> None:
-        self.graph_scene.update_colors()
+        self.graph_scene.update_colors()
+
+    def sync_splitter_sizes(self):
+        self.splitter_sizes[self.__class__] = self.splitter.sizes()
+
+    def set_splitter_size(self):
+        if self.__class__ in self.splitter_sizes:
+            self.splitter.setSizes(self.splitter_sizes[self.__class__])
+
+    def change_edge_curves(self, eitem, new_distance, old_distance):
+        self.undo_stack.push(ChangeEdgeCurve(self.graph_view, eitem, new_distance, old_distance))