Improve transpiler documentation

[mtreinish]

Summary

This commit expands the module documentation for the qiskit.transpiler module to explain details of working with preset pass managers and how to modify stages for custom workflows. It also updates some of the details about the stages which were a bit stale on the exact behavior of the transpiler.

Details and comments

[qiskit-bot]

Thank you for opening a new pull request.

Before your PR can be merged it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient.

While you're waiting, please feel free to review other open PRs. While only a subset of people are authorized to approve pull requests for merging, everyone is encouraged to review open pull requests. Doing reviews helps reduce the burden on the core team and helps make the project's code better for everyone.

One or more of the the following people are requested to review this:

• @Qiskit/terra-core

[coveralls]

Pull Request Test Coverage Report for Build 4016054745

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 2 unchanged lines in 1 file lost coverage.
• Overall coverage increased (+0.03%) to 84.935%

---

Files with Coverage Reduction	New Missed Lines	%
src/sabre_swap/layer.rs	2	98.95%

Totals
Change from base Build 4010423670:	0.03%
Covered Lines:	66703
Relevant Lines:	78534

---

💛 - Coveralls

[jakelishman]

This looks like a good (and probably a bit overdue!) change to the documentation to me. I've left some typo fixes and stuff like that.

I was commenting more on some of the stuff in the scheduling stage, then I realised that it was just unchanged from the previous version, so we don't necessarily try to fix everything about it in a single PR right now.

[jakelishman]

This documentation is a bit misleading - the currentmodule is qiskit.transpiler.preset_passmanagers, but these functions aren't actually available from that namespace. We either need to change the module for the documentation of these, or import them into the top-level namespace (my preferred choice - I like packages to properly define a public API, and not require users to go searching in the code for the module stuff happens to be defined it).

[mtreinish]

I was on the fence about re-exporting it form the root here. I opted to not do it in this PR since I wanted to leave this as purely documentation changes. But I can add it if you think it's necessary here. Otherwise I think we can do this in a follow up PR. TBH, I'm not really sure why I didn't re-export these functions when I added these in #6403.

[jakelishman]

The first sentence says "two parts", but the rest of the paragraph makes it sound like a minimum of three components to me.

[des137]

Hi @mtreinish and @jakelishman,

Related to this, in the transpiler documentation page, under "Mapping circuits to hardware topology", the "bad" initial_layout fails to create a wider distribution of depths.

Essentially, all the different iterations lead to depth=16. Given that the point of that section is to demonstrate a wider distribution in the depths of the transpired circuits, I believe it needs to corrected.

Please let me know if I should create a separate issue for this. Thanks.

[mtreinish]

Thanks for pointing that out, I hadn't realized that I expect it maybe an artifact of changing the default algorithm to SabreSwap and it now converging on the same solution regardless of seed. I need to fix lint on this anyway I'll modify the example to have it better show the stochastic nature of the routing algorithm.

[mtreinish]

I updated the examples in: 2b7e998 and it is showing more of a distribution now:

[kdk]

Up to the Routing section, these sections looks great.

[kdk]

It seems like we're using backend, target and target backend interchangeably throughout. Is there a distinction to be made between them?

[mtreinish]

In this context not so much, there is a distinction between a Target and a Backend (as in the classes) but for the purposes of the transpiler module, pass managers, and pass managers the target, backend, and target backend I was referring to the the same thing (the compilation target backend).

[kdk]

Similarly, this will likely be outdated following #9417 .

[mtreinish]

Yeah, after this merges we should make a note to update this doc after when #9417 is fixed

[kdk]

❤️

[kevinhartman]

#MyLifeIsNPHard

[kdk]

Suggested change

	keyword argument, where the index labels the virtual qubit in the circuit and the
	corresponding value is the label for the physical qubit to map onto:
	keyword argument where the index labels the virtual qubit in the circuit and the
	corresponding value is the label for the physical qubit to map onto:

This has to be the hardest-to-describe kwarg input format in all Qiskit. Maybe something like "where each integer specifies a physical qubit index onto which the corresponding virtual qubit (following the order in circuit.qubits will be mapped"?

[mtreinish]

Heh, I know the array of physical bits is Paul's preferred input format (I'm also fond of it too). But initial_layout supports like every way imaginable to describe the mapping. It might make more sense to use the dict format:

{ghz.qubits[0]: 3, ghz.qubits[1]: 4. ghz.qubits[2]: 2}

which is a bit easier to describe.

[kdk]

Agree, and I think the example below does a good job of clarifying the format should be used. I'm just wondering if there's a clearer text explanation we can give (but I wouldn't be surprised if not, there isn't one in e.g. the transpile docstring).

[kevinhartman]

Partially reviewed, more to come. Adding comments so far to reduce conflicts with other reviewers.

[kevinhartman]

Suggested change

	When writing a quantum circuit you are free to use any quantum gate (unitary operator) that
	you like, along with a collection of non-gate operations such as qubit measurements and
	reset operations. However, when running a circuit on a real quantum device one no longer
	has this flexibility. Due to limitations in, for example, the physical interactions
	between qubits, difficulty in implementing multi-qubit gates, control electronics etc,
	a quantum computing device can only natively support a handful of quantum gates and non-gate
	operations. The allowed instructions for a given backend can be found by querying the
	:class:`~.Target` for the devices:
	Users are free to write quantum circuits using any quantum gate (unitary operator) in addition
	to non-gate operations such as qubit measurements and reset operations. However, when
	running a circuit on real quantum hardware, these operations must be translated to the native
	set of operations supported by the device, which is often limited. The allowed instructions for a
	given backend can be found by querying the :class:`~.Target` for the devices:

[kevinhartman]

Suggested change

	We have :math:`H`, :math:`X`, and controlled-:math:`P` gates, all of which are
	not in our devices basis gate set, and must be expanded. This expansion is taken
	care of for us in the :func:`qiskit.execute` function. However, we can
	decompose the circuit to show what it would look like in the native gate set of
	the IBM Quantum devices (the :class:`~.FakeVigoV2` backend is a fake backend that
	models the historical IBM Vigo 5 qubit device for test purposes):
	We have :math:`H`, :math:`X`, and controlled-:math:`P` gates, none of which are
	in our device's basis gate set, and thus must be expanded. This expansion is taken
	care of for us in the :func:`qiskit.execute` function. However, we can
	decompose the circuit to show what it would look like in the native gate set of
	the IBM Quantum device (the :class:`~.FakeVigoV2` backend is a fake backend that
	models the historical IBM Vigo 5 qubit device for test purposes):

[kevinhartman]

Suggested change

	As a product of three CNOT gates, swap gates are expensive operations to perform on a
	noisy quantum devices. However, such operations are usually necessary for embedding a
	circuit into the limited entangling gate connectivities of actual devices. Thus,
	minimizing the number of swap gates in a circuit is a primary goal in the
	transpilation process.
	Swap gates are expensive operations to perform on a noisy quantum devices because
	each one is decomposed to three CNOT gates. However, swaps are usually necessary
	for embedding a circuit to match the limited connectivity of actual devices.
	Thus, a primary goal of the transpilation process is to minimize the number of swap gates
	required to make the circuit compatible with the target device.

[kevinhartman]

LGTM

[itoko]

Overall LGTM. I have one comment on Overview section. When I first read it, I was a bit confused about the misalignment between "steps" in the first figure and "stages" defined in preset pass manager. Some reader would expect one-on-one mapping between the six steps in the figure and the six stages in the main text but in fact the first two steps will be implemented in the init stage and there is no step corresponding to scheduling stage in the figure. The "steps" seems a classification of transpiler tasks (often seen in the transpiler research literature) and the "stages" is a grouping of their implementations (passes) in Qiskit. I think a little more explanation something like above things might be helpful for novice readers.

[kdk]

Last few comments, then looks good to me! Didn't review through the Scheduling section as I think it was unchanged.

[kdk]

Agree, and I think the example below does a good job of clarifying the format should be used. I'm just wondering if there's a clearer text explanation we can give (but I wouldn't be surprised if not, there isn't one in e.g. the transpile docstring).

[kdk]

True, but even with translation, there are the unroll and synthesis methods which we could highlight here, likewise routing has stochastic and lookahead. I suppose I'm saying if we're going to document the pass behaviors and available *_method options for layout here, we should do the same for translation and routing.

As an alternative, the documentation here could be at the level of "here are the default stages and the problems they solve" and then for folks to understand the implementation of those stages at each optimization level, we could move the descriptions of the passes being run (and corresponding *_method options) to the documentation of the preset pass manager generators.

[kdk]

Thanks for the updates, LGTM.