Add tutorial notebook for M3 readout mitigation

[jlapeyre]

This tutorial presents an application of qiskit-addon-mthree, the "Matrix-free Measurement Mitigation (M3)" technique. (It is actually readout mitigation). The technique is applied to a simple hidden shift problem

In particular, we follow citation 5 in the article linked above (arXiv).

This PR was co-authored by @kevinsung

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[jlapeyre]

I made many changes to satisfy CI errors.

The most recent error occurs in parsing the notebook. But the location or nature of the error is not included in the error messages. I suppose I could look for another tool to parse the notebook and hope that it errors and that it gives informative error messages.

[abbycross]

Hi @jlapeyre! I've been trying to debug this by using a local preview, and removing chunks of the notebook at a time then trying to see what renders....I can get the notebook to render just fine if I remove everything between "Theoretical background" and "Requirements" 🤣 but it's very unclear what exactly is causing the error. The "unexpected character" it complains about is not immediately apparent. I suspect it has something to do with LaTeX/KaTeX?? Possibly the \newcommands? Sorry I can't be of more help...

[jlapeyre]

@abbycross , thanks for looking at this. I have no problem rendering the notebook locally, just running the notebook server. At least I don't see an obvious mistake.

I also can view it here: https://github.com/jlapeyre/documentation/blob/mthree-tutorial/docs/tutorials/readout-error-mitigation-sampler.ipynb

But a tool (called "acorn" I think) seems to be unable to parse it:

Error: Problem parsing 'docs/tutorials/readout-error-mitigation-sampler.ipynb':
Could not parse expression with acorn: Unexpected content after expression
    at parseFile (/home/runner/work/documentation/documentation/scripts/js/lib/links/extractLinks.ts:137:11)

Either the location in the notebook file of the parse error is not available, or it is somehow suppressed.

Is there a way I can run this tool locally?

EDIT:
I think I misunderstood. Maybe it is this: You are not looking at the notebook using Jupyter. Instead, you are using whatever tool chain is set up here to turn this into static web pages. It is this tool chain that is having trouble rendering. If I want to do this locally, it looks like I need a few things such as Docker and Node.js

[abbycross]

Yes - you can follow the README for instructions. Also, once we fix this 😆 you will want to do the following (or I can help with these):

• you'll want your first code cell to contain imports for the whole notebook (and remove them elsewhere) - otherwise a check will fail.
• Run .\fix to automatically convert output images to .avif (see more about our checks in the README)
• Add the file name to the notebook-testing.toml file, under the comment "We never run tutorials notebooks" (should be around line 164)

I think I see that the \CZ command isn't defined - is it possible that's blowing it all up? 💥

[jlapeyre]

Thanks. I started with the README. I already have nodejs installed. I'm hoping I can just run the javascript script that is reporting the error, without going down the container path.

I think I see that the \CZ command isn't defined

This sounds like a great idea. Makes sense that most tools skip it in order to let the user get something done. But the doc building CI should be less tolerant.

WAIT: I do have this:

\DeclareMathOperator{\CZ}{CZ}

Maybe it's not supported. I can try just \newcommand.

[jlapeyre]

Tried changing the definition for \CZ. There is still an error. I'll try to see if I can run the internal link checker locally.

[abbycross]

I was finally able to get the entire notebook to pass all checks locally when I got rid of all the \newcommands and \DeclareMathOperator (I searched for all the new commands in use and replaced them with their long form), and I found a set of $$s enclosing a \begin{equation}. In case the latter is the thing breaking it all, I'm checking it here first to see if you get a different error if all I do is remove those redundant double dollar signs.

[abbycross]

Ok, that didn't seem to fix it. Would you like me to commit my local changes to your branch? You'll want to do a really close reading of it, if so, to make sure all the symbols/expressions look as they need to, after my changes... but at least it would save you doing the search and replace for all the \newcommands...