Increase documentation of built-in transpiler plugins

[jakelishman]

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.

[qiskit-bot]

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

• @Qiskit/terra-core

[jakelishman]

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]

Pull Request Test Coverage Report for Build 13160133967

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.
• 365 unchanged lines in 25 files lost coverage.
• Overall coverage decreased (-0.2%) to 88.659%

---

Files with Coverage Reduction	New Missed Lines	%
crates/circuit/src/dag_circuit.rs	1	89.36%
crates/accelerate/src/unitary_synthesis.rs	1	92.97%
qiskit/providers/fake_provider/fake_backend.py	1	85.51%
crates/qasm2/src/expr.rs	1	94.23%
qiskit/providers/basic_provider/basic_provider_tools.py	1	83.33%
crates/circuit/src/operations.rs	1	89.61%
qiskit/pulse/transforms/canonicalization.py	1	93.44%
qiskit/pulse/transforms/base_transforms.py	2	86.96%
qiskit/pulse/schedule.py	3	88.6%
qiskit/result/result.py	3	83.74%

Totals
Change from base Build 13118695608:	-0.2%
Covered Lines:	79024
Relevant Lines:	89133

---

💛 - 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 :)

[jakelishman]

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]

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

[jakelishman]

"reason about" here I think is meaning more about the idea of using programmatic logic on the output, rather than a user sitting and thinking - "understand" isn't quite right, but "reason about" is something we say

[beckykd]

Suggested change

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

[jakelishman]

"walltime" is an equally common spelling of this, and I think we'd end up with "wall-clock-time-sensitive" if we did that, which seems a bit verbose

[ElePT]

Thanks a lot Jake, this is a great improvement on the previous docs. I managed to finally finish reading it and suggested a few minor changes, other than that LGTM.

[ElePT]

maybe we could also introduce "physical qubits" here, or is this a term we prefer to avoid? (I never keep up with these trends)

[jakelishman]

In the qiskit.circuit documentation, we define "physical qubit" to be one type of "hardware qubit" (the other is a "logical qubit"). In those terms, the compiler deals in "hardware qubits", because it doesn't care if the Target was presented as a low-level Target (as it always is right now) or a logical-qubit Target (as it one day may be).

[ElePT]

I just learned something new

[jakelishman]

ha yeah - I've seen too many people struggle with this, so I thought it was useful to call it out

[ElePT]

I was just going to comment on this (I was looking at the rendered version), good clarification.

[ElePT]

LGTM! I will not add the PR to the queue yet in case @beckykd has any final comments, but I think it's good to merge.

[mtreinish]

Overall this LGTM too, I left a few small questions inline but nothing worth blocking over. If you don't feel there is anything to change related to my questions I think we can enqueue this for merging.

[mtreinish]

This implies the intent to change this in Qiskit 2.0? Is there a tracking issue or PR for this? I worry if we're not tracking it < 1 month away from the feature freeze we'll lose the thread on this.

[jakelishman]

I'm planning on doing it - I've got it written on my todo list. I've opened a proper tracking issue at #13787.