2274 Benchmark User Guide

[Shivansh20128]

Description

This PR adds a user guide section for benchmarks.
Closes issue #2274

---

License

• I license this contribution under the terms of the GNU GPL, version 3 and grant Unitary Fund the right to provide additional permissions as described in section 7 of the GNU GPL, version 3.

Before opening the PR, please ensure you have completed the following where appropriate.

• I added unit tests for new code.
• I used type hints in function signatures.
• I used Google-style docstrings for functions.
• I updated the documentation where relevant.
• Added myself / the copyright holder to the AUTHORS file

[github-actions]

Hello @Shivansh20128, thank you for submitting a PR to Mitiq! We will respond as soon as possible, and if you have any questions in the meantime, you can ask us on the Unitary Fund Discord.

[Shivansh20128]

Hi! Can someone review this draft PR and reply if this is the kind of documentation the project needs? I will then add the rest of it accordingly.
Thank You

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.73%. Comparing base (3315184) to head (3701a61).
Report is 15 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2566   +/-   ##
=======================================
  Coverage   98.72%   98.73%           
=======================================
  Files          92       92           
  Lines        4168     4176    +8     
=======================================
+ Hits         4115     4123    +8     
  Misses         53       53           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[natestemen]

@Shivansh20128 this is exactly the kind of thing we're looking for!

[Shivansh20128]

@purva-thakre Can you tell me why this error is coming in the checks performed? This is a different one from the previous check error, which I have linked to an open issue. I don't think its related to the changes I have made, so maybe I am just unlucky to encounter two tests failing non-deterministically🥲 for the two pushes I have made.

[cosenal]

@Shivansh20128 https://github.com/unitaryfund/mitiq/actions/runs/11801809295/job/32876002160?pr=2566 is definitely unrelated to your changes, but it's not even a test that fails non-deterministically, or has anything to do with Mitiq. It looks like Python panicked when calling some core routine written in Rust 😱 Interesting, but definitely not in the scope of this PR 😄

[Shivansh20128]

It looks like Python panicked when calling some core routine written in Rust 😱 Interesting, but definitely not in the scope of this PR 😄

Aahh. Okay. Thank you

[Shivansh20128]

I think the error in the docs-build will be resolved once #2570 is merged.

[cosenal]

Overall this is what we had in mind.
I agree with @purva-thakre that a snippet on how to use each circuit type would make the user guide too heavy, so let's leave only the small demo at the top.
I left some comments throughout the PR, looking forward to the next iteration.

[Shivansh20128]

Overall this is what we had in mind. I agree with @purva-thakre that a snippet on how to use each circuit type would make the user guide too heavy, so let's leave only the small demo at the top.

@cosenal Just to make sure, you want to remove the all the code snippets from the circuits and leave just the one at the top?

from mitiq.benchmarks import generate_ghz_circuit

circuit = generate_ghz_circuit(n_qubits=7)

So shall I remove all the blocks like these?

[cosenal]

Overall this is what we had in mind. I agree with @purva-thakre that a snippet on how to use each circuit type would make the user guide too heavy, so let's leave only the small demo at the top.

@cosenal Just to make sure, you want to remove the all the code snippets from the circuits and leave just the one at the top?

from mitiq.benchmarks import generate_ghz_circuit

circuit = generate_ghz_circuit(n_qubits=7)

So shall I remove all the blocks like these?

No, those small snippets on how to generate the circuits are good. What I meant is that we shouldn't have snippets running error mitigation for each class of circuits.

[purva-thakre]

What I had in mind for how each section describing a benchmarking circuit might look like is shown below. Right now, the details pertaining to each circuit are lacking.

We can discuss this during the community call.

w_state_outline.txt

Edit: Note that we don't use $G(p)$ exactly as defined in the paper. There should be a line or two discussing these changes as well.

mitiq/mitiq/benchmarks/w_state_circuits.py

Lines 38 to 44 in edeede6

	for i, j in zip(range(0, n_qubits), range(1, n_qubits)):
	N = n_qubits - i
	angle = 2 * np.arccos(np.sqrt(1 / N))
	circuit.append(
	cirq.Ry(rads=angle).controlled().on(qubits[i], qubits[j])
	)
	circuit.append(cirq.CNOT(qubits[j], qubits[i]))

[purva-thakre]

I suggested some changes. @Shivansh20128 let me know if you have the time to work on these.

If not, I can take over.

[purva-thakre]

It might be better to show an example code block.

[purva-thakre]

Most of the benchmarking circuit docstrings have a link to some reference that was used to define the function. Could you please mention these in the circuit descriptions?

https://mitiq.readthedocs.io/en/stable/apidoc.html#module-mitiq.benchmarks.mirror_circuits

The W-state outline txt file contains an example of how to use {cite} for the references listed in docs/source/refs.bib

[Shivansh20128]

I suggested some changes. @Shivansh20128 let me know if you have the time to work on these.

Okay. I will make the changes.

[Shivansh20128]

Hi @purva-thakre , I have added an example code block for the generate_mirror_circuit.

I have also added references for the benchmarking circuits wherever I could find them in the API-doc.

[cosenal]

Left a small comment. The rest looks good to me.

[cosenal]

This description sounds the same as the QV one; instead, it should be noticed that here mirror quantum volume circuits are generated with the same definition of mirroring as above.

[Shivansh20128]

Done!