Add `generate_clifford_t_pass_manager` by alexanderivrii · Pull Request #15918 · Qiskit/qiskit

alexanderivrii · 2026-03-30T21:09:16Z

Summary

This PR introduces a function generate_clifford_t_pass_manager which is analogous to generate_preset_pass_manager but exposes arguments specifically tailored for Clifford+T compilation. In particular it does not have arguments such as init_stage or optimization_stage but has arguments rz_synthesis_error and rz_cache_error relevant to synthesizing RZ-gates to Clifford+T basis set.

The previously existing ways of instantiating a Clifford+T transpiler pipeline (via transpile or generate_preset_pass_manager with a Clifford+T basis set) are still supported, however using the new function is recommended.

Details and comments

I have defined the following classes:

PassManagerCliffordTConfig, which is analogous to PassManagerConfig but tailored for Clifford+T. Currently it subclasses PassManagerConfig as Clifford+T compilation pipeline (not changed in this PR) uses default layout, routing and scheduling stages. (Actually the only place which really needs this to be a subclass is DefaultRoutingPassManager which calls SabreSwapPassManager, which assumes that config includes layout_method. And I did not want to explicitly add layout_method to PassManagerCliffordTConfig as per previous discussions we might want to completely change how layout and routing look for Clifford+T compilations).
PassManagerCliffordTStagePlugin, which is analogous to PassManagerCliffordTStagePlugin, but tailored for Clifford+T compilation.

Both of the above classes are internal for now (not exposed in the documentation on purpose) since we might want to further refactor them when the PBC compilation pipeline will be added.

reno and docs

qiskit-bot · 2026-03-30T21:09:20Z

One or more of the following people are relevant to this code:

@Qiskit/terra-core

Cryoris · 2026-03-31T14:58:01Z

+        rz_synthesis_error: float | None = None,
+        rz_cache_error: float | None = None,


I would expect this to go under the umbrella of generic synthesis arguments. Once we add a plugin here we'll need to accommodate for this, plus other synthesis methods might handle caching differently. Could we just call this rz_synthesis_config and make it a generic dictionary to pass into the synthesis method?

That was mainly to show that we now can add Clifford+T pipeline-specific arguments (and because you have asked for this for comparing against other tools). But I agree that we need to think a bit more about how synthesis and Clifford+T should look.

Cryoris

Some high level comments, I didn't read the logic yet 🙂

Cryoris · 2026-03-31T14:58:51Z

+            basis_gates (list): List of basis gate names to unroll to.
+            coupling_map (CouplingMap): Directed graph representing a coupling
+                map.


Could we ditch these and just use a Target instead? Or is there a reason to use these as standalone?

In theory, we can, however I am personally so used to generate preset pass managers while specifying basis_gates and coupling_map manually, that I would miss this functionality. However, based on our offline discussion, I have removed backend as an argument (especially that we have no such backends at the moment).

Cryoris

I took a closer look and overall this looks good. I left some, mostly minor comments, below. I didn't re-run the benchmarks since this doesn't touch the pipeline itself.

Cryoris · 2026-04-16T15:03:12Z

-            if pass_manager_config.routing_method != "none":
-                split_2q_unitaries_swap = True


This is because the routing method cannot be set and is always the default method, right?

Cryoris · 2026-04-16T15:04:02Z

+    rz_synthesis_error: float | None = None,
+    rz_cache_error: float | None = None,
+):
+    r"""Generate a Clifford+T :class:`~.PassManager`


Suggested change

Suggested change

r"""Generate a Clifford+T :class:`~.PassManager`

r"""Generate a preset Clifford+T :class:`.StagedPassManager`.

Cryoris · 2026-04-16T15:04:57Z

+):
+    r"""Generate a Clifford+T :class:`~.PassManager`
+
+    This function provides a fast and convenient way to construct a preset pass manager for


I guess every way is "fast" since there's no computation done 😄

Suggested change

This function provides a fast and convenient way to construct a preset pass manager for

This function provides a convenient way to construct a preset pass manager for

Cryoris · 2026-04-16T15:05:40Z



+def generate_preset_clifford_t_pass_manager(
+    optimization_level=2,


Could we add typehints to all these arguments?

Cryoris · 2026-04-16T15:07:44Z

+            :class:`~.StagedPassManager` for. By default optimization level 2
+            is used if this is not specified. This can be 0, 1, 2, or 3. Higher
+            levels generate potentially more optimized circuits, at the expense
+            of longer transpilation time:


Can we ensure to use compilation and transpilation consistently? So far we've been talking about compilation in the docstring, which I think makes sense due to the RZ->T step.

Cryoris · 2026-04-16T15:31:03Z

+        qc.rz(theta, 0)
+
+        # testing approximation_degree
+        for eps in 10.0 ** np.arange(-2, -13, -1):


How long do these run? We could just run a few values here, we don't need to run every one 🙂

Cryoris · 2026-04-16T15:32:34Z

+        unitary_synthesis_method (str): The name of the unitary synthesis
+            method to use. By default ``'default'`` is used. You can see a list of
+            installed plugins with :func:`.unitary_synthesis_plugin_names`.


Suggested change

unitary_synthesis_method (str): The name of the unitary synthesis

method to use. By default ``'default'`` is used. You can see a list of

installed plugins with :func:`.unitary_synthesis_plugin_names`.

unitary_synthesis_method (str): The name of the unitary synthesis

method to use. By default ``'default'`` is used. You can see a list of

installed plugins with :func:`.unitary_synthesis_plugin_names`.

Note that, while this is supported, it is encouraged to not synthesize

arbitrary unitaries in this fashion due to high T count and no available

cache.

Cryoris · 2026-04-16T15:32:57Z

+features_transpiler:
+  - |
+    Added a new function :func:`~.generate_preset_clifford_t_pass_manager`, which provides
+    a fast and convenient way to construct a preset pass manager for Clifford+T compilation.


Suggested change

a fast and convenient way to construct a preset pass manager for Clifford+T compilation.

a convenient way to construct a preset pass manager for Clifford+T compilation.

Cryoris · 2026-04-16T15:33:21Z

+
+    For example::
+
+        from qiskit.transpiler.preset_passmanagers import generate_preset_clifford_t_pass_manager


Can we make this available on qiskit.transpiler?

Cryoris · 2026-04-16T15:34:09Z

+        basis_gates = ["cx", "s", "sdg", "h", "t", "tdg"]
+        pass_manager = generate_preset_clifford_t_pass_manager(basis_gates=basis_gates, optimization_level=3)


I would suggest this example to not set the basis gates specifically, one of the nice things here is that we don't have to do that anymore. Instead maybe just show compiling a simple circuit and counting the gates?

Adding generate_clifford_t_pass_manager

cec6797

reno and docs

alexanderivrii requested a review from a team as a code owner March 30, 2026 21:09

alexanderivrii added this to Qiskit 2.5 Mar 30, 2026

github-project-automation bot moved this to Ready in Qiskit 2.5 Mar 30, 2026

alexanderivrii added this to the 2.5.0 milestone Mar 30, 2026

alexanderivrii added Changelog: Added Add an "Added" entry in the GitHub Release changelog. fault tolerance related to fault tolerance compilation labels Mar 30, 2026

alexanderivrii requested a review from Cryoris March 30, 2026 21:10

alexanderivrii added 2 commits March 31, 2026 00:40

docs

45bd6b8

docs fix

640bee8

Cryoris reviewed Mar 31, 2026

View reviewed changes

alexanderivrii added 4 commits April 6, 2026 12:25

docstring

d096bf5

renaming

b5f1f52

docstring

09343b7

support for not specifying neither basis_gates nor target

b481d98

Cryoris moved this from Ready to In development in Qiskit 2.5 Apr 15, 2026

Cryoris self-assigned this Apr 16, 2026

Cryoris reviewed Apr 16, 2026

View reviewed changes

		rz_synthesis_error: float \| None = None,
		rz_cache_error: float \| None = None,

		if pass_manager_config.routing_method != "none":
		split_2q_unitaries_swap = True

	r"""Generate a Clifford+T :class:`~.PassManager`
	r"""Generate a preset Clifford+T :class:`.StagedPassManager`.

	This function provides a fast and convenient way to construct a preset pass manager for
	This function provides a convenient way to construct a preset pass manager for



		def generate_preset_clifford_t_pass_manager(
		optimization_level=2,

	a fast and convenient way to construct a preset pass manager for Clifford+T compilation.
	a convenient way to construct a preset pass manager for Clifford+T compilation.


		For example::

		from qiskit.transpiler.preset_passmanagers import generate_preset_clifford_t_pass_manager

		basis_gates = ["cx", "s", "sdg", "h", "t", "tdg"]
		pass_manager = generate_preset_clifford_t_pass_manager(basis_gates=basis_gates, optimization_level=3)

Conversation

alexanderivrii commented Mar 30, 2026

Summary

Details and comments

Uh oh!

qiskit-bot commented Mar 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Cryoris left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexanderivrii Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Cryoris left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alexanderivrii Apr 6, 2026 •

edited

Loading