docs(notebooks): add qubit-mapping guide

[haimeng-zhang]

Add qubit-mapping how-to guide to introduce the routing and layout transpiler stages.

Details and comments

Need dependence on package mapomatic

[pedrorrivero]

Thanks @haimeng-zhang!

Would you mind creating a notebooks directory inside of docs and placing yours inside? (i.e. ./docs/notebooks/<NOTEBOOK>)

[pedrorrivero]

Thanks @haimeng-zhang and @nathanearnestnoble! A couple of changes:

• Please open one PR per notebook. Generally speaking PRs should do only one thing.
• Please add the notebooks inside of a (new) ./docs/notebooks/ directory.

[pedrorrivero]

Hi @haimeng-zhang can you check that this notebook runs with a freshly created environment and only this repo installed from source? Please make sure to install the notebook optional dependencies.

Since Friday, this should be equivalent to Qiskit 1.0.0. You will need to rebase this branch to main, let me know if you need help.

If you need additional dependencies please flag.

[coveralls]

Pull Request Test Coverage Report for Build 8940873145

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

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 100.0%

---

Totals
Change from base Build 8708380490:	0.0%
Covered Lines:	290
Relevant Lines:	290

---

💛 - Coveralls

[pedrorrivero]

@haimeng-zhang can we remove the word "guide" from the filename?

@ashsaki please have this review by end of day tomorrow so that Haimeng has time to integrate your suggestions and we can merge on Friday.

[ashsaki]

I suggest we use optimization_level=3. Avoiding stochastic process is not a strong reason. Also, optimization_level=2 can be stochastic. SabreSwap is used as the routing method for both level $2$ and level $3$.

[ashsaki]

Two bullets - one circle and one square - in the same line.

[haimeng-zhang]

Fixed! Thanks!

[ashsaki]

"Step $2$" appears twice. This should be "Step $3$".

[haimeng-zhang]

Fixed. Thank you!

[ashsaki]

Should be Step $4$.

Also, the default cost function in mapomatic uses only gate errors and readout errors, not state preparation and T1 and T2 errors (GitHub Link).

[haimeng-zhang]

This is a great point! Corrected the original statement about the cost function in mapomatic.

[ashsaki]

Can we use a shorter string? Example"

print(f'Fidelity (unoptimized circuit): {hellinger_fidelity(unoptimized_result, ideal)}')

Fix typo uoptimized --> unoptimized.

[ashsaki]

Suggest a shorter sentence.

print(f'Fidelity (optimized circuit with mapomatic): {hellinger_fidelity(optimized_result, ideal)}')

[ashsaki]

Mapomatic is included in Qiskit transpiler's present pass managers (as VF2Layout or VF2PostLayout) for all optimization_levels except 0.

I think we should mention it somewhere in the notebook. Maybe, we can borrow the rationale befind using standaalone mapomatic from mapomatic's GitHub.

[ashsaki]

[General comment; not a correction request]
There are no SWAP gates in the output circuit (ghz_pm). It potentially means the layout stage found a perfect layout using the VF2Layout (Link) pass. As VF2Layout accounts for backend errors automatically, the output circuit was mapped to good qubits. This is a possible reason behind fidelities for unoptimized and optimized circuits being very similar.

[ashsaki]

Circuit names can be more cohesive.

Some suggestions:

ghz_5q
ghz_5q_routed
ghz_5q_routed_translated
ghz_5q_routed_translated_df
ghz_5q_mapped or ghz_5q_mapomatic

[itoko]

Thank you for preparing a useful notebook. I've found two small but critical typos.

[itoko]

Suggested change

	"|\\psi_{\\rm GHZ}\\rangle = \\frac{1}{\\sqrt{2^n}} \\left( |0\\rangle^{\\otimes n} + |1\\rangle^{\\otimes n} \\right)\n",
	"|\\psi_{\\rm GHZ}\\rangle = \\frac{1}{\\sqrt{2}} \\left( |0\\rangle^{\\otimes n} + |1\\rangle^{\\otimes n} \\right)\n",

The coefficient must be 1/sqrt(2), not 1/sqrt(2^n).

[itoko]

optimized -> unoptimized

I'm talking about the lines below:

plot_histogram(
    [result for result in [sim_result, optimized_result, unoptimized_result]],
    bar_labels=False,
    legend=[
        "ideal",
        "optimized",
        "optimized",
    ],
)

(note: I don't know why but wrong line is shown above)

[itoko]

@haimeng-zhang @pedrorrivero I'd like to use this notebook in a lecture at a university this June, so I'm happy if this PR is merged by the end of May.

[a-matsuo]

It may be little difficult to understand the structure of the notebook. I suggest making the section names a little longer or assigning numbers to them. It might be a good idea to make the notebook to follow the Qiskit pattern.

[a-matsuo]

"heuristic algorithms" might be a better word to describe these algorithms instead of stochastic algorithms.

[a-matsuo]

How about "Example with larger circuits" instead of "Bigger circuits"? I think each section title is little too short, e.g. "Start", "Build" and so on.