Python binding support for the Program type

[notmgsk]

To support a robust and fluent Python ecosystem (see QCS SDK Rust) we should provide comprehensive Python support for the quil_rs::Program type, and it hew close to the interface presented by pyquil.Program.

Before working on this issue we should have a plan for

• what is supported
• what is deprecated (but supported)
• what is not supported

and we should have input from intended users (e.g. @caldwellshane and @jokasinski).

[jselig-rigetti]

RE rigetti/pyquil#1455 make sure to support LaTeX generation

[MarquessV]

This issue has been closed out now that quil-py is live. Any remaining work has its own issue.

Here's a checklist of tasks that need to be completed to close out this issue. Issues/PRs will be created as we get to them, and this list is still living, like a hydra, new tasks often spawn out of completed ones.

Ready to work

Instruction API:

Unless otherwise stated, each of these needs:

1. A new constructor, w/ validations (if applicable).
2. Corresponding Python bindings.
3. Mapped to the corresponding pyQuil AbstractInstruction or QuilAtom subclass.

Complexity commonly arises in (1) when the type doesn't cleanly translate to something that can be mapped
to a pyo3 binding (e.g. enum struct variants). Extra complexity also pops up in (3) when a quil-rs
Instruction doesn't cleanly map to a pyQuil type (e.g. Arithmetic), limitations with pyO3
(e.g. not being able to pickle pyo3 types, or subclass enums), or quil-rs is missing functionality
(e.g. declarations w/ OFFSET). For that reason I'm using 1 day as a lower bound for each instruction. My hope is that adds enough of a buffer to account for any unseen complexity.

Remaining instructions:

• Arithmetic (pyQuil only) (1 day)
• BinaryLogic (pyQuil only) (1 day)
• Capture (2 days)
• CircuitDefinition (quil-rs PR, pyQuil PR)
• Convert (1 day)
• Comparison (1 day)
  • ComparisonOperator
  • ComparisonOperand
• Declaration (needs OFFSET support)
• Delay (quil-rs PR, pyQuil PR)
• Exchange (1 day)
• Fence (1 day) (quil-rs PR, pyQuil PR)
• GateDefinition (PR)
  • Needs Pauli-Sum support (PR)
• Include (0 days - not in pyQuil?)
• Control Flow (see Placeholder work)
  • Jump
  • JumpUnless
  • JumpWhen
  • Label
• Load (1 day)
• Move (1 day)
• Pragma (3 days) (quil-rs PR, pyQuil PR)
  • PragmaArgument
• Pulse (1 day)
• RawCapture (2 days)
• Reset (1 day) (quil-rs PR, pyQuil PR)
• SetFrequency (1 day)
• SetPhase (1 day)
• SetScale (1 day)
• ShiftFrequency (1 day)
• ShiftPhase (1 day)
• Store (1 day)
• SwapPhases (1 day)
• UnaryLogic (1 day)
  • UnaryOperator
• Wait (no-variant) (0.5 day)
• WaveformDefinition (quil-rs PR, pyQuil PR)

Parsing Fixes:

• GateDefinition: Parameter parsing (%)
• PRAGMA READOUT-POVM fails to parse, probably the - (Not needed, was a pyQuil bug)

Program Unitary

• Add a method to build and return the unitary of a program #187

Release Engineering (~3 days)

• Re-configure knope with scopes for each package.
• CI flows for building wheels and publishing the package.
• Figure out how to bundle quil-py with qcs-sdk-python
  • Either:
    • Define quil-py as a required dependency of qcs-sdk-python
    • Re-export with a build script

Pickling

• Tracked by quil-rs#169

quil-rs Features:

• Support Declaration OFFSETs quil-rs#171

Expressions API

• Expressions API Python Binding quil-rs#168
• Use Expressions API in pyQuil (Done as part of DefGate)

Misc

• Deprecate quilatom.format_parameter (0.5 day)
• Deprecate PRAGMA Delay in pyQuil, use DELAY instruction instead (Not needed, not really used in pyQuil, parser should error on it).
• Remove to_headers() quil-rs#151 (2 days)
• get_match_for_measurement should follow precedence rules quil-rs#160 (0.5 day)

Blocked

Control Flow Methods

• Needs Support Qubit & Label Placeholders #147
  • Update bindings to use Display::to_string() to Quil::to_quil()
  • Instruction API: Control Flow #197
  • Use it in pyQuil (3 days, to account for friction between implementations)

Endgame (5 days)

• Docs sweep and update
• Migration guide
• CHANGELOG

LaTeX Module

• In progress by @hiyaryan quil-rs#145

Finished

Instruction API

Via:

1. quil-rs#140

2. pyQuil#1518

3. quil-rs#168

4. pyQuil#1542

Instruction Types

• CalibrationDefinition
• FrameDefinition
• Gate
• Halt
• MeasureCalibrationDefinition
• Measurement
• Nop

Supporting Types:

Arithmetic

• ArithmeticOperand
• ArithmeticOperator
• BinaryOperand
• BinaryOperands
• BinaryOperator

Declaration

• MemoryReference
• ScalarType
• Vector

Frame

• AttributeValue
• FrameIdentifier

Gate

• GateDefinition
• GateModifier
• GateSpecification
• Qubit

Waveform

• Waveform
• WaveformInvocation

Other

• Re-implement get_classical_addresses_from_quil_program pyQuil#1451
• CalibrationSet API quil-rs#156, pyQuil#1536
• FrameSet API quil-rs#170, pyQuil#1543