Increase documentation of built-in transpiler plugins #13620

jakelishman · 2025-01-07T17:53:44Z

Summary

This overhauls how the qiskit.transpiler documentation talks about the transpiler plugins. All of the built-in plugins now have a decent amount of overview documentation, and the requirements and expectations for each stage of the preset pipelines is explained in more detail.

This form of the documentation makes the distinction between "a compilation routine in general" and "Qiskit's specific choice of default pipeline" clearer, to avoid confusion for advanced users.

Much of the guide-level explanations of the different preset pipeline stages moved to https://docs.quantum.ibm.com some time ago, so this PR removes those, in favour of focussing on the actual API, and inserts links to learn more about the principles elsewhere.

The guide-level explanation of scheduling is left in-place for now, because the content on the other parts of the IBM documentation isn't as complete for that.

Details and comments

I've attempted to draw a good line between explaining what Qiskit actually does, so users know, and maintaining that we reserve the right to modify specifics of things (especially default plugins) between minor versions.

This isn't a full rewrite of everything - I feel like we could probably do with revisiting the documentation of a lot of individual transpiler passes' classes - but I was writing my own plugin over the last month or so, and this is documentation I personally wanted to see.

This overhauls how the `qiskit.transpiler` documentation talks about the transpiler plugins. All of the built-in plugins now have a decent amount of overview documentation, and the requirements and expectations for each stage of the preset pipelines is explained in more detail. This form of the documentation makes the distinction between "a compilation routine in general" and "Qiskit's specific choice of default pipeline" clearer, to avoid confusion for advanced users. Much of the guide-level explanations of the different preset pipeline stages moved to https://docs.quantum.ibm.com some time ago, so this PR removes those, in favour of focussing on the actual API, and inserts links to learn more about the principles elsewhere. The guide-level explanation of scheduling is left in-place for now, because the content on the other parts of the IBM documentation isn't as complete for that.

qiskit-bot · 2025-01-07T17:53:49Z

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

@Qiskit/terra-core

jakelishman · 2025-01-07T17:55:04Z

Docs team: as of right now, we don't necessarily need to bother copy-editing - first I need to get sign-off from the rest of the compiler team that this is the appropriate level of detail for us to document, and doesn't over-tie our hands with respect to the stability policy. If you guys have any comments about the high-level content, that's very welcome immediately.

coveralls · 2025-01-07T18:20:26Z

Pull Request Test Coverage Report for Build 12915883307

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

1 of 1 (100.0%) changed or added relevant line in 1 file are covered.
1203 unchanged lines in 37 files lost coverage.
Overall coverage remained the same at 88.94%

Files with Coverage Reduction	New Missed Lines	%
crates/circuit/src/lib.rs	1	94.64%
crates/accelerate/src/basis/basis_translator/basis_search.rs	1	99.3%
crates/qasm3/src/build.rs	1	72.24%
crates/accelerate/src/isometry.rs	1	99.65%
crates/accelerate/src/unitary_synthesis.rs	2	92.97%
crates/qasm3/src/lib.rs	2	87.88%
crates/accelerate/src/synthesis/linear/mod.rs	2	93.41%
crates/accelerate/src/sabre/neighbor_table.rs	3	74.29%
crates/circuit/src/parameter_table.rs	3	93.97%
crates/qasm2/src/lex.rs	3	92.98%

Totals
Change from base Build 12885084518:	0.0%
Covered Lines:	79438
Relevant Lines:	89316

💛 - Coveralls

ElePT

Thanks Jake! I have taken a look to the introduction up to the init stage details and left a few comments. I will try to finish the review later today :)

qiskit/transpiler/__init__.py

ElePT · 2025-01-09T10:46:22Z

qiskit/transpiler/__init__.py

+    backend = QiskitRuntimeService().backend("some-backend")
+
+    # Create the pass manager for the transpilation ...
+    pm = generate_preset_pass_manager(backend=backend)


We have had a few back and forths over the use of backend vs target as the "main" transpilation input, the original text said "target backend" so the terms where kind of interchangeable in the docs. Now, the code examples sometimes use backend, sometimes target, but the text mostly refers to the target. I don't think it's difficult to understand, but I wonder if we'd like to explain this nuance a bit better to users (maybe the answer is no).

I don't have a strong preference with the state of Qiskit right this second, but I think Ian and I might be beginning to argue for an expansion of the meaning of Backend for a hypothetical BackendV3 that will make it preferable to use backend as the default user-facing bit.

I've left this as-is for now, but feel free to argue.

Co-authored-by: Elena Peña Tapia <[email protected]>

qiskit/transpiler/__init__.py

qiskit/transpiler/preset_passmanagers/__init__.py

qiskit/transpiler/preset_passmanagers/plugin.py

abbycross

some copy-editing suggestions and otherwise reads great!!

Co-authored-by: abbycross <[email protected]>

jakelishman · 2025-01-22T18:08:47Z

Thanks! Should all be applied now. I get the logic in changing "1- and 2-qubit" (etc) to "one- and two-qubit", it just feels a bit weird to write that because the numerals are easier to read to me. But this is all prose anyway, so better to have it consistent.

abbycross · 2025-01-22T18:58:37Z

Thanks! Should all be applied now. I get the logic in changing "1- and 2-qubit" (etc) to "one- and two-qubit", it just feels a bit weird to write that because the numerals are easier to read to me. But this is all prose anyway, so better to have it consistent.

I hear that. The general rule to apply is if the number is under 10, we spell it out (unless it is attached to a unit, like 5 mm for example). I personally prefer "single- and two-qubit" but didn't change the "one" to "single" since I didn't want to wreck the line lengths :) and also, one-qubit is just as clear as single-qubit -- I just think it sounds nicer :)

jakelishman · 2025-01-22T20:26:07Z

The general rule to apply is if the number is under 10, we spell it out

Yeah, this I know, I guess it's just because I usually write "1q gates" (and so on). I'm so used to reading the numerals in this specific case that the words feel funny to me, even though I don't use numerals in other small-number situations.

beckykd

This is great - thanks, Jake!

beckykd · 2025-01-23T15:07:26Z

qiskit/transpiler/layout.py

    The final layout permutation is caused by :class:`~.SwapGate` insertion during
-    the :ref:`routing_stage`. This class provides an interface to reason about these
-    permutations using a variety of helper methods.
+    the :ref:`transpiler-preset-stage-routing`. This class provides an interface to reason about


Suggested change

the :ref:`transpiler-preset-stage-routing`. This class provides an interface to reason about

the :ref:`transpiler-preset-stage-routing`. This class provides an interface to understand

beckykd · 2025-01-23T15:09:48Z

qiskit/transpiler/preset_passmanagers/plugin.py

-Currently, there are 6 stages in the preset pass managers, all of which actively
-load external plugins via corresponding entry points.
+Currently, there are six stages in the preset pass managers, all of which actively
+load external plugins using corresponding entry points.  The following table gives a quick summary


Suggested change

load external plugins using corresponding entry points. The following table gives a quick summary

load external plugins using corresponding entry points. The following table summarizes

beckykd · 2025-01-23T15:10:03Z

qiskit/transpiler/preset_passmanagers/plugin.py

-load external plugins via corresponding entry points.
+Currently, there are six stages in the preset pass managers, all of which actively
+load external plugins using corresponding entry points.  The following table gives a quick summary
+of each stage.  For more details on the description and expectations of each stage, follow the link


Suggested change

of each stage. For more details on the description and expectations of each stage, follow the link

each stage. For more details on the description and expectations of each stage, follow the link

beckykd · 2025-01-23T15:10:21Z

qiskit/transpiler/preset_passmanagers/plugin.py

@@ -35,66 +37,55 @@
 Plugin Stages
 =============

-Currently, there are 6 stages in the preset pass managers, all of which actively
-load external plugins via corresponding entry points.
+Currently, there are six stages in the preset pass managers, all of which actively


Suggested change

Currently, there are six stages in the preset pass managers, all of which actively

There are six stages in the preset pass managers, all of which actively

beckykd · 2025-01-23T15:17:58Z

qiskit/transpiler/__init__.py

+pipeline is a :class:`.PassManager` object, whose :meth:`.PassManager.run` method takes in a
+:class:`.QuantumCircuit` and converts it to a :class:`.DAGCircuit`, then subjects the IR to a sequence
+of *passes*, finally returning a :class:`.QuantumCircuit` back.  A pass is either an
+:class:`.AnalysisPass`, whose purpose is to calculate and store properties about the circuit in the


Suggested change

:class:`.AnalysisPass`, whose purpose is to calculate and store properties about the circuit in the

:class:`.AnalysisPass`, which calculates and stores properties about the circuit in the

beckykd · 2025-01-23T17:15:41Z

qiskit/transpiler/__init__.py

+At optimization level 0, the stage is empty.
+
+At optimization level 1, the stage does matrix-based resynthesis of runs of 1q gates, and very
+simply symbolic inverse cancellation of two-qubit gates, if they appear consecutively.  This runs


Suggested change

simply symbolic inverse cancellation of two-qubit gates, if they appear consecutively. This runs

simple symbolic inverse cancellation of two-qubit gates, if they appear consecutively. This runs

beckykd · 2025-01-23T17:18:32Z

qiskit/transpiler/__init__.py

+
+The scheduling stage, if requested, is responsible for inserting explicit :class:`~.circuit.Delay`
+instructions to make idle periods of qubits explicit.  Plugins may optionally choose to do
+walltime-sensitive transformations, such as inserting dynamical decoupling sequences.


Suggested change

walltime-sensitive transformations, such as inserting dynamical decoupling sequences.

wall clock time-sensitive transformations, such as inserting dynamical decoupling sequences.

beckykd · 2025-01-23T17:19:24Z

qiskit/transpiler/__init__.py

+      - Attempt to satisfy timing alignment constraints without otherwise scheduling.
+
+    * - :ref:`alap <transpiler-preset-stage-scheduling-alap>`
+      - Schedule the circuit preferring operations to be as late as possible.


Suggested change

- Schedule the circuit preferring operations to be as late as possible.

- Schedule the circuit, preferring operations to be as late as possible.

beckykd · 2025-01-23T17:19:37Z

qiskit/transpiler/__init__.py

+      - Schedule the circuit preferring operations to be as late as possible.
+
+    * - :ref:`asap <transpiler-preset-stage-scheduling-asap>`
+      - Schedule the circuit preferring operations to be as soon as possible.


Suggested change

- Schedule the circuit preferring operations to be as soon as possible.

- Schedule the circuit, preferring operations to be as soon as possible.

beckykd · 2025-01-23T17:20:16Z

qiskit/transpiler/__init__.py

+
+Do nothing, unless the circuit already contains instructions with explicit timings.  If there are
+explicitly timed operations in the circuit, insert additional padding to ensure that these timings
+satisfy the alignment and other constraints of the hardware.


Suggested change

satisfy the alignment and other constraints of the hardware.

satisfy the alignment and other hardware constraints.

jakelishman added documentation Something is not clear or an error documentation stable backport potential The bug might be minimal and/or import enough to be port to stable labels Jan 7, 2025

jakelishman requested a review from a team as a code owner January 7, 2025 17:53

jakelishman requested review from Eric-Arellano, abbycross and beckykd January 7, 2025 17:54

jakelishman added the Changelog: None Do not include in changelog label Jan 7, 2025

Fix cross references in release notes

1f8ed6e

ElePT reviewed Jan 9, 2025

View reviewed changes

jakelishman and others added 2 commits January 21, 2025 15:00

Merge remote-tracking branch 'ibm/main' into doc/transpiler-plugins

34c1567

Include Elena's suggestions

adacfe9

Co-authored-by: Elena Peña Tapia <[email protected]>