Add new sample for solving Sudoku puzzles using Grover

[markklink]

This was the type of sample code I wanted to see when I started learning the QDK
i.e. How to implement a normal program in Quantum.
I'm only a beginner with the QDK and don't know if this is a suitable sample for the QDK, but wanted to offer it for your consideration.
I would also be very interested in getting access to Quantum Azure to run the more complex 9x9 puzzle which I commented out in the simulation.
Thanks!
Mark Klink

[ghost]

All CLA requirements met.

[cgranade]

Thanks for contributing, Mark! This looks like a really neat PR, so we really appreciate your opening it up. I'll take a look through and review as soon as I can, thanks for your patience as we work to give suggestions and feedback.

[tcNickolas]

@markklink I like this twist on graph coloring - it makes for a nice easy-to-explain task while stretching the original problem quite a bit!

How do you feel about making this into a new section in the GraphColoring kata?

We wouldn't be able to solve a 9x9 sudoku, but we could have several tasks around the 4x4 version - modifying the oracle to include constraints from already filled cells (it can be split into individual checks to build up to the whole oracle), parsing the sudoku input into the input that we'll pass to the oracle, solving the whole sudoku and a free-form task for the learner to experiment with custom tests. I'd make the new tasks a part of the existing Q# project GraphColoring (so that you can reuse some of the primitives without duplicating code), but give them a separate Jupyter notebook frontend for better visibility.

Let us know what you think!

[markklink]

@tcNickolas are you saying you want have this as a Kata instead of as a sample? My experience trying to learn the QDK was that I really wanted to see complete examples. The Katas are hard enough to understand even if you cheat and look at the answers! I found myself just browsing thru the entire codebase of the Quantum and QuantumLibraries repos to see things in action. Perhaps I'm missing something, but this seems to be the only way to learn about the API. This all started for me with as a hackathon project at work (LinkedIn), where we get 2 days to pick a project and hack up a solution. I wanted to learn about Quantum Computing and chose solving Sudoku as the project goal. I had been reading "Quantum Computation and Quantum Information" by Nielsen and from there I got the insight that all the logic gates are built with controlled NOT gates. My first version of Sudoku was created with hardcoded AND/OR/XOR gates built on top of CCNOTs to define the puzzle. I then noticed that the graph coloring Kata was doing similar things to my code but with much smarter code. The database search sample showed how to interact with C#. Hackathons are all about doing things quickly. I think adding this PR as a sample would make it much easier for someone to quickly ramp up as a developer.
Would it be OK to do both? i.e. add it as sample, and create new GraphColoring kata section?
BTW - @tcNickolas I really liked your QDK presentation in the July Azure Quantum Developer workshop!
@cgranade - Wish I had known about your book earlier! I'm reading it now. I didn't see any links to this in https://docs.microsoft.com/en-us/quantum/. Can you add it somewhere? That would be really helpful for us newcomers.

[tcNickolas]

@markklink I'm sorry to hear that you found the katas hard to understand :-( Can you elaborate on where you started in them and what were the gaps in the covered material? One of the things our community is working on right now are the workbooks for the katas - descriptions of worked out solutions to the tasks; I imagine having one like that for the GraphColoring would have been helpful? (It's in progress now.) But I digress :-)

I think we can have both a kata section and a sample for the sudoku, as long as you're willing to contribute both :-) The code is going to be somewhat different, with the split into tasks, reference implementation and testing harness for the kata that the samples usually don't exhibit. My interest is mostly in the kata, I believe @guenp will guide you through the contribution to the samples repo.

P.S. I'm glad you enjoyed the virtual lab at AQDW! :-)

[guenp]

My experience trying to learn the QDK was that I really wanted to see complete examples. The Katas are hard enough to understand even if you cheat and look at the answers! I found myself just browsing thru the entire codebase of the Quantum and QuantumLibraries repos to see things in action. Perhaps I'm missing something, but this seems to be the only way to learn about the API.

Thank you @markklink , this is great feedback! We will take this into account. Have you taken a look at the QDK documentation and Q# API reference? What are your thoughts on those from the Hackathon/learning the API perspective?

Would it be OK to do both? i.e. add it as sample, and create new GraphColoring kata section?

Yes! We completely agree with your suggestion. If you have time, would you have time to help and contribute both the Sample and Kata? As @tcNickolas mentioned I can help you get the sample ready, however since some of the code came from the Kata (which generally has more relaxed requirements) we will need to rework it a bit to match the style requirements in this repo.

If you want to follow up in more depth on any of the above, feel free to reach out to me via the Q# community slack.

[markklink]

@guenp , I have time to do both. I'll contact you on slack. I did look at the documentation and API reference. It would be really helpful if there was a quick way to find a specific API description e.g. when i wanted to learn about ControlledOnInt, i didn't know where to find in on your website and i just got in the habit of finding the implementation in the code to read the code docs and have the bonus of seeing its implementation as well, and how it's used elsewhere in code.

@tcNickolas - My experience with Katas is probably a little different than normal. As mentioned, I was under a big time constraint (2 days) to get my Hackathon project done. I just wanted to quickly see something similar to what i wanted to do (i.e. run Grover from C# to find a solution to problem).
Hackathons can be a great entry point for projects, but it requires an easy path to get in. If we can see such a path, then we are much more likely to try/succeed. We don't have time to start a whole chain of Katas. I ended up just finding the most relevant ones and quickly skimming them for what's useful.
Even when I looked at the Graph Coloring Kata answers, it wasn't obvious how to use it. When I tried to use it for a 4 vertex graph which had edges that allowed for a 2 color solution, it just returned colors 0,1,2,3! OK, coloring each vertex with its own color is an answer, but how to get the solution with the minimum amount of colors. The Kata was much more helpful in showing me coding constructs I could use for my own design.
The path i took was that I knew coming into this that I could use Grover's Algorithm. I spent the first day of my hackathon looking at the related Katas: SimpleGrover, SolveSatWithGrover Kata and the database search sample (because I wanted to use C# as the front-end). IMO SimpleGrover isn't as simple as it could be ... It's not obvious initially how it works or how it's useful. The SolveSatWithGrover was really helpful to understand some basic concepts, but went beyond my comprehension (in the time i had) as it progressed. But I was determined to hack something together, so I set a goal of writing my Sudoku code using AND/OR/XOR gates. I understood enough from SolveSatWithGrover Kata to do that. After writing the code, it didn't find a result but it gave me some confidence. I wanted to maximize what I was learning in my 2 days, and had found the Graph Coloring Kata reference code and decided to try and learn that code and get it working. I was able to run it for the sample graphs in the Kata, but that's as far as i got because I realized i needed a way to add the initial numbers/colors into the solution, and to restrict the colors to 4 or 9. I also had to write up my results. It was a few days after the hackathon when I thought of a way to do both the color limit and initial color restrictions, and finished the code using the database-search sample code to figure out the C# interaction, as well as searching the entire code base for figuring out the API for result i.e. ValueTuple.
So my experience is probably not typical, but I thought i would offer it as feedback from someone who wanted to quickly ramp up.

[guenp]

@markklink done with my first pass for now!
It might be useful to check out the Q# naming conventions and walk through your code and make sure the naming is consistent with our guidelines. Please let us know if you'd like help with that from me or @cgranade.

[guenp]

@markklink thanks for your changes! I think something went wrong with the GitHub diff after some of the changes, which left a lot of @cgranade 's comments unresolved. I've gone through them, resolved them and added suggestions instead. I hope this will work, if you don't mind taking another look. Thanks!

[markklink]

I made all the code review changes and pushed them. Thanks again for the great review comments. I learnt a lot!