Right now, if you want to generate e.g. shift_phase(frame, pi), you need to write program.shift_phase(frame, oqpy.pi), but one could imagine instead writing program.shift_phase(frame, np.pi) or program.shift_phase(frame, math.pi) which might be more natural for users.

We could accommodate this by detecting specific floating point numbers and replacing them with expressions for e.g. pi or pi/2 or 2*pi.

Currently only support individual qubits, but openqasm allows to refer to arrays of qubits as well.

Currently

p1 = Program()
...
p2 = Program()
...
p1.to_qasm()
(p1 + p2).to_qasm()

and

p1 = Program()
...
p2 = Program()
...
# skip this --> p1.to_qasm() 
(p1 + p2).to_qasm()

Produce different outcomes because the autodeclaration in to_ast mutates p1. One potential solution is to (at least by default) copy the program before converting to ast, although this could have performance concerns. A faster solution could be to change the autodeclaration code such that it only affected the generated output, rather than the state of the program.

I.e. this section: https://openqasm.com/language/gates.html

In python, the user will likely be representing durations as floats with some canonical unit, probably seconds. It is inconvenient for the user to need to remember where a float is allowed and where a duration is required. We can help this along by detecting when a user is passing a float someplace where a duration is expected and insert <expr> * 1s. Or vice versa, we can detect if a user is passing a duration where a float is expected and pass <expr> / 1s.

I could imagine turning this behavior on and off with a configuration setting passed to an initializing Program.

We could try to minimize the number of decimals required to show the value.

Investigate how and where to convert slices into RangeDefinition.

Add support for making a function call that assigns return to classical variables

OPENQASM 3.0;
bit b0;
b0 = my_function();

For loops can be used with identifiers:

array = {0, 1, 2};
for int i in array {}

OQpy needs to check that the identifier points to a valid iterable variable.

For (possibly) all variables types (e.g. BoolVar, IntVar) etc, we do not do any type validation/conversion if the user tries to create a variable with a value that is not a boolean or integer.

Some suggests for cases where we should consider converting instead of failing:
BoolVar(1, "i") --> BoolVar(True, "i")
IntVar(1.0, "j") --> IntVar(1, "j")

There may also be some other cases where it would make more sense to warn & convert instead of failing.

With #20 merged to main we can now declare return types in defcal statements. However there isn't a convenient way to return values from defcal statements (as far as I can tell, please correct me if I'm wrong). This capability is demonstrated in the capture instructions of the OpenPulse Grammar specification. I suggest implementing a new method of the opqy.Program class that adds a ReturnStatement ast node to the program

def returns(self, return_var:AstConvertible):
    self._add_statement(ast.ReturnStatement(return_var.to_ast(self)))
    return self

This method just wraps the current workaround I've found to return a value from a defcal statement which requires using the 'private' _add_statement function of opqy.Program, see e.g. the following example

from openpulse import ast

import oqpy

prog = oqpy.Program()  # create a new oqpy program

m0 = oqpy.PortVar("m0")
cap0 = oqpy.PortVar("cap0")
stimulus_frame = oqpy.FrameVar(m0, 5e9, 0, name="stimulus_frame")
caputure_frame = oqpy.FrameVar(cap0, 5e9, 0, name="capture_frame")
dummy_wfm = oqpy.WaveformVar([-1.0, 0.5, 0.25, -0.75], "dummy_wfm")
capture_v2 = oqpy.declare_extern("capture_v2", [("output", ast.FrameType()), ("duration", oqpy.duration)], oqpy.bit)
qubit = oqpy.PhysicalQubits[0]

with oqpy.defcal(prog, qubit, "measure", return_type=oqpy.bit):
    prog.play(stimulus_frame, dummy_wfm)
    prog._add_statement(
        ast.ReturnStatement(capture_v2(caputure_frame, 16000e-9).to_ast(prog))
    )  # Suggestion: replace with prog.returns(result)

prog.measure(qubit, oqpy.BitVar(name="measured_bit"))

print(prog.to_qasm(encal_declarations=True))

Which generates the following OpenQASM code

OPENQASM 3.0;
defcalgrammar "openpulse";
cal {
    extern capture_v2(frame, duration) -> bit;
    port m0;
    port cap0;
    frame stimulus_frame = newframe(m0, 5000000000.0, 0);
    waveform dummy_wfm = {-1.0, 0.5, 0.25, -0.75};
    frame capture_frame = newframe(cap0, 5000000000.0, 0);
}
bit measured_bit;
defcal measure $0 -> bit {
    play(stimulus_frame, dummy_wfm);
    return capture_v2(capture_frame, 16000.0ns);
}
measured_bit = measure $0;

I'm willing to take the lead on implementing this method and any tests that may be required.

Program._add_var gets invoked often, and expr_matches is relatively expensive. We should consider alternatives.

Barrier and delay should take None as argument (which should be the default behavior):

.barrier() -> barrier;, i.e places a barrier on all frames
.barrier([]) -> does NOT insert an AST node
.barrier([frames]) -> barrier frame0, frame1, ...;, i.e. places a barrier on all listed frames

The AST for DelayInstruction and QuantumBarrier defines a qubits attribute, but in oqpy we also use them for frames so the attribute naming is misleading. The typing is not an issue here.

@dataclass
class DelayInstruction(QuantumStatement):
    """
    Delay instruction

    Example::

        delay[start_stretch] $0;
    """

    duration: Expression
    qubits: List[Union[IndexedIdentifier, Identifier]]

@dataclass
class QuantumBarrier(QuantumStatement):
    """
    A quantum barrier instruction

    Example::

        barrier q;
    """

    qubits: List[Expression]

In particular the calculation of binary expression types is fragile.

Check arguments types of Program's member functions. Currently

set_phase(frame=x, phase=frame)

is allowed, which would submit a program including the OQ instruction and the corresponding AST node:

set_phase(x, frame)

Add support for BitVar indexing with an integer variable that allows the usage:

arr = BitVar[20](name="arr")
index = IntVar(2, "index")
prog.set(arr[index], 1)

For instance, we shouldn't accept "delay" as a valid variable name, since it is a keyword.

#48 Surfaced 2 remaining issues where the AST we produce is not consistent with the openqasm3 AST type hints.

1. Pragmas are not statements, I think to keep them from being added anywhere other than at the top level. I would guess they should be added to the set of valid types in a Program.statements field.
2. Box statements only allow QuantumStatement which does not include e.g. play openpulse function calls.