Create workbooks for the katas/tutorials, part 2

[tcNickolas]

(This issue is the second part of #208)

The katas offer a set of programming exercises on quantum computing and reference solutions to them, but we often hear that it would be helpful to have the solutions explained, with the logic steps necessary to arrive from the problem description to the code spelled out. It is especially important for people who go through the katas on their own, without a study group to support them.

To address this, we came up with the idea of "workbooks" - explanations of the solutions to the tasks offered in the katas/tutorials, written in Jupyter Notebook format. You can check any of the workbooks completed in #208 to get an idea of what the workbooks look like.

Here are the katas and tutorials that don't have a workbook yet and seem like a good fit for one.

• BasicGates (@TonyHoldroyd)
• GraphColoring, part IV triangle-free coloring
• KeyDistribution_BB84 (@devikamehra)
• MagicSquareGame
• MarkingOracles
• PhaseEstimation
• QEC_BitFlipCode
• QFT (@WaywardPhoton)
• RippleCarryAdder (@Parisha-Agrawal)
• SuperdenseCoding
• Teleportation
• TruthTables (tasks 1-8 @olstulo, tasks 9-10 @tcNickolas)
• tutorials/Oracles
• tutorials/RandomNumberGeneration (@ssc1729)

[born-2learn]

I would love to work on them, @tcNickolas. Will it be okay if I move with a slow pace for these?

[tcNickolas]

@born-2learn Sure! Usually I recommend to pick one workbook to work on and claim it, so that if somebody else wants to take another one, they can; once that one is complete, can pick another one if you want, and so on. The #208 took about a year to complete :-) (though it had more workbooks in it)

[born-2learn]

@tcNickolas Alright, I would like to try out the Phase Estimation workbook then.

[WaywardPhoton]

@tcNickolas Is there anything I can work on? I'd be happy to create a workbook for QFT if that is something that would be needed. It seems like there isn't one currently available.

[tcNickolas]

Hi Ana, Absolutely! I'm not aware of anybody else working on the QFT kata workbook, so you're welcome to it! Please let me know if you need any help from me to get started.

…

On Fri, May 28, 2021 at 9:22 PM Ana Madalena ***@***.***> wrote: @tcNickolas <https://github.com/tcNickolas> Is there anything I can work on? I'd be happy to create workbooks for QFT if that is something that would be needed. It seems like there isn't one currently available. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#542 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACNFAAEIR5PIUQH3NBY2U2DTQBTZZANCNFSM4S2RPEBA> .

[WaywardPhoton]

@tcNickolas I'd love some general guidelines on content. I know that the solution already exists (and all I have to do is explain it) but if there is anything specific that explanations are required to have I'd like to know!
Oh! and also, where to submit the notebook when finished :)

[tcNickolas]

The best way to get an idea of how the workbook should look is probably checking out the ones for other katas. Typically we want to explain the way to come to the solution mathematically, and then to highlight some Q# features/library operations that come in handy but can be not obvious for someone who is just getting started with the language.

…

On Sat, May 29, 2021 at 2:51 PM Ana Madalena ***@***.***> wrote: @tcNickolas <https://github.com/tcNickolas> I'd love some general guidelines on content. I know that the solution already exists (and all I have to do is explain it) but if there is anything specific that explanations are required to have I'd like to know! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#542 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACNFAACJWBVTUQ42F4FTZBTTQFOV7ANCNFSM4S2RPEBA> .

[tcNickolas]

Hi @born-2learn and @WaywardPhoton,
Are you still working on the PhaseEstimation and QFT workbooks, respectively? Let me know if you want to drop them or need any help from me - I finally have a little breathing room compared to the past few months, and hope to catch up on the open source work on the Katas in the next few weeks!

[WaywardPhoton]

Hi, yes, I am almost done the QFT. Has been a busy two weeks with school.
Just doing some research to figure out part 3. I can send you what I have if you want.

[tcNickolas]

@WaywardPhoton
Oh, I forgot we had part 3 in the QFT kata at all! You can definitely skip that one, those are tasks from the Q# Coding Contest #3 and they're pretty advanced. We have writeups of the solutions at https://assets.codeforces.com/rounds/1357/problems-e1e2-2.pdf, so I'll be able to hunt down the sources from which we generated that pdf and to reuse them, or to upload the pdf as a whole and use it as is.

If you have parts 1 and 2, please feel free to send the pull request and I'll take a look next week. We'll deal with part 3 later.

[WaywardPhoton]

Gone ahead and made the pull request. Thanks!

[TonyHoldroyd]

@tcNickolas Ciao, I should like to either: develop a workbook for the Quantum BasicGates kata, or: develop a kata for the Classical language features of Q# (possibly subdidivided into smaller programmatical logical units) , as per your notifications. As far as I can tell, nobody has taken these on yet.Please would you kindly let me know which, if either, of these, (or both in the fullness of time) you would support for my first foray into MS documentation development. Thankyou Mariia..

[tcNickolas]

@TonyHoldroyd I'll be happy to support you in both of these endeavors! I recommend starting with the workbook for the BasicGates kata, since it is a well-defined work. Meanwhile I'll think about the way to organize the classical features kata and open a new issue for it - it's been on the roadmap forever and I never got to writing that down (thank you for the reminder!!) It seems that it can be very modular but probably not to the point of having separate katas for each of the variables, loops, conditional branching, etc.

[TonyHoldroyd]

@tcNickolas Thank you very much for your rapid response Mariia. A workbook for the BasicGates kata it is, then. I'll get right on it.

[TonyHoldroyd]

@tcNickolas About the scopes of the individual katas for classical features of Q#: sure thing, I expect logical groupings of the features into around about 4/5 sets might be the order of the day.

[TonyHoldroyd]

@tcNickolas ciao Mariia, to edit the workbooks (and katas) do you recommend working with markdown and Latex directly in Jupyter Notebooks or use some other editor? Thanks

[tcNickolas]

I edit Jupyter Notebooks directly in their environment - they're very convenient in that you can edit the Markdown of the cells and then immediately view it in the same environment, and the same with the code cells, you can write the code and run it in the same place.

…

On Thu, Sep 23, 2021 at 5:49 AM Tony Holdroyd ***@***.***> wrote: Ciao Mariia, to edit the workbooks (and katas) do you recommend working with markdown and Latex directly in Jupyter Notebooks or use some other editor? Thanks — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#542 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACNFAAABXBDZAV3LYMAK5H3UDMO5DANCNFSM4S2RPEBA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[TonyHoldroyd]

@tcNickolas Thank you Mariia, good, yes, that's what I was hoping you would say, I've used Jupyter Notebooks extensively in the past and have started with them for this work.

What do you think about the idea of adding a small extension task at the end of the solution to each Basic Gates Task please?
The reason I ask is that in the Learning Path, Basic Gates follows Single Qubit Gates; the work involved in Basic Gates is to an extent recall or looking-up and I thought a little reinforcement might be in order.

Here is an example I thought to suggest for Task 1:

Extension task: A single qubit is in a superposition |𝜓⟩=𝛼|0⟩+𝛽|1⟩ with 𝛼=0.42 . Work out 𝛽 , (to 2 decimal places), and write down |𝜓⟩ both before and after applying the Pauli-X gate to it.

Perhaps the answers could go at the end of the Workbook file

[TonyHoldroyd]

@tcNickolas Ciao Mariia, I have had a stab at the first two Tasks in the Basic Gates kata and I was wondering if you have time to have a quick look at them for me please? Shouldn't take long.

[tcNickolas]

@TonyHoldroyd Sure, you can attach the notebook to this thread and I'll take a look. (You might have to rename it to .txt, I think GitHub is not happy about .ipynb attachments.)
For the actual pull request, I recommend waiting until October 1st if you're interested in participating in Hacktoberfest - they have nice t-shirts if you like that kind of thing :-)

[TonyHoldroyd]

@tcNickolas Okay, thank you Mariia, it's attached. And thank you also for the tip, I never wear anything else these days :).

WorkBook_BasicGatesCopy1ForMariia.txt

[CemNurlu]

Hello,
If it's still up for grabs, i can start working on Superdense Coding and Teleportation Workbooks. Is there a specific format guideline for the workbooks? If not i can start working now.

[tcNickolas]

@CemNurlu Yes, these are still up for grabs! The workbooks do follow a specific structure, with a standard introduction followed by a sequence of tasks, with a task description, solution description, and solution code, and links to and from the kata notebook to link the respective tasks in both. You can check out any existing workbooks to see the structure; a recent example of a pull request adding a workbook is #636.

[tcNickolas]

@TonyHoldroyd I took a quick look your workbook draft, here are a few comments:

• When we reference tutorials or katas from notebooks, we use relative links to .ipynb tutorial files instead of absolute GitHub links - this way, if a person is on Binder or running the notebook locally, the link will take them directly to the tutorial referenced, rather than back to GitHub to find their way back to the notebook version of the tutorial
• When discussing a task, we usually put the solution description first, and the code cell second - this way the learner can take a peek at the beginning of the solution, realize what they've been missing in their thinking, and keep trying to do it on their own, rather than being faced with the answer right away
• Looks like in some tasks you're using formulas and in some tasks (like task 1.2) - Unicode. The katas started with .qs files - they are actually older than Q# Jupyter Notebooks! - which don't support formulas, so I had to get creative with Unicode there (and I'm still using plenty of Unicode in GitHub comments). In Jupyter Notebooks, though, we're using formulas, both for uniformity across all notebooks and because they render prettier
• The product in the formulas is best denoted with \cdot macro
• In task 1.1, we probably don't need the note in italics, since this is not a tutorial that introduces the gates, but an exercise to practice using them
• For the extension tasks, it probably makes sense to move the tasks themselves to the kata, and add the solutions to them to the workbook? Similar to the programming tasks, but without the code cells
• For task 1.2E, I'm not sure what you mean by checking that H|+⟩ = 0.7071(|0⟩ +|1⟩) - did you mean to check that H|+⟩=|0⟩?
• Task 1.3E seems to be very similar to exercise 3 from SingleQubitGates tutorial? Maybe we could do something more interesting here, say, combine H with Z?
• When we work with angles, we usually express them in radians - fractions of 𝜋 are a lot more common in quantum computing than degrees. I think it makes sense to stick to this convention in this tutorial as well

I hope these notes make sense - let me know if you have questions about them! Once you've addressed them, I think you can send the pull request with the first four tasks. Smaller pull requests make it easier for me to review them promptly. You might also want to split adding the extension tasks into a separate pull request, since they'll need extra work on the solutions as well.

[TonyHoldroyd]

@tcNickolas Ciao Mariia, thank you very much for taking the time to leave me such detailed and helpful feedback notes, all of which make total sense.
What I thought was, if I make a pull request for every 4 workbook tasks would that be manageable? I could do less, whatever would suit you, . Then I can merge all the tasks into one workbook at the end when you have approved them (I have found a little Python program for that). Also I'll put all the extension tasks into one or two files as they are short. I've registered with Hacktoberfest.

[TonyHoldroyd]

Ciao Mariia,
Thank you, again, for your detailed and helpful feedback.
I have followed up on all your notes, and issued a new pull request which is currently awaiting green ticks.
For your last note about the structure of the workbook, I have followed the pattern you suggested - in 3 steps - I have introduced/revised the gate with simpler examples than the main task so as to lead into the task, then for the extension exercises I will come up with Tasks that make more extended use of the gate. I think that is what you had in mind, but I can always do more work on this if you would like me to.

[saich08]

@tcNickolas, I would like to contribute on this. I can start with tutorials/RandomNumberGeneration. Let me know if it already taken.

[tcNickolas]

@ssc1729 Sounds great - I don't think anybody's working on RandomNumberGeneration so you're welcome to it!

[japanavi]

I can do QEC_BitFlipCode!

[tcNickolas]

@japanavi Sounds good!

[PratikSathe]

Hi @tcNickolas , I would like to work on one of the workbooks or tutorials. It seems to me that the Oracles Tutorial might be up for grabs. Is MagicSquareGame, or any other one taken?

[tcNickolas]

Hi @PratikSathe, welcome back! :-)

Let me check quickly with someone who expressed interest in the workbook for the Oracles tutorial; all others that are not marked as taken are up for grabs!

[PratikSathe]

Hi @tcNickolas , I would like to work on Phase Estimation!

[tcNickolas]

@PratikSathe Sounds good!

[Parisha-Agrawal]

Hi @tcNickolas , I would like to work on the tasks in Ripple Carry Adder workbook. I am planning to send 3-4 workbook tasks in a PR so that it is manageable with my college course. Would that be ok with you?

[tcNickolas]

@Parisha-Agrawal Sure! In fact, I prefer to review smaller PRs, it's a lot easier for me to make time for them, and a lot better for the contributors to get early feedback on the work to account for it right away in the next installments.

[Parisha-Agrawal]

Thanks @tcNickolas . I will get started on "Ripple Carry Adder" workbook then. I will update this thread when my first draft is ready :-)

[Parisha-Agrawal]

Hi @tcNickolas , I have created pull request to add workbook tasks 1.1 - tasks 1.3 in pull request. #794

Would be glad to receive your feedback.