Added a How-To guide for transpiler optimization level

[MaldoAlberto]

Summary

Documentation of the optimization_level parameter in the transpile method, taking as reference #8574

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:

• @Eric-Arellano
• @HuangJunye
• @javabster
• @Qiskit/terra-core

[javabster]

Thanks for your submission @MaldoAlberto, a few things need to be tidied up then I'll do a proper content review:

Firstly, the file structure needs a bit of a rework. We keep all the how to guides in the docs/how_to folder, so the main .rst file should be moved there. Also the images should be kept in the docs/source_images folder.

Secondly, it looks like CI is failing for the docs build. Taking a look at the logs it says WARNING: document isn't included in any toctree. I think this is probably because you need to move the files into the right folder as I mentioned above. In addition you will need to add the file name for the new how to guide to docs/how_to/index.rst

[MaldoAlberto]

Thanks @javabster I did the changes

[coveralls]

Pull Request Test Coverage Report for Build 5764174047

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 2394 unchanged lines in 144 files lost coverage.
• Overall coverage decreased (-0.06%) to 85.917%

---

Files with Coverage Reduction	New Missed Lines	%
crates/accelerate/src/sabre_layout.rs	1	99.43%
crates/qasm2/src/lex.rs	1	92.15%
qiskit/circuit/commutation_checker.py	1	98.51%
qiskit/circuit/library/n_local/efficient_su2.py	1	94.74%
qiskit/circuit/library/n_local/excitation_preserving.py	1	95.83%
qiskit/circuit/parametertable.py	1	88.19%
qiskit/opflow/gradients/qfi.py	1	95.65%
qiskit/quantum_info/operators/base_operator.py	1	98.08%
qiskit/quantum_info/operators/mixins/adjoint.py	1	92.86%
qiskit/quantum_info/operators/mixins/multiply.py	1	94.44%

Totals
Change from base Build 5520034869:	-0.06%
Covered Lines:	73086
Relevant Lines:	85066

---

💛 - Coveralls

[MaldoAlberto]

@Eric-Arellano I did new version of the documentation

[atharva-satpute]

Please fix the typo

[Eric-Arellano]

Nice work so far!

[mtreinish]

I left a few suggestions and comments inline about some things that I think need to be updated here. A few of the more mechanical suggestions apply to all the instances (like the sphinx refs in particular), but I only commented on a few at the beginning.

My biggest concerns are around using the legacy BackendV1 interface and some accuracy/clarity issue in some of the statements being made about the differences between the optimization levels. Also I'm a bit worried about using hardcoded doc test examples with output in this doc. The transpiler's output changes is non-deterministic because we use a stochastic algorithm for layout and routing, so the output can change depending on seed. But also using hard coded output like this will go stale anytime we make an improvement to the transpiler which changes the output circuit. In general I think it would be better to use the matplotlib plot directive: https://matplotlib.org/stable/api/sphinxext_plot_directive_api.html for all the visualizations so they're generated on the fly. The overhead of the running this code as part of the sphinx build should be minimal as the circuit is very small so the compilation and visualization will be relatively quick.

That being said while I think some of the content here is largely duplicated in the transpiler module documentation, but I realize the how to section is a different target audience and having some duplication between the two documents is ok as there is a different target audience and entry point people, so I'm glad to see this contribution. Thanks for getting it started.

[Eric-Arellano]

Thanks for the updates! It sounds like this still needs to migrate to a V2 backend.

[Eric-Arellano]

The ~ results in only showing transpile rather than qiskit.compiler.transpile. Imo it is useful to show the whole import path.

Suggested change

	parameter with :func:`~qiskit.compiler.transpile`.
	parameter with :func:`qiskit.compiler.transpile`.

[MaldoAlberto]

that is ok because just put a link in the method, and the oder tutorials use the same format

[MaldoAlberto]

Hi @mtreinish I did the changes your explanation for the different levels help me more to understand the background of this method, so I added a short sentence for this, as this tutorial is more explain how to use optimization level and no education, but is interesting to learn more how is working the code of optimization_level, I'm thinking if is possible explain more in this or in other kind of tutorial

[frankharkins]

Nice work! I've left quite a few comments but most are minor, the only important bits are to do with headings, and a couple of sentences I didn't understand.

[MaldoAlberto]

@frankharkins Thank you so much for all the feedback, I did the changes, I hope is now better :D

[frankharkins]

Thanks! Sorry just a few more comments from me.

[frankharkins]

@MaldoAlberto "considering" is incorrect here, it basically means "think about carefully", so this sentence means "thinking about a trivial layout and stochastic swap".

I'd switch "considering" -> "using".

Suggested change

	When setting the ``optimization_level`` to 0, the resulting quantum circuit is not optimized and simply mapped to the device, considering a trivial layout and stochastic swap.
	When setting the ``optimization_level`` to 0, the resulting quantum circuit is not optimized and simply mapped to the device using a trivial layout and stochastic swap.

[MaldoAlberto]

@frankharkins thank you so much for your nice feedback, explanation and resource 😄 I did the changes

[frankharkins]

Looks great, thanks!

[mtreinish]

This looks great, thanks for all the hard work with all the updates. I think this is basically ready, I just left a couple small inline wording suggestions to make some of the details about the transpiler levels a bit clearer to me.

Other than that I think the only other thing is we can drop most of the testcode blocks that are calling draw. The plot directive has an include-source option that will enable us to display the code side by side with the generated visualization. If the issue is that you want to reuse state between plot calls there is a context option you can use to enable sharing context between calls.

Comments addressed

[MaldoAlberto]

@Eric-Arellano Hi! I son{t know iid is ok this version or I need to do some changeS?