Adding circuit images for better understanding

[J1990]

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.

• ID: e1e62567-13c8-19c2-ba15-65920a49afb3
• Version Independent ID: 5c7af935-d4af-6f50-1bb7-4f64ffcf836e
• Content: CyclicEntanglingLayer function (Microsoft.Quantum.MachineLearning) - Q# reference - Microsoft Quantum
• Content Source: api/qsharp/microsoft.quantum.machinelearning.cyclicentanglinglayer.yml
• Product: quantum
• GitHub Login: @cgranade

[cgranade]

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 microsoft/iqsharp#231.

[guenp]

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

[cgranade]

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]

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?