Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update workflow images in documentation #2034

Merged
merged 15 commits into from
Dec 18, 2023
19 changes: 19 additions & 0 deletions docs/CONTRIBUTING_DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,25 @@ where `file.md` is the one to be added. For more information on including files
To add information in the guide, please add markdown (`.md`) files to the `docs/guide` directory.
Remember to add new files to the guide's TOC file `docs/source/guide/guide.md`.

### Adding workflow images to the user guide

To insert a workflow to the user's guide of some new technique, a template is available (shown below as a `png`). This template is also available in `svg` format at [mitiq_template.svg](../source/img/general_template.svg).

The `svg` will require edits to the items listed below:

- One word description of the first step of the new technique in `(Edit Step 1)`. For example, if the new technique
requires sampling of the input quantum program, you will edit the text to `1. Sampling`.
- Make changes to `Description of circuit generated by mitiq` to instead briefly provide information about how mitiq is manipulating the input circuit.
- Feel free to change the color scheme in `mitiq.new_technique` of the `svg` file.

```{figure} ../source/img/mitiq_workflow_template.png
---
name: fig-overview-template
---
The diagram shows the workflow template of a new technique in Mitiq.
```


### Adding code examples

All code examples, besides explanations on the use of core software package features, live in the `examples` directory under `docs/source`. You can add
Expand Down
2 changes: 1 addition & 1 deletion docs/source/guide/shadows.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ sample efficiency and demonstrates noise resilience {cite}`chen2021robust`. For
([Classical Shadow Protocol and its Robust Estimation](shadows-5-theory.md)).


```{figure} ../img/shadows_workflow.png
```{figure} ../img/classicalshadow_workflow.png
---
width: 700px
name: shadows-workflow-overview
Expand Down
Binary file modified docs/source/img/classicalshadow_workflow.png
purva-thakre marked this conversation as resolved.
Show resolved Hide resolved
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
617 changes: 617 additions & 0 deletions docs/source/img/classicalshadow_workflow.svg
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • I don't think we "insert [a] noise channel" in the first dark green box, do we?
  • I think it should read mitiq.shadows in the center box instead of mitiq.classicalshadows.

Copy link
Collaborator Author

@purva-thakre purva-thakre Dec 18, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we "insert [a] noise channel" in the first dark green box, do we?

Yes, we do. According to the docs. See step 1 in this section of the docs.

I think it should read mitiq.shadows in the center box instead of mitiq.classicalshadows

Thanks for catching that! I did not double-check the API-doc. Only followed what the previous images stated.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we do. According to the docs. See step 1 in this section of the docs.

That is the "user defined input" section, however. I think that part of the code to ensure we are using a realistic executor. That is not something that happens in the mitiq.shadows module, which this diagram is explaining.

Copy link
Collaborator Author

@purva-thakre purva-thakre Dec 18, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would you prefer to have Insert noisy channel moved to the hardware region?

Otherwise, I don't know how to explain the difference between the workflows for ideal classical shadows and robust shadows. The way I understand it, we use the latter in the former after the device noise is characterized.

OR Step 2 could be changed to Noisy Z-basis measurement where the noise is user-defined or the one characterized from the robust shadows workflow.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see this diagram as explaining what happens under the hood, and I cannot find anywhere in the mitiq.shadows module where we add a noise channel. I can see we apply random Paulis in shadow_quantum_processing, but don't see any insertion/application of a noise channel, which is why I think that part may be unnecessary. If you agree this is the purpose of the image, can you show me where I'm missing this part?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally can't understand the details of robust shadow in Mitiq. I looked at what the main reference of this technique does. https://arxiv.org/abs/2011.09636

Step 7 is where the device noise is characterized.

Steps 8, 9 and 10 are where the classical shadows workflow comes into play.

image

How about I remove the insert noisy channel part and make changes to Step 2? It would then be labeled as Noisy Z-basis measurement.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just in case anyone is following along, Purva and I chatted and agreed her suggestion sounds good. We will go forward with that.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
358 changes: 358 additions & 0 deletions docs/source/img/general_template.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/img/mitiq_workflow_template.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/rshadows_workflow.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
733 changes: 733 additions & 0 deletions docs/source/img/rshadows_workflow.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/img/rshadows_workflow_minli.png
purva-thakre marked this conversation as resolved.
Show resolved Hide resolved
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.