add quantikz circuit plotting

cl-quil.asd

@@ -293,15 +293,18 @@
 (asdf:defsystem #:cl-quil/tools
   :description "Tools for cl-quil developers."
   :license "Apache License 2.0 (See LICENSE.txt)"
-  :depends-on (#:cl-quil)
+  :depends-on (#:cl-quil
+               #:common-lisp-jupyter
+               #:swank)
   :in-order-to ((asdf:test-op (asdf:test-op #:cl-quil/tools-tests)))
   :around-compile (lambda (compile)
                     (let (#+sbcl (sb-ext:*derive-function-types* t))
                       (funcall compile)))
   :pathname "src/tools/"
   :serial t
   :components ((:file "package")
-               (:file "hasse-schedule")))
+               (:file "hasse-schedule")
+               (:file "circuit-diagram")))
 
 (asdf:defsystem #:cl-quil/tools-tests
   :description "Regression tests for tools for cl-quil developers."
@@ -315,4 +318,5 @@
   :serial t
   :components ((:file "package")
                (:file "suite")
-               (:file "hasse-diagram-tests")))
+               (:file "hasse-diagram-tests")
+               (:file "circuit-diagram-tests")))

src/ast.lisp

@@ -1301,6 +1301,9 @@ N.B. This slot should not be accessed directly! Consider using GATE-APPLICATION-
             'vector)
   "The list of RATIONAL multiples of PI that are checked by FORMAT-REAL when *PRINT-FRACTIONAL-RADIANS* is T.")
 
+(defparameter *pi-literal* "pi"
+  "String representation of a PI literal.")
+
 (defun format-real (r stream)
   "Print the real number R nicely to the stream STREAM."
   (check-type r real)
@@ -1315,8 +1318,8 @@ N.B. This slot should not be accessed directly! Consider using GATE-APPLICATION-
            :for denom := (denominator rr)
            :when (double~ r-abs (/ (* pi numer) denom)) :do
              ;; Pretty-print "reasonable" integer and fractional multiples of pi.
-             (format stream "~:[~;-~]~:[~D*~;~*~]pi~:[/~D~;~*~]"
-                     (minusp r) (= 1 numer) numer (= 1 denom) denom)
+             (format stream "~:[~;-~]~:[~D*~;~*~]~A~:[/~D~;~*~]"
+                     (minusp r) (= 1 numer) numer *pi-literal* (= 1 denom) denom)
              (return-from format-real))
      ;; If we cannot find a nice fraction of pi, just print the real number.
      (format stream "~F" r))))

src/package.lisp

@@ -312,6 +312,7 @@
    #:named-operator                     ; ADT CONSTRUCTOR
    #:controlled-operator                ; ADT CONSTRUCTOR
    #:dagger-operator                    ; ADT CONSTRUCTOR
+   #:forked-operator                    ; ADT CONSTRUCTOR
    #:operator-description-root-name     ; FUNCTION
    #:operator-description=              ; FUNCTION
    #:operator-description-hash          ; FUNCTION

src/tools/README.md

@@ -2,6 +2,68 @@
 
 Tools for cl-quil developers.
 
+These provide functionality above and beyond core `cl-quil`, but perhaps at the cost of additional system dependencies (e.g. `graphviz` or `pdflatex`). Read the instructions carefully!
+
+A short summary of what follows in this README is indicated below.
+
+| Section | Description |
+| --- | ----------- |
+| Circuit Diagrams | Generate plots of circuit diagrams from Quil code.  |
+| Hasse Schedule | Visualize `logical-scheduler` data. |
+
+## Circuit Diagrams
+
+Render a Quil `parsed-program` object as a circuit diagram. There are a few possible backends:
+- `:jupyter-svg` (default) render to SVG and show inline in a Jupyter notebook
+- `:slime-png` render to a PNG and show inline in a Slime session
+- `:latex` just produce quantikz source for the diagram
+
+### Example Usage
+
+#### Jupyter
+
+To generate a Jupyter SVG object capable of rendering inline,
+```
+(plot-circuit <parsed-program>)
+```
+
+To save SVG output, use `:output-file <filename>`.
+
+An example Jupyter session is shown below.
+
+![Example PLOT-CIRCUIT usage in a Jupyter notebook](images/plot-circuit-example.png)
+
+
+#### SLIME
+
+![Example PLOT-CIRCUIT usage in SLIME](images/plot-circuit-slime.png)
+
+### Installation Instructions
+
+#### `:jupyter-svg`
+
+You will need `pdflatex` and `pdf2svg` in your path. On macOS, `pdflatex` is part of the `mactex` distribution. Both of these may be installed with homebrew:
+```
+brew install mactex
+brew install pdf2svg
+```
+
+These executables are referred to in `cl-quil.tools` by `*pdflatex-exe*` and `*pdf2svg-exe`, should you wish to override them.
+
+To use this in a Jupyter notebook, you should use [common-lisp-jupyter](https://github.com/yitzchak/common-lisp-jupyter). As an installation note, some users have found that on macOS the default SBCL path associated with the jupyter kernel (e.g. in `~/Library/Jupyter/kernels/common-lisp/kernel.json`) is incorrect; this will result in `jupyter` being unable to start the Common Lisp kernel.
+
+#### `:slime-png`
+
+You need `pdflatex` (cf. above) and `convert` (from ImageMagick) in your path. These executables are referred to in `cl-quil.tools` by `*pdflatex-exe*` and `*convert-exe*`, should you wish to override them.
+
+The Slime interaction requires two SLIME contribs: `slime-media` and `slime-repl` (which is included in `slime-fancy`). In addition, you must enable SLIME evaluation in Emacs. This all can be done, for example, by the following (from `config.el`):
+
+```
+(slime-setup '(slime-fancy slime-media))
+(setq slime-enable-evaluate-in-emacs t)
+```
+
+
 ## Hasse Schedule
 
 The *Hasse schedule* tool helps you to visualize the *logical-scheduler* data structure, which is used by the addresser to organize and manage resource dependencies between instructions on 'logical' qubits.