Increase documentation of built-in transpiler plugins #13620
Conversation
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.
jakelishman
added
documentation
|
One or more of the following people are relevant to this code:
|
|
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. |
Pull Request Test Coverage Report for Build 12657127421Details
💛 - Coveralls |
| :class:`.StagedPassManager`, which allows greater configuration of the individual stages of a | ||
| tranpsilation. | ||
|
|
||
| A preset pass manager has up to six named stages. These are summarized, in order of execution, |
There was a problem hiding this comment.
I think we should also briefly mention the ability to add pre_ and post_ stages, maybe as a note at the end of this section? The pre_layout stage is used later in an example but I didn't find it being introduced anywhere in the text.
There was a problem hiding this comment.
Shall I put that documentation into the bit about StagedPassManager further down the page?
Imo the preset pass managers shouldn't use the pre_ and post_ sections themselves at all, since that defeats their purpose for configuration; if we use them, we've de facto made that its own stage. But I think we need to re-jig the construction a little bit to make that true; at the moment, we do use them.
| optimizations; only transformations needed to make the circuit runnable at all will be present. On | ||
| the other end, level 3 enables a full barrage of optimization techniques, some of which can be very | ||
| expensive in compilation time. Similar to classical compilers, optimization level 3 is not always | ||
| guaranteed to produce the best results. Qiskit defaults to optimization level 2. |
There was a problem hiding this comment.
Should we explicitly argue why we chose level 2? I am thinking something like:
| guaranteed to produce the best results. Qiskit defaults to optimization level 2. | |
| guaranteed to produce the best results. Qiskit defaults to optimization level 2, | |
| which offers a balanced tradeoff between compilation time and the expected level of circuit optimization. |
I understand that the wording here can be tricky, so no need to apply the suggestion.
| backend = QiskitRuntimeService().backend("some-backend") | ||
|
|
||
| # Create the pass manager for the transpilation ... | ||
| pm = generate_preset_pass_manager(backend=backend) |
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
Summary
This overhauls how the
qiskit.transpilerdocumentation 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
defaultplugins) 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.