Add plugin pass to support non-calibrated rzz angles

[nkanazawa1989]

Summary

IBM Quantum recently released new basis set including rzz gate. The Rzz gate supports continuous angle but it is calibrated only within [0, pi/2]. We have implemented the validation mechanism to detect non-calibrated angles, but user always need to manually tweak circuits to avoid angles outside this range, which is a bit cumbersome.

This PR adds a plugin pass to automatically modifies the input circuit so that end users don't need to consider our hardware constraints. However, a user still needs to consider the constraints when they send parameterized PUB with Rzz gates. The latter case is outside the scope of this PR.

Details and comments

This PR adds new translation plugin. Alternatively we can add new pass to existing ibm_dynamic_circuits entry point, but name is very specific to the dynamic circuits feature and adding fractional feature under this plugin name seems confusing. For now I decided to create new entry point ibm_fractional but eventually these must be merged when our hardware supports both features with a single execution path.

[yaelbh]

Thanks @nkanazawa1989.

As much as users will certainly be happy to have all angle values covered, it will also be confusing for them to see that values that are supposed to be invalid pass all the checks and run successfully.

Therefore:

1. We should document that fixed angles can have any value, whereas parametrized angles are restricted.
2. We should similarly rephrase the ISA error message.

[yaelbh]

What I wrote here is not accurate. An ISA circuit is still a circuit where all rzz angles are in the range [0, pi/2].

How can we let the users know that, if they transpile with a backend that enables fractional gates, then they enjoy the service of the transpiler taking care of the angle values for them?

[nkanazawa1989]

Thanks @yaelbh for review. I also feel we have vague definition of "ISA". In case of Rzz, the instruction becomes ISA for "IBM Quantum" only when angle in [0, pi/2] (this is why the pass is plugin). I added more document in a45251a. Hope it improves understanding.

[yaelbh]

The documentation that you added is very good. I think the general documentation of fractional gates should be updated somehow. Right now it says that theta must be between 0 and pi/2, and does not mention that you don't have to worry about it if you only transpile your circuit.

[nkanazawa1989]

does not mention that you don't have to worry about it if you only transpile your circuit.

+1. @kaelynj can you update the doc?

[yaelbh]

+1. @kaelynj can you update the doc?

Just not yet... Thanks 😄.

[yaelbh]

Be aware of Qiskit/qiskit#13320. It's planned for Qiskit 2.0. #2043 should be merged first.

[nkanazawa1989]

Thanks for linking the issue. Probably it's safer to merge this first as you mention. Qiskit core doesn't need to consider angle restriction because this is very IBM Quantum specific.

[yaelbh]

@kt474 I'm reviewing the transpiler pass, but can you please review the design of the entry point ibm_fractional? Maybe we should consult Matthew about it?

[yaelbh]

I'm not sure exactly how to proceed with this PR, now that Naoki is on leave. I guess that I'll take ownership on it. @wshanks and @kt474, can you please read my comments, see if they make sense, and answer questions therein?

[wshanks]

@yaelbh I think we can take over this PR. I didn't understand the bug you mentioned and I would rather defer to someone else on the consistency of the transpiler plugins. I think otherwise this looks good. I will apply the wording suggestions you made.

[yaelbh]

I'll take care of this PR today. Main work items:

1. Apply global phase.
2. Add an integration test, which will verify that generate_preset_pass_manager with a fractional backend invokes the new pass.
3. Probably improve the tests a bit.
4. Ask Kevin and Shelly to review the plugin.
5. Go over comments along the PR and make sure that they are all addressed.

[yaelbh]

@kt474 Can you please explain how the transpiler plugins mechanism works?

I tried:

    def test_fractional_pluging(self):
        """ Verify that a pass manager created for a fractional backend applies the rzz folding
        pass"""

        circ = QuantumCircuit(2)
        circ.rzz(7, 0, 1)

        # this commented section is not working either
        #pm = generate_preset_pass_manager(optimization_level=0, target=FakeFractionalBackend().target)
        #isa_circ = pm.run(circ)

        from qiskit import transpile
        isa_circ = transpile(circ, FakeFractionalBackend())

        print(isa_circ)

But the pass manager is not applied, what am I doing wrong?

[yaelbh]

Note a comment in another issue, that's related to this PR: #2032 (comment).

[wshanks]

@yaelbh Regarding the transpiler plugin, I think the problem is that FakeFractionalBackend inherits from FakeBackendV2 which inherits from BackendV2. I think the extra transpiler passes get added into the preset pass managers through hook methods on the backend like this one on IBMBackend (and we probably need to add a hook to IBMBackend as well, and perhaps also to FakeFractionalBackend):

qiskit-ibm-runtime/qiskit_ibm_runtime/ibm_backend.py

Lines 912 to 914 in 639f307

	def get_translation_stage_plugin(self) -> str:
	"""Return the default translation stage plugin name for IBM backends."""
	return "ibm_dynamic_circuits"

Edit: I see the PR does modify the IBMBackend hook, so the question is just adding the hook to FakeFractionalBackend versus testing with an IBMBackend instead.

[yaelbh]

The hook is not working for me also with an IBMBackend:

from qiskit.circuit import QuantumCircuit, Parameter
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager

from qiskit_ibm_runtime import QiskitRuntimeService


service = QiskitRuntimeService()
backend = service.backend("ibm_fez", use_fractional_gates=True)

p = Parameter("p")

circ = QuantumCircuit(2)
circ.rzz(7, 0, 1)


pm = generate_preset_pass_manager(optimization_level=0, target=backend.target)
isa_circ = pm.run(circ)

print(isa_circ)

This results with rzz(7), in spite of using the code of this PR.

[mtreinish]

If you're using the hook points for a backend alternate default stage those only work if you specify the backend to the pass manager constructor. They don't exist on the target.

[yaelbh]

Thanks @mtreinish, it works for fez.

[yaelbh]

Thanks to an advice from @alexanderivrii, I was able to write a test that I'm OK with, in bae9209.

[yaelbh]

This would work too:

qiskit-ibm-runtime/qiskit_ibm_runtime/transpiler/passes/scheduling/__init__.py

Lines 156 to 157 in 681aeb9

	# Temporary workaround for mock backends. For real backends this is not required.
	backend.get_translation_stage_plugin = lambda: "ibm_dynamic_circuits"

[wshanks]

Here are some minor formatting suggestions for the release note. Otherwise, I think this is ready to merge. If merging the release note suggestions dismisses my approval, I think you can still approve and merge @yaelbh since you did not open the PR.

[yaelbh]

Following #2043 (comment):
@kaelynj Since the PR is merged, it's time to think of updating the doc. I'm not sure exactly how to do it.
The story is that rzz gates in ISA circuits must satisfy 0 <= theta <= 2pi, as written in the doc.
Transpiling a circuit with an IBM backend will automatically generate a circuit that satisfies this request.

[yaelbh]

Also I guess that the doc update should take place at the time of the next release of qiskit-ibm-runtime, and it should be stated that this feature is available only starting from that release.