Description of apply / within as part of control flow.

[msoeken]

Conjugation is currently described as part of Operations and functions. I would have expected it (also) as part of the Control flow, where all other control flow constructs are described.

---

Document Details

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

• ID: 704e68ff-365d-99ee-f7b3-7c1342cbbc6b
• Version Independent ID: f997d8f0-c8dc-5fd9-2921-fadcfda3c5b6
• Content: Operations and functions in Q# - Microsoft Quantum
• Content Source: articles/user-guide/using-qsharp/operations-functions.md
• Product: quantum
• GitHub Login: @gillenhaalb
• Microsoft Alias: [email protected]

[cgranade]

I wonder if it may be reasonable to have a section on Q# keywords, similar to how the Python language reference lists different kinds of statements, or to how the C# language reference has a page for each keyword to help with searchability?

[msoeken]

@cgranade I really like this idea. Also, I keep on entering keywords into the TOC search box, even though it only filters through the TOC titles. So I guess if they had separate pages showing up in the TOC, they'd be in that search automatically.

[cgranade]

+@KittyYeungQ, @bettinaheim for discussion

[gillenhaalb]

Figure a keyword list might be a good addition to the Quick Reference pages in the user guide. Did a quick scan through and came out with these keywords below. Figure this is a decent place to discuss, let me know if I'm missing anything. (The bold titles are just loosely what they relate to for our sake here, not a suggestion for the quick ref page structure).

Types:

• Int, BigInt, Double, Bool, Range, String, Unit, Qubit, Pauli, Result
• true, false, PauliI, PauliX, PauliY, PauliZ, One, Zero

Vars:

• new, let, set, mutable,

• operation, function, newtype

Ops:

• Adjoint, Controlled, Controlled Adjoint
• is, Adj, Ctl, Adj + Ctl
• Specializations:
  • tags: body, adjoint, controlled, controlled adjoint
  • directives: intrinsic, distribute, invert, self, auto
• return
• apply, within
• _ (partial application symbol)

Control flow

• for, in
• if, elif, else, while
• repeat, until, fixup
• fail

Qubits:

• using, borrowing,

Namespace:

• namespace, open, as,

Attributes:

• @Test("..."), @EntryPoint(),

Operator symbols:
https://docs.microsoft.com/en-us/quantum/user-guide/language/expressions#operator-precedence

[crazy4pi314]

Strong +1 to @msoeken and @cgranade I keep trying to find docs for things like within/apply and other control flow and functors that then don't come up in search and I have to try and memorize which sub pages they are on (not always where I would expect them). My memory frequently fails me especially when I am on stream 😅

[KittyYeungQ]

@msoeken @cgranade @efratshabtai Can you take a look at the above list and confirm if it looks good or missing anything?

[cgranade]

Adding @bettinaheim, since many of these are about the Q# language itself. To that effect, there's a full list of Q# keywords defined in the parser at https://github.com/microsoft/qsharp-compiler/blob/2002c55a59808d44c2fec4f862c67b5848c27816/src/QsCompiler/TextProcessor/QsKeywords.fs#L66 and https://github.com/microsoft/qsharp-compiler/blob/b77641106b8faaa9046e119dec9f704f200bce46/src/QsCompiler/DataStructures/ReservedKeywords.fs. In any case, I think the only other language-level thing that I find myself linking people to regularly is the format for documentation comments (currently at https://docs.microsoft.com/en-us/quantum/user-guide/using-qsharp/file-structure#documentation-comments, under Q# user guide → Use Q# → File structure).

[msoeken]

@KittyYeungQ I cannot see anything missing there.

[efratshabtai]

@KittyYeungQ looks good to me

[KittyYeungQ]

@gillenhaalb can you create a PR to add this?

[gillenhaalb]

@KittyYeungQ Yep, will do that now. A few clarifications before I start:

1. I'll be moving the Conjugation section to Control Flow. @geduardo mentioned the lack of documentation on it (i.e. within/apply statements) in No documentation available for "within/apply" statements. #1034. Could you clarify, Eduardo, if you were referring to the explanation being insufficient, or simply being in an odd location?

2. I'll be creating a quick-ref page containing all the constructs/keywords. @cgranade @crazy4pi314 @msoeken, would that be sufficient, or would you also prefer a separate page for each (to improve searchability)? The latter would require a little more discussion into what/how much should be on each page.

[geduardo]

@gillenhaalb The explanation being insufficient. I can't find any explanation for the functioning and purpose of the keywords apply and within.

[geduardo]

For example, in the first code block of this section on Pauli measurements: https://docs.microsoft.com/en-us/quantum/concepts/pauli-measurements
the keywords are used in a context slightly different from what is stated in the documentation.

[gillenhaalb]

@geduardo I think the confusion (w.r.t. that example specifically) comes from their use being somewhat roughly described there (i.e. on the Pauli page). As far as I can tell from the documentation (Conjugation section), a block of

within{
Op1(target)
}
apply{
Op2(target)
}

corresponds to applying Op1, then Op2, and then adjoint Op1 at the end.

So, what's actually happening in the Pauli code block is that it's applying H S^dag, then measuring in Z, and then applying (H S^dag)^dag.

[cgranade]

2. I'll be creating a quick-ref page containing all the constructs/keywords. @cgranade @crazy4pi314 @msoeken, would that be sufficient, or would you also prefer a separate page for each (to improve searchability)? The latter would require a little more discussion into what/how much should be on each page.

I think the searchability argument is a pretty good one for splitting things up further as a reference. Can we compare to what other docs.ms docsets do? Taking a quick look:

• C#: one page per keyword (https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/abstract)
• F#: combined keyword reference page (https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/keyword-reference)
• C++: combined keyword reference page, with many keywords getting listed on additional pages (https://docs.microsoft.com/en-us/cpp/cpp/keywords-cpp?view=vs-2019)
• PowerShell: combined keyword reference page, with many keywords getting listed on additional pages (https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_language_keywords?view=powershell-7)
• Kusto: one page per keyword (https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/)
• T-SQL: one page per keyword (https://docs.microsoft.com/en-us/sql/t-sql/language-elements/language-elements-transact-sql?view=sql-server-ver15)
• VB.NET: one page per keyword (https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/)

[cgranade]

So, what's actually happening in the Pauli code block is that it's applying H S^dag, then measuring in Z, and then applying (H S^dag)^dag.

That's correct; the within part of MeasureY ensures that the 𝑌-basis is mapped to the 𝑍-basis, then the apply part performs the measurement. The final part, the adjoint of the within part, ensures that the post-measurement state is what you would expect from a 𝑌-basis measurement by mapping the 𝑍-basis post-measurement state back to the 𝑌-basis. Were the adjoint-within step not to be executed, the post measurement state would be either |0⟩ or |1⟩ (corresponding to Zero and One, respectively) rather than (|0⟩ + 𝑖|1⟩) / √2 or (|0⟩ − 𝑖|1⟩) / √2, as would be correct for a 𝑌-basis measurement.

[crazy4pi314]

1. I'll be creating a quick-ref page containing all the constructs/keywords. @cgranade @crazy4pi314 @msoeken, would that be sufficient, or would you also prefer a separate page for each (to improve searchability)? The latter would require a little more discussion into what/how much should be on each page.

I think the searchability argument is a pretty good one for splitting things up further as a reference. Can we compare to what other docs.ms docsets do? Taking a quick look:

I strongly agree with the searchability concern. I am often working (or on stream) and want to look up the docs for things like within/apply to link folks to and if it does not come up in the search box on the docs page I find it extremely hard to find.

[gillenhaalb]

@cgranade @crazy4pi314 Thanks for the input (and links, etc.). The benefit in searchability does sound substantial---I think I'll go ahead with that route.

I'll make a small PR moving the conjugations section to Control Flow, and then a separate one for the keywords pages. They'll start out relatively minimalist just to go ahead and have them all in place, and we can then discuss more in the PR what info the pages should/shouldn't have.

[cgranade]

@cgranade @crazy4pi314 Thanks for the input (and links, etc.). The benefit in searchability does sound substantial---I think I'll go ahead with that route.

No worries, happy to help! Thanks for taking this on!

I'll make a small PR moving the conjugations section to Control Flow, and then a separate one for the keywords pages. They'll start out relatively minimalist just to go ahead and have them all in place, and we can then discuss more in the PR what info the pages should/shouldn't have.

Sounds like a good plan, please let me know if I can help. One suggestion I'd have as they get past the minimal stage is to include concrete examples as much as possible; ideally said examples would be pulled from the samples repo so that we can unit test and make sure that those samples stay correct as the Q# language evolves. With the new ability to draw from Jupyter Notebooks, we may be able to tie that to @guenp's suggestion at microsoft/Quantum#422 if we format the Intro to Q# sample as a Q# notebook.

[crazy4pi314]

+1 to including sample code on the keyword pages. That's one of the docs improvements that (other than searchability) could have the biggest impact.

[geduardo]

I think this issue was solved with the new language repo.