Add RZ to QIR QIS

[rainij]

The corresponding QIS function will probably look like this

declare void @__quantum__qis__rz__body(double, ptr)

Original suggestion (DO NOT IMPLEMENT!)

Originally we wanted an fixed point angle with this format:

declare void @__quantum__qis__rz__body(i32, ptr)

The i32 encodes an angle from the interval $[0,2\pi)$. Although the hardware seems to prefer fixed point value for efficiency the QIR community seems to have settled on floats (see discussion below). This probably introduces some friction, especially with high speed modalities but we handle this in upcoming issues.

[burgholzer]

Note that the canonical way of representing the RZ gate is to use a floating point value for the angle (see, e.g., qir-alliance/qir-spec#46).
The lowering to a specific ISA and quantization to fixed-point arithmetic for angles, should IMO be done elsewhere in the pipeline.
If our compiler produces an RZ gate in a QIR program, the community expects the angle to be a floating point.

[rainij]

If our compiler produces an RZ gate in a QIR program, the community expects the angle to be a floating point.

@burgholzer I see that one needs support for this in some way. On the other hand we currently treat the QIR output as being close to our backend and not to the frontend.

The HiSEP-Q backend expects integers (see spec:

QV.ROT.G: use a stable integer GPR for the angle; verify against scalar traffic hazards.

Interestingly the QISA does not fix the interpretation of the QISA (could be mapped to $[0,2\pi)$ or could be interpreted as Q16.16). I guess this is what I usually call "configurable".

I could imagine that we need (at least) two signatures for QIR: one with integer, one with floats. If a frontend like Qrisp does not support anything else than floats as angles we have to come up with a plan on how to convert those to integers in a predictable way. But I believe we can do this in a different issue.

On the other hand one could debate if QIR is really a good fit for the backend. The HiSEP-Q QISA is quite different to the usual QIS encountered in QIR (although I am not sure how rigid the spec is in that regard). It could be an option to emit LLVM-IR with HiSEP-Q intrinsics instead of QIR. But this is also outside the scope of this issue. Just wanted to mention it for context.

I believe at some point (probably soon) we need to discuss these issues in a meeting.

FYI: @xiguo1030 just that you know about the discussion here (please give feedback if you like)

[burgholzer]

The QIR spec is a blessing and a curse in this regard.
On the one hand, it provides lots of flexibility in how to define the QIS; but on the other hand it also makes this definition a contract between frontends and backends that needs to be agreed upon. By now, this is considered a feature and not a bug in QIR.

I would have personally expected the QIR signature to just always use double for the angle and the piece of software that takes QIR and translates it to HiSEP-Q QISA to quantize the angles to their integer representation (as required by that instruction set).
IMO this creates clear responsibilities and maximizes compatibility of the QIR code being produced by our compiler.
The code for quantization needs to be written anyway somewhere in the compiler as practically no frontend will emit angles as fixed point numbers (OpenQASM 3 technically has support for the angle type).

Whether it is the "best" solution to go through QIR instead of directly to HiSEP-Q is a different question that is out of scope for this issue.

[rainij]

OK I see. Does the QIR spec really explicitly enforce the double data type? I got the impression that it does not say much about the QIS itself, except for imposing certain constraints?

In principle we could quantize late (in the backend compiler) but my feeling says quantizing early might be better. I also asked gemini about that (attached below). It assume only one possible interpretation of the i32 but my feeling is that this is not problematic.

@EnriqueNB maybe you have an oppinion on late vs early quantization?

My ideal solution looks like this:

• quantize as early as possible (in the high-level dialect regime)
• QIR only sees integers (except if the backend explicitly requests floats)
• support both QIR functions, one with i32 and another with float.

I could imagine that for practical reasons we cannot quantize very early right now (not sure if QC or QCO support this). In this case I would still define two QIR functions and add a quantization pass which quantizes one to the other. This way the backend compiler (outside MLIR) is not burdened with this quantization. Does this sound like a plan @burgholzer ?

Gemini on early vs late quantization

It is almost always better to quantize the angle earlier in the pipeline.

In the context of an MLIR-based compiler, doing this transformation during a conversion pass (rather than at the final assembly/binary emission stage) provides several significant advantages:

1. Integer Arithmetic is Exact

Quantum rotation gates are additive: $RZ(\alpha) \cdot RZ(\beta) = RZ(\alpha + \beta)$.

• The Float Problem: If you keep angles as double, repeated optimizations or rotations can lead to floating-point drift and precision loss.
• The i32 Advantage: If you map $[0, 2\pi)$ to the full range of an i32 (often called "binary radians" or BAMs), rotation addition becomes simple modular integer addition. The overflow behavior of an i32 perfectly maps to the periodicity of a circle ($2\pi = 0$).

2. Simplifies the Backend

Your backend (the part emitting the actual QISA) should ideally be as "dumb" as possible. If the backend receives an i32, it just puts that bit pattern into the instruction field.
If you do it "within" the backend:

• You have to implement floating-point-to-fixed-point conversion logic in your emitter.
• You lose the ability to perform late-stage constant folding on those angles using standard MLIR integer passes.

3. Canonicalization and CSE

If you quantize earlier, MLIR's Canonicalizer and CSE (Common Subexpression Elimination) work much more effectively.

• Two rotations of $0.785398$ and $\pi/4$ might not be seen as the same by a simple float CSE.
• Once quantized to the same i32 value (e.g., 0x20000000), they are identical symbols, and the compiler can easily deduplicate them.

4. Hardware-Specific Constraints

Backend quantization often has to deal with "dead zones" or hardware-specific precision (e.g., maybe the hardware only actually supports 12 bits of the 32-bit integer). Handling this in an MLIR pass allows you to insert "Clear Lower Bits" or "Range Check" operations using standard arith ops, which are then visible for further optimization.

Recommendation

Lower the double to i32 during your ConvertQCToQIR or PrepToQIR phase.

You can define a simple conversion utility:
$$Angle_{i32} = \text{round}\left( \frac{Angle_{double}}{2\pi} \times 2^{32} \right)$$

This ensures that by the time you are calling @__quantum__qis__rz__body, the signature already matches your backend's needs (or you have switched to a custom internal function that takes the i32).

Tip: If you need to support both high-level "math" rotations and low-level "quantized" rotations, you can use a TypeConverter to transition the angle type from f64 to i32 as you move down the pipeline.

[xiguo1030]

From my perspective (at the ISA level), the angle format itself doesn't matter much to us at the moment - the parameter is ultimately passed to the AWG, where a specific angle needs to be mapped to a corresponding waveform. Whether it arrives as a double or an integer doesn't affect the integration at the ISA/microarchitecture level. However, the choice does become relevant once we look at the AWG side (or physical simulator): the interpretation of the angle (e.g., mapping to [0, 2π), Q16.16, or something else) determines how the waveform calculation is performed.

[burgholzer]

I'll try to comment on separate items as much as possible. I hope the overall picture still makes sense.

OK I see. Does the QIR spec really explicitly enforce the double data type? I got the impression that it does not say much about the QIS itself, except for imposing certain constraints?

No, QIR does not enforce anything. That was the point I was trying to make above. At the same time, the community kind-of forces the signatures because for QIR to function as an exchange format, the two interacting parties need to agree on the signatures of the core instruction set.
And the community around QIR clearly centers around floating points for rotation angles in every implementation (of both sides) that I know of. Of course, I might be missing some parts of the community, but I still think I have a rather good overview.

In principle we could quantize late (in the backend compiler) but my feeling says quantizing early might be better. I also asked gemini about that (attached below). It assume only one possible interpretation of the i32 but my feeling is that this is not problematic.

My ideal solution looks like this:

• quantize as early as possible (in the high-level dialect regime)
• QIR only sees integers (except if the backend explicitly requests floats)
• support both QIR functions, one with i32 and another with float.

I could imagine that for practical reasons we cannot quantize very early right now (not sure if QC or QCO support this). In this case I would still define two QIR functions and add a quantization pass which quantizes one to the other. This way the backend compiler (outside MLIR) is not burdened with this quantization. Does this sound like a plan @burgholzer ?

This is not how any (at least that I am aware of) quantum SDKs/frameworks/frontends/compilers work. There is very poor support for discretized/quantized rotation angles in optimization routines across the community.
In addition, the only place where this really becomes important is close to the hardware.
At the virtual or hardware-independent level, artificially restricting the precision of angles does not add value and inevitably introduces errors/approximations.
Hardware-specific optimizations may, at a certain point far-down in the compiler pipeline, assume a certain precision for rotation angles; at which point quantization could make sense; however in these stages of the compiler pipeline, rounding does the job as well.
Overall, I see no point in quantizing early as it will only create friction with existing passes/compilation infrastructure and the community.
The need for quantization is, almost by definition, a backend-specific consideration.
As such, it should IMO not "bubble up" into the upper layers of the stack.
Not every device will need it nor want it.

Gemini on early vs late quantization

It is almost always better to quantize the angle earlier in the pipeline.

In the context of an MLIR-based compiler, doing this transformation during a conversion pass (rather than at the final assembly/binary emission stage) provides several significant advantages:

1. Integer Arithmetic is Exact

Quantum rotation gates are additive: R Z ( α ) ⋅ R Z ( β ) = R Z ( α + β ) .

• The Float Problem: If you keep angles as double, repeated optimizations or rotations can lead to floating-point drift and precision loss.

• The i32 Advantage: If you map
  [
  0
  ,
  2
  π
  )
  to the full range of an i32 (often called "binary radians" or BAMs), rotation addition becomes simple modular integer addition. The overflow behavior of an i32 perfectly maps to the periodicity of a circle (
  2
  π

  0
  ).

While this may be true to some degree, it is also kind of a false premise, because limiting yourself to 32 bits of precision is an approximation itself that might incur subtle errors in the overall computations that might have benefited from the full range of a 64 bit double.

2. Simplifies the Backend

Your backend (the part emitting the actual QISA) should ideally be as "dumb" as possible. If the backend receives an i32, it just puts that bit pattern into the instruction field. If you do it "within" the backend:

• You have to implement floating-point-to-fixed-point conversion logic in your emitter.
• You lose the ability to perform late-stage constant folding on those angles using standard MLIR integer passes.

The conversion can, and probably should, still be done on the LLVM IR level, where one can take advantage of standard LLVM passes to simplify the IR further. So the respective conversion would still be an LLVM conversion pass that takes the QIR functions and (most likely) turns them into some kind of intrinsics.

3. Canonicalization and CSE

If you quantize earlier, MLIR's Canonicalizer and CSE (Common Subexpression Elimination) work much more effectively.

• Two rotations of
  0.785398
  and
  π

  /
  

  4
  might not be seen as the same by a simple float CSE.

• Once quantized to the same i32 value (e.g., 0x20000000), they are identical symbols, and the compiler can easily deduplicate them.

This can still happen at the LLVM stage to reduce the IR size. Or, alternatively, if the precision is already known beforehand (on the MLIR level), rounding can be performed in a backend-specific pass.

4. Hardware-Specific Constraints

Backend quantization often has to deal with "dead zones" or hardware-specific precision (e.g., maybe the hardware only actually supports 12 bits of the 32-bit integer). Handling this in an MLIR pass allows you to insert "Clear Lower Bits" or "Range Check" operations using standard arith ops, which are then visible for further optimization.

Recommendation

Lower the double to i32 during your ConvertQCToQIR or PrepToQIR phase.

You can define a simple conversion utility: A n g l e i 32 = round ( A n g l e d o u b l e 2 π × 2 32 )

This ensures that by the time you are calling @__quantum__qis__rz__body, the signature already matches your backend's needs (or you have switched to a custom internal function that takes the i32).

Based on the above, I would argue that the conversion can also take place on the LLVM IR after the conversion to QIR, which would ensure that the QIR program can be read by many more people/frameworks/runtimes, while still targeting the specific hardware-requirements of HiSEP-Q.

[rainij]

@burgholzer OK now I believe I see your point. So basically the community is treating QIR almost exclusively as an exchange format rather than an internal IR. We have also made a similar experience, which was a bit frustrating from a compiler perspective.

Btw: I think on the point of quantization/rounding/double vs i32 we misunderstood each other. But doesn't matter too much.

OK then let us use a double there if this is the "community pseudo standard". But I would still not perform the conversion from within LLVM. I would follow the principle "If it can be done in MLIR, then do it in MLIR" or related "keep the backend as dump as possible". MLIR is much nicer to use (easier, more flexible, etc) and there is some community wishes to move more LLVM tasks into MLIR (this assembly discussion I mentioned on discord points exactly in this direction).

Before the code generation we need HiSEP-Q intrinsics anyway (they are quite a bit different to the QIR functions). We will generate those from within MLIR before exporting to LLVM (so @EnriqueNB 's backend compiler won't see QIR at all - just LLVM-IR with the right intrinsics). We can fix the data types of angles at the same time. I would really label it a fix, because I believe that the frontend should already use the right data types (similar to classical compiled languages were one also cannot interchange float and int easily). This is our "from the metal to the user" guideline which prioritizes hardware if there is a conflict between hardware and frontend.

I am not sure how ugly it gets with dynamically computed angles under the constraint that the control hardware has no floating point unit. In that case the conversion has to happen at runtime. Either the control hardware needs some library to emulate the conversion or if the float ultimately comes from another device (co-precessor) the co-processor should perform the conversion. I would still argue that the cleaner option is to use the datatype enforced by the hardware (at least whenever you actually use a rotation gate). But as I said, since we cannot expect this to change anytime soon we have to fix it ourselves - and we will do it.

[rainij]

@xiguo1030 I am not sure if I understand you correctly. You said it does not matter if the angle is a float or an integer. Actually, if you can accept a float this would help us alot (see my discussion with @burgholzer). The problem is, I do not exactly see how this works in your QISA. The signature of a rotation gate is like this in your QISA

qv.rz    vs1, rs2, Block_imm        # QV.ROT.G

Here rs2 is a 32 bit GPR which holds the angle (as an integer). I understand that you leave the interpretation (e.g. Q16.16 or Q8.24 or something else) open (which is smart IMO) but my understanding was that it is a fixed point in any case. Floats always arrive in floating point registers. For example there exist the following variants of the vadd family of instructions

# For integers:
vadd.vx vd, vs2, rs1, vm   # vector-scalar, rs1 is a GPR like x7
# For floats:
vfadd.vf vd, vs2, rs1, vm  # vector-scalar, rs1 is a FPR like f7

In the second case rs1 needs to be a float register f0 - f31 if I understand the riscv spec correctly. So my feeling is that in order for HiSEP-Q to support float angles properly one would also need a dedicated instruction (e.g. called QV.ROT.GF) just for floats.

Maybe I miss something here. Would be super helpful if we could clarify this 🙂.

[xiguo1030]

@@rainij I may have been thinking about this too simply before. But I think, on the hardware level, a 32-bit IEEE-754 float can sit in a GPR, and the dispatcher will forward it opaquely to the back-end, which is then free to interpret it as either fixed-point or IEEE-754. So mechanically, "float through GPR" works. But this has to be a fixed setup -- the back-end has to commit to one interpretation per program, so switching between integer and float dynamically would be a bit challenging.

But you are right about the ABI side. Standard RISC-V puts float arguments in FPRs (f0-f31), so the RISC-V compiler, seeing qv_rz(qubits, angle), cannot emit the floating point directly; it has to insert an fmv.x.w to move the bit pattern from f-reg to x-reg first. This is the same reason RVV introduces vfadd.vf alongside vadd.vx.

So I think if we force the insertion of the 32-bit float into the GPR, and let the backend (AWG) interpret it, it should work. But I can also look into adding a dedicated float variant (e.g. qv.rg.f as you said), reading directly from FPR. That would make things much easier on the compiler side.

[rainij]

@xiguo1030 we try to find a workaround/quickfix from the compiler side so that you do not have to rush any changes on the QISA side. In particular I would wait before introducing a new instruction for floats (to the QISA). In the end we might regret introducing such an instruction.

I have really no background in control hardware and hence do not know what data types are best suited for "communication" with an AWG. Googling around a bit suggests however that fixed points is the way to go - which also makes sense to me. It could also be that the quickfix we come up above introduces too much overhead in terms of cycles. If this happens we re-evaluate, but I believe it is a problem on the software side. The fixed point on the hardware side seems well motivated.

[burgholzer]

@burgholzer OK now I believe I see your point. So basically the community is treating QIR almost exclusively as an exchange format rather than an internal IR. We have also made a similar experience, which was a bit frustrating from a compiler perspective.

Yes. QIR is much more used as an exchange format than an actual IR in the community; at least in my view of the field.
Almost everyone also solely deals with the text/string based format and hardly anyone would actually accept a QIR binary blob.
Maybe there's a shift in the community that we can influence.

OK then let us use a double there if this is the "community pseudo standard". But I would still not perform the conversion from within LLVM. I would follow the principle "If it can be done in MLIR, then do it in MLIR" or related "keep the backend as dump as possible". MLIR is much nicer to use (easier, more flexible, etc) and there is some community wishes to move more LLVM tasks into MLIR (this assembly discussion I mentioned on discord points exactly in this direction).

We talked past each other, I believe. I would very much do the conversion within MLIR, but on the LLVM dialect (as opposed to LLVM IR itself). It's fairly easy to mix up the LLVM MLIR dialect and LLVM IR in discussions. I definitely meant for the respective pass to be written in MLIR, but most likely acting on a program that has already been converted to the LLVM dialect (when targeting QIR first and not directly the QISA).

Before the code generation we need HiSEP-Q intrinsics anyway (they are quite a bit different to the QIR functions). We will generate those from within MLIR before exporting to LLVM (so @EnriqueNB 's backend compiler won't see QIR at all - just LLVM-IR with the right intrinsics). We can fix the data types of angles at the same time. I would really label it a fix, because I believe that the frontend should already use the right data types (similar to classical compiled languages were one also cannot interchange float and int easily). This is our "from the metal to the user" guideline which prioritizes hardware if there is a conflict between hardware and frontend.

I generally agree with this, especially the "from the metal to the user" analogy. I just believe that there is no conflict here. There is a point to be made for why hardware-independent stages of the compiler pipeline should not worry about discretized angles and should take advantage of all the features of floating point numbers. Application-level code coming in through a frontend will most certainly rely on the industry standard of IEEE-754 floating points for any numerical computation (that may also determine the angles of rotation gates). At the same time, most quantum (control) hardware, at least to the best of my understanding, is inherently limited to a finite precision that is much smaller than 32 or 64 bits of floating points cover, which makes it feasible/sensible/necessary to discretize/quantize to the finite precision closer to hardware.
There is a point along the compiler pipeline where the respective conversion should take place. And this point is IMO still a moving target at the moment. And it may as well depend on the actual hardware (modality).

I am not sure how ugly it gets with dynamically computed angles under the constraint that the control hardware has no floating point unit. In that case the conversion has to happen at runtime. Either the control hardware needs some library to emulate the conversion or if the float ultimately comes from another device (co-precessor) the co-processor should perform the conversion. I would still argue that the cleaner option is to use the datatype enforced by the hardware (at least whenever you actually use a rotation gate). But as I said, since we cannot expect this to change anytime soon we have to fix it ourselves - and we will do it.

Dynamically computed angles will likely be ugly, but let's maybe cross that bridge when we get there and this turns out to be an actual bottleneck. 😌

[rainij]

OK thanks @burgholzer then we have settled the discussion sufficiently enough to get a PR rolling :) . I also updated the issue description accordingly. I left a "section for historians" to document our struggle 😄.

I think this float vs fixed point discussion is not finally settled. I would keep it on my todo list. I could imagine that part of the team (including @xiguo1030) meet at some point and we try to sharpen our understanding. It seems to be a hard problem due to a wide range of people being involved across the full stack from application to hardware.