Quilt Extensions

.gitlab-ci.yml

@@ -78,6 +78,7 @@ test-coverage:
   extends: .python
   script:
     - make coverage
+  allow_failure: true
 
 ####################################################################################################
 # MASTER-ONLY JOBS

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "quillang"]
+	path = docs/quil
+	url = https://github.com/rigetti/quil.git

CHANGELOG.md

@@ -9,6 +9,7 @@ Changelog
 ### Improvements and Changes
 
 - Unpacking bitstrings is significantly faster (@mhodson-rigetti, @notmgsk, #1276).
+- Parsing is now performed using Lark rather than ANTLR (@notmgsk, #1278).
 
 ### Bugfixes
 

CONTRIBUTING.md

@@ -228,10 +228,7 @@ verify that everything looks right!
 
 ### Working with the Parser
 
-Working with the ANTLR parser involves some extra steps, so make sure to read the
-[Parser README](pyquil/_parser/README.md) if you plan on making changes to it. Note
-that you only need to install ANTLR if you want to change the grammar; simply running
-the parser involves no additional steps beyond installing pyQuil as usual.
+The parser is implemented with Lark. See the [parser README](pyquil/_parser/README.md).
 
 ### Using the Docker Image
 

Makefile

@@ -16,11 +16,11 @@ check-format:
 
 .PHONY: check-types
 check-types:
-	mypy .
+	mypy pyquil
 
 .PHONY: check-style
 check-style:
-	flake8
+	flake8 pyquil
 
 .PHONY: clean
 clean:
@@ -80,3 +80,11 @@ upload:
 .PHONY: version
 version:
 	@git describe --tags | sed 's/v//' | sed 's/\(.*\)-.*/\1/'| sed 's/-/./'
+
+docs/quil/grammars/Quil.g4:
+	git submodule init
+	git submodule update
+
+.PHONY: generate-parser
+generate-parser: docs/quil/grammars/Quil.g4
+	cd docs/quil/grammars && antlr -Dlanguage=Python3 -o ../../../pyquil/_parser/gen3 Quil.g4

docs/source/apidocs/gates.rst

@@ -34,12 +34,37 @@ in the computational (Z) basis.
     MEASURE
 
 
+Quilt instructions
+------------------
+
+Quilt extends the above "native" operations with several more.
+
+.. autosummary::
+    :toctree: autogen
+    :template: autosumm.rst
+
+    PULSE
+    SET_FREQUENCY
+    SHIFT_FREQUENCY
+    SET_PHASE
+    SHIFT_PHASE
+    SWAP_PHASE
+    SET_SCALE
+    CAPTURE
+    RAW_CAPTURE
+    DELAY
+    FENCE
+
+
+
 All gates and instructions
 --------------------------
 
 In general, you will write a quantum program using the full suite of Quil gates and instructions
 and use :ref:`the Quil compiler <compiler>` to compile programs into the target instruction
-set (ISA). The full list of quantum gates and classical Quil instructions is enumerated here.
+set (ISA).
+
+Furthermore, Quilt instructions may be executed natively, although are not fully supported by the Quil compiler or QVM.
 
 .. rubric:: Single-qubit gates
 .. autosummary::
@@ -77,7 +102,24 @@ set (ISA). The full list of quantum gates and classical Quil instructions is enu
     PSWAP
 
 
-.. rubric:: Classical instructions
+.. rubric:: Quilt instructions
+.. autosummary::
+    :toctree: autogen
+    :template: autosumm.rst
+
+    PULSE
+    SET_FREQUENCY
+    SHIFT_FREQUENCY
+    SET_PHASE
+    SHIFT_PHASE
+    SWAP_PHASE
+    SET_SCALE
+    CAPTURE
+    RAW_CAPTURE
+    DELAY
+    FENCE
+
+.. rubric:: Other classical instructions
 .. autosummary::
     :toctree: autogen
     :template: autosumm.rst
@@ -112,5 +154,6 @@ set (ISA). The full list of quantum gates and classical Quil instructions is enu
 .. autosummary::
 
     QUANTUM_GATES
+    QUILT_INSTRUCTIONS
     STANDARD_INSTRUCTIONS
 

docs/source/apidocs/program.rst

@@ -13,6 +13,9 @@ Program
 
         ~Program.instructions
         ~Program.defined_gates
+        ~Program.calibrations
+        ~Program.waveforms
+        ~Program.frames
         ~Program.out
         ~Program.get_qubits
         ~Program.is_protoquil
@@ -47,6 +50,15 @@ Program
         ~Program.while_do
         ~Program.if_then
 
+    .. rubric:: Quilt Routines
+    .. autosummary::
+        :toctree: autogen
+        :template: autosumm.rst
+
+        ~Program.get_calibration
+        ~Program.match_calibrations
+        ~Program.calibrate
+
     .. rubric:: Utility Methods
     .. autosummary::
         :toctree: autogen

docs/source/apidocs/waveforms.rst

@@ -0,0 +1,25 @@
+Quilt Waveforms
+===============
+
+.. currentmodule:: pyquil.quiltwaveforms
+
+All Quilt waveforms have corresponding PyQuil syntax objects. For example, a waveform written in Quilt syntax as ``flat(iq: 1.0, duration: 1e-5)`` corresponds to a :py:class:`~pyquil.quiltwaveforms.FlatWaveform` object.
+
+.. autosummary::
+    :toctree: autogen
+    :template: autosumm.rst
+
+
+    FlatWaveform
+    GaussianWaveform
+    DragGaussianWaveform
+    HrmGaussianWaveform
+    ErfSquareWaveform
+    BoxcarAveragerKernel
+
+
+
+Custom Waveforms
+----------------
+
+Custom waveform definitions, introduced in Quilt with ``DEFWAVEFORM``, have a corresponding :py:class:`~pyquil.quilbase.DefWaveform` object. These are referenced in PyQuil with :py:class:`~pyquil.quilatom.WaveformReference`.

docs/source/conf.py

@@ -47,6 +47,7 @@
     "sphinx.ext.viewcode",
     "sphinx_autodoc_typehints",
     "nbsphinx",
+    "recommonmark"
 ]
 
 autosummary_generate = True
@@ -59,7 +60,7 @@
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
 
 # The encoding of source files.
 #

docs/source/index.rst

@@ -86,12 +86,23 @@ Contents
    changes
    intro
 
+.. toctree::
+   :maxdepth: 3
+   :caption: Quil-T
+
+   quilt
+   quilt_getting_started
+   quilt_waveforms
+   quilt_parametric
+   quilt_raw_capture
+
 .. toctree::
    :maxdepth: 1
    :caption: API Reference
 
    apidocs/program
    apidocs/gates
+   apidocs/waveforms
    apidocs/pauli
    apidocs/quantum_computer
    apidocs/compilers

docs/source/quilt.rst

@@ -0,0 +1,34 @@
+.. _quilt:
+
+Quil-T
+======
+
+Quil-T is an extension to Quil which introduces pulse-level control to
+quantum programs. With Quil-T one can describe a program at a level
+lower than is typically permitted in circuit-type programs, with
+explicit control over the RF waveforms played by the QPU's control
+hardware. In particular this imbues programs with a notion of *time*,
+hence the `T` suffix.
+
+The Quil compiler `quilc` was developed to support most users in their
+pursuit for producing an optimal program from a high-level
+language. In contrast Quil-T was developed to enable the low-level and
+precise control desired by power-users. For example, for many users
+the implementation details of a Hadamard gate are not particularly
+important, and indeed the behind-the-scenes realisation of a Hadamard
+gate are likely to change over time as gate implementations are
+recalibrated to provide the best results. If you instead you are
+interested in those details, and in particular you want to control
+those details, then pulse-level control with Quil-T is the way to
+go. With Quil-T you can define precisely what you mean by `H 0`, you
+can perform experiments to characterize the underlying hardware such
+as determining `T1`. The hardware is almost at your fingertips.
+
+.. note::
+
+   Quil-T is not yet finalized and subject to change. The following
+   link should be updated upon the release of Quil-T.
+
+For examples, see the adjacent notebooks. For more information, see
+the Quil-T proposal at the `Quil project homepage
+<https://github.com/rigetti/quil/tree/bugfix/quilt-rfc-improvements/rfcs/analog>`_.