search

microsoft / QuantumLibraries

Q# libraries for the Quantum Development Kit
https://docs.microsoft.com/quantum
MIT License
541 stars 179 forks source link

Adding circuit images for better understanding #300

Open J1990 opened 4 years ago

J1990 commented 4 years ago

It would be nice to have an overview of inner working of each of the APIs in Microsoft Quantum Machine Learning library. Also for better intuition building, these articles can include images of example circuits.

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

cgranade commented 4 years ago

Thanks for raising this, @J1990! We'll look at how to add more examples of using those QML library functions in API documentation.

As a side note, you may also be interested in the feature at https://github.com/microsoft/iqsharp/pull/231.

guenp commented 3 years ago

@cgranade @KittyYeungQ , I think this is a great suggestion. Will it be possible to include circuit diagrams in some parts of the documentation?

cgranade commented 3 years ago

Part of the problem is that Q# operations really aren't circuits; while tools like %trace provided with IQ# can show execution paths when running Q# programs, I think it would be very confusing to equate circuit diagrams with those programs themselves. That aside, though, I don't believe we currently have a pipeline in place for deploying images used in API documentation at all, especially since API documentation can be consumed in a variety of different places (e.g.: docs.microsoft.com, IQ#'s ? commands, VS Code or VS 2019 hover information), not all of which support richer features like images.

guenp commented 3 years ago

That makes sense. There are, however, some Q# operations for which having an example circuit diagram to explain the concept can be helpful. Like you said; Q# programs aren't circuits, but circuits can be helpful to explain some parts of the program. My suggestion would be to have an internal discussion about this and see how we can use circuits to our advantage whilst still making a clear distinction between circuits and Q# programs. Then we can see if we can implement a feature to deploy images in API documentation (which would be platform-dependent as you noted). Would something like that work?