Documentation around DELAY feels unclear

[notmgsk]

The proposal says

A DELAY instruction is equivalent to a NONBLOCKING no-operation on all specified frames. For example, DELAY 0 "xy" 1.0 delays frame 0 "xy" by one second.

If the DELAY instruction presents a list of qubits with no frame names, all frames on exactly these qubits are delayed. Thus DELAY 0 1.0 delays all one qubit frames on qubit 0, but does not affect 0 1 "cz".

The pyquil docstring for DELAY says

def DELAY(*args) -> Union[DelayFrames, DelayQubits]:
    """
    Produce a DELAY instruction.

    Note: There are two variants of DELAY. One applies to specific frames on some
    qubit, e.g. `DELAY 0 "rf" "ff" 1.0` delays the `"rf"` and `"ff"` frames on 0.
    It is also possible to delay all frames on some qubits, e.g. `DELAY 0 1 2 1.0`.

    :param args: A list of delay targets, ending with a duration.
    :returns: A DelayFrames or DelayQubits instance.
    """

The proposal definition seems to not exclude the following which delays specific frames on a number of qubits: DELAY q1 q2 ... qN f1 f2 ... fM <delay>. The second definition however does exclude that.

Questions:

• Is it correct that the example above should be an error.
• If yes -- why? Seems like an odd use case to exclude, so I wonder if there is a reason that is not obvious to me?

[braised-babbage]

The PyQuil docstring is a typo, it should be possible to delay a frame which is on multiple qubits. The PyQuil DelayFrames instruction allows for this too.

At the language level I think there are two main motives:

• The basic objects on which delays are applied are frames, but the syntactic question is whether we force people to write out all delayed frames individually or to allow for more abbreviated syntax. The DELAY q1 ... qN f1 ... fM <time> syntax was just a lightweight abbreviation
• Sometimes users may need to delay on some qubits without knowing precisely what frames are on those. This is why we allow the DELAY q1 ... qN <time> syntax.

In PyQuil the two separate varieties are represented by two separate instruction classes.