There are too many ways to construct a Program

In the pyQuil documentation for "Programs and Gates", we see snippets like this:

import numpy as np

from pyquil import Program
from pyquil.gates import RX, RZ, MEASURE

qubit = 0

p = Program()
ro = p.declare("ro", "BIT", 1)
theta_ref = p.declare("theta", "REAL")

p += RX(np.pi / 2, qubit)
p += RZ(theta_ref, qubit)
p += RX(-np.pi / 2, qubit)

p += MEASURE(qubit, ro[0])

Which seem to imply that we are pushing the += <PYQUIL_OBJECT> method of building out Program objects as the recommended way. However, there are other spots in the source, docs, and examples, where other forms of program construction are used. These include:

1. p.inst(X(0))
2. p.inst("X 0")
3. p = Program(X(0))
4. p = Program("X 0")
5. p += "X 0"
6. p += Program(X(0))
   etc.

We as pyQuil developers / maintainers feel that this is simply too many ways to do the same thing, and is a source of confusion. We would like to funnel all program construction toward one canonical/supported way of doing so.

My vote would be for the += <PYQUIL_OBJECT> method, but there are some caveats to this. There are specialized methods on the Program object, and some can easily be replaced by the += approach. Others, like the declare method or ones that add control flow, are not as easily swapped out.

For example, the declare method returns a MemoryReference that we use when adding MEASURE instructions:

p = Program()
ro = p.declare("ro", "BIT")
p += MEASURE(0, ro[0])

# replaced by

p = Program()
p += Declare("ro", "BIT")
ro = MemoryReference("ro")
p += MEASURE(0, ro[0])

In addition, the control flow methods like if_then are convenient, as they handle the different jump statements for you. However, there is probably a way unify everything into the += approach, so we are looking for input / suggestions based off of what people prefer to use, before we settle on one!

Start with the Program API and the “Programs and Gates” documentation, then review the listed construction forms in the source, docs, and examples. The work is not implementation-ready until maintainers choose a canonical construction method and decide how specialized methods such as declare and if_then fit; done would include a documented decision and consistent examples.