From ad2e4059fb696c7ed388b678398dd8d6ebce7dce Mon Sep 17 00:00:00 2001 From: numpde <21158052+numpde@users.noreply.github.com> Date: Mon, 16 Dec 2019 17:46:45 +0100 Subject: [PATCH 1/5] Minor doc fixes --- Standard/src/Arithmetic/Modular.qs | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/Standard/src/Arithmetic/Modular.qs b/Standard/src/Arithmetic/Modular.qs index a2650934558..d5392f7a901 100644 --- a/Standard/src/Arithmetic/Modular.qs +++ b/Standard/src/Arithmetic/Modular.qs @@ -11,10 +11,10 @@ namespace Microsoft.Quantum.Arithmetic { /// # Summary /// Performs a modular increment of a qubit register by an integer constant. /// - /// Let us denote `increment` by a, `modulus` by N and integer encoded in `target` by y + /// Let us denote `increment` by a, `modulus` by N and integer encoded in `target` by y. /// Then the operation performs the following transformation: /// \begin{align} - /// \ket{y} \mapsto \ket{y + 1 \operatorname{mod} N} + /// \ket{y} \mapsto \ket{(y + a) \operatorname{mod} N} /// \end{align} /// Integers are encoded in little-endian format. /// @@ -27,12 +27,14 @@ namespace Microsoft.Quantum.Arithmetic { /// Integer y in `LittleEndian` format that `increment` a is added to. /// /// # See Also - /// - IncrementPhaseByModularInteger + /// - Microsoft.Quantum.Arithmetic.IncrementPhaseByModularInteger /// /// # Remarks - /// Assumes that the value of target is less than N. Note that + /// Assumes that the initial value of target is less than N + /// and that the increment a is less than N. + /// Note that /// implements - /// the same operation, but in the `PhaseLittleEndian` basis. + /// the same operation in the `PhaseLittleEndian` basis. operation IncrementByModularInteger(increment : Int, modulus : Int, target : LittleEndian) : Unit { body (...) { let inner = IncrementPhaseByModularInteger(increment, modulus, _); @@ -50,13 +52,13 @@ namespace Microsoft.Quantum.Arithmetic { /// # Summary /// Performs a modular increment of a qubit register by an integer constant. /// - /// Let us denote `increment` by a, `modulus` by N and integer encoded in `target` by y + /// Let us denote `increment` by a, `modulus` by N and integer encoded in `target` by y. /// Then the operation performs the following transformation: /// |y⟩ ↦ |y+a (mod N)⟩ - /// Integers are encoded in little-endian format in QFT basis + /// Integers are encoded in little-endian format in QFT basis. /// /// # See Also - /// - Microsoft.Quantum.Canon.ModularIncrementLE + /// - Microsoft.Quantum.Canon.ModularIncrementLE (deprecated) /// /// # Remarks /// Assumes that `target` has the highest bit set to 0. @@ -153,11 +155,11 @@ namespace Microsoft.Quantum.Arithmetic { } /// # Summary - /// The same as ModularAddProductLE, but assumes that summand encodes + /// The same as ModularAddProductLE (deprecated), but assumes that summand encodes /// integers in QFT basis /// /// # See Also - /// - Microsoft.Quantum.Canon.ModularAddProductLE + /// - Microsoft.Quantum.Canon.ModularAddProductLE (deprecated) /// /// # Remarks /// Assumes that `phaseSummand` has the highest bit set to 0. @@ -186,13 +188,13 @@ namespace Microsoft.Quantum.Arithmetic { /// Let us denote modulus by N and constMultiplier by a /// then this operation implements a unitary defined by the following map on /// computational basis: - /// |y⟩ ↦ |a⋅y (mod N) ⟩, for all y between 0 and N - 1 + /// |y⟩ ↦ |a⋅y (mod N)⟩, for all y between 0 and N - 1. /// /// # Input /// ## constMultiplier /// Constant by which multiplier is being multiplied. Must be co-prime to modulus. /// ## modulus - /// The multiplication operation is performed modulo `modulus` + /// The multiplication operation is performed modulo `modulus`. /// ## multiplier /// The number being multiplied by a constant. /// This is an array of qubits representing integer in little-endian bit order. From 37266fec66bfab44402f1acd4a49bd77ca921c91 Mon Sep 17 00:00:00 2001 From: numpde <21158052+numpde@users.noreply.github.com> Date: Tue, 17 Dec 2019 23:52:26 +0100 Subject: [PATCH 2/5] Minor doc cleanup There are probably still some unstated assumptions on the algorithms. --- Standard/src/Arithmetic/Modular.qs | 50 ++++++++++++++++++------------ 1 file changed, 30 insertions(+), 20 deletions(-) diff --git a/Standard/src/Arithmetic/Modular.qs b/Standard/src/Arithmetic/Modular.qs index d5392f7a901..4363fb1a237 100644 --- a/Standard/src/Arithmetic/Modular.qs +++ b/Standard/src/Arithmetic/Modular.qs @@ -11,7 +11,7 @@ namespace Microsoft.Quantum.Arithmetic { /// # Summary /// Performs a modular increment of a qubit register by an integer constant. /// - /// Let us denote `increment` by a, `modulus` by N and integer encoded in `target` by y. + /// Let us denote `increment` by $a$, `modulus` by $N$ and integer encoded in `target` by $y$. /// Then the operation performs the following transformation: /// \begin{align} /// \ket{y} \mapsto \ket{(y + a) \operatorname{mod} N} @@ -20,18 +20,18 @@ namespace Microsoft.Quantum.Arithmetic { /// /// # Input /// ## increment - /// Integer increment a to be added to y. + /// Integer increment $a$ to be added to $y$. /// ## modulus - /// Integer N that mods y + a. + /// Integer $N$ that mods $y + a$. /// ## target - /// Integer y in `LittleEndian` format that `increment` a is added to. + /// Integer $y$ in `LittleEndian` format that `increment` $a$ is added to. /// /// # See Also /// - Microsoft.Quantum.Arithmetic.IncrementPhaseByModularInteger /// /// # Remarks - /// Assumes that the initial value of target is less than N - /// and that the increment a is less than N. + /// Assumes that the initial value of target is less than $N$ + /// and that the increment $a$ is less than $N$. /// Note that /// implements /// the same operation in the `PhaseLittleEndian` basis. @@ -52,17 +52,19 @@ namespace Microsoft.Quantum.Arithmetic { /// # Summary /// Performs a modular increment of a qubit register by an integer constant. /// - /// Let us denote `increment` by a, `modulus` by N and integer encoded in `target` by y. + /// Let us denote `increment` by $a$, `modulus` by $N$ and integer encoded in `target` by $y$. /// Then the operation performs the following transformation: - /// |y⟩ ↦ |y+a (mod N)⟩ + /// \begin{align} + /// \ket{y} \mapsto \ket{(y + a) \operatorname{mod} N} + /// \end{align} /// Integers are encoded in little-endian format in QFT basis. /// /// # See Also - /// - Microsoft.Quantum.Canon.ModularIncrementLE (deprecated) + /// - Microsoft.Quantum.Arithmetic.IncrementByModularInteger /// /// # Remarks /// Assumes that `target` has the highest bit set to 0. - /// Also assumes that the value of target is less than N. + /// Also assumes that the value of target is less than $N$. /// /// For the circuit diagram and explanation see Figure 5 on [Page 5 /// of arXiv:quant-ph/0205095v3](https://arxiv.org/pdf/quant-ph/0205095v3.pdf#page=5). @@ -118,7 +120,7 @@ namespace Microsoft.Quantum.Arithmetic { /// Implements the map /// $$ /// \begin{align} - /// \ket{x} \ket{b} \mapsto \ket{x} \ket{b + a \cdot x \operatorname{mod} N} + /// \ket{x} \ket{b} \mapsto \ket{x} \ket{(b + a \cdot x) \operatorname{mod} N} /// \end{align} /// $$ /// for a given modulus $N$, constant multiplier $a$, and summand $y$. @@ -135,6 +137,9 @@ namespace Microsoft.Quantum.Arithmetic { /// A quantum register representing an unsigned integer to use as the target /// for this operation. /// + /// # See Also + /// - Microsoft.Quantum.Arithmetic.MultiplyAndAddPhaseByModularInteger + /// /// # Remarks /// - For the circuit diagram and explanation see Figure 6 on [Page 7 /// of arXiv:quant-ph/0205095v3](https://arxiv.org/pdf/quant-ph/0205095v3.pdf#page=7) @@ -155,15 +160,15 @@ namespace Microsoft.Quantum.Arithmetic { } /// # Summary - /// The same as ModularAddProductLE (deprecated), but assumes that summand encodes - /// integers in QFT basis + /// The same as @"MultiplyAndAddByModularInteger", but assumes that the summand encodes + /// integers in QFT basis. /// /// # See Also - /// - Microsoft.Quantum.Canon.ModularAddProductLE (deprecated) + /// - Microsoft.Quantum.Arithmetic.MultiplyAndAddByModularInteger /// /// # Remarks /// Assumes that `phaseSummand` has the highest bit set to 0. - /// Also assumes that the value of `phaseSummand` is less than N. + /// Also assumes that the value of `phaseSummand` is less than $N$. operation MultiplyAndAddPhaseByModularInteger(constMultiplier : Int, modulus : Int, multiplier : LittleEndian, phaseSummand : PhaseLittleEndian) : Unit is Adj + Ctl { EqualityFactB(modulus <= 2 ^ (Length(phaseSummand!) - 1), true, $"`multiplier` must be big enough to fit integers modulo `modulus`" + $"with highest bit set to 0"); EqualityFactB(constMultiplier >= 0 and constMultiplier < modulus, true, $"`constMultiplier` must be between 0 and `modulus`-1"); @@ -185,10 +190,15 @@ namespace Microsoft.Quantum.Arithmetic { /// # Summary /// Performs modular multiplication by an integer constant on a qubit register. /// - /// Let us denote modulus by N and constMultiplier by a - /// then this operation implements a unitary defined by the following map on + /// Let us denote `modulus` by $N$ and `constMultiplier` by $a$. + /// Then this operation implements a unitary operator defined by the following map on /// computational basis: - /// |y⟩ ↦ |a⋅y (mod N)⟩, for all y between 0 and N - 1. + /// $$ + /// \begin{align} + /// \ket{y} \mapsto \ket{(a \cdot y) \operatorname{mod} N} + /// \end{align} + /// $$ + /// for all $y$ between $0$ and $N - 1$. /// /// # Input /// ## constMultiplier @@ -197,7 +207,7 @@ namespace Microsoft.Quantum.Arithmetic { /// The multiplication operation is performed modulo `modulus`. /// ## multiplier /// The number being multiplied by a constant. - /// This is an array of qubits representing integer in little-endian bit order. + /// This is an array of qubits encoding an integer in little-endian format. /// /// # Remarks /// - For the circuit diagram and explanation see Figure 7 on [Page 8 @@ -206,7 +216,7 @@ namespace Microsoft.Quantum.Arithmetic { /// [arXiv:quant-ph/0205095v3](https://arxiv.org/pdf/quant-ph/0205095v3.pdf) operation MultiplyByModularInteger(constMultiplier : Int, modulus : Int, multiplier : LittleEndian) : Unit is Adj + Ctl { // Check the preconditions using Microsoft.Quantum.Canon.EqualityFactB - EqualityFactB(constMultiplier >= 0 and constMultiplier < modulus, true, $"`constMultiplier` must be between 0 and `modulus`"); + EqualityFactB(0 <= constMultiplier and constMultiplier < modulus, true, $"`constMultiplier` must be between 0 and `modulus`"); EqualityFactB(modulus <= 2 ^ Length(multiplier!), true, $"`multiplier` must be big enough to fit integers modulo `modulus`"); EqualityFactB(IsCoprimeI(constMultiplier, modulus), true, $"`constMultiplier` and `modulus` must be co-prime"); From 760fb12f6e4769f339bbfdb8b66c45667d19315d Mon Sep 17 00:00:00 2001 From: numpde <21158052+numpde@users.noreply.github.com> Date: Sat, 4 Jan 2020 12:52:00 +0100 Subject: [PATCH 3/5] Add "# Description" for MultiplyByModularInteger ...because there is inline math. Co-Authored-By: Chris Granade --- Standard/src/Arithmetic/Modular.qs | 1 + 1 file changed, 1 insertion(+) diff --git a/Standard/src/Arithmetic/Modular.qs b/Standard/src/Arithmetic/Modular.qs index 4363fb1a237..f402d16c7e0 100644 --- a/Standard/src/Arithmetic/Modular.qs +++ b/Standard/src/Arithmetic/Modular.qs @@ -190,6 +190,7 @@ namespace Microsoft.Quantum.Arithmetic { /// # Summary /// Performs modular multiplication by an integer constant on a qubit register. /// + /// # Description /// Let us denote `modulus` by $N$ and `constMultiplier` by $a$. /// Then this operation implements a unitary operator defined by the following map on /// computational basis: From 22bdd269b93fa2cfd128c1c3e9cff6a9237b7926 Mon Sep 17 00:00:00 2001 From: numpde <21158052+numpde@users.noreply.github.com> Date: Sat, 4 Jan 2020 12:55:17 +0100 Subject: [PATCH 4/5] "unitary operation" instead of "unitary operator" Co-Authored-By: Chris Granade --- Standard/src/Arithmetic/Modular.qs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Standard/src/Arithmetic/Modular.qs b/Standard/src/Arithmetic/Modular.qs index f402d16c7e0..d0d068c13c9 100644 --- a/Standard/src/Arithmetic/Modular.qs +++ b/Standard/src/Arithmetic/Modular.qs @@ -192,7 +192,7 @@ namespace Microsoft.Quantum.Arithmetic { /// /// # Description /// Let us denote `modulus` by $N$ and `constMultiplier` by $a$. - /// Then this operation implements a unitary operator defined by the following map on + /// Then this operation implements a unitary operation defined by the following map on the /// computational basis: /// $$ /// \begin{align} From bf85a855509a7ba2be2afca5568fc7a53e9e20f5 Mon Sep 17 00:00:00 2001 From: numpde <21158052+numpde@users.noreply.github.com> Date: Sat, 4 Jan 2020 13:02:43 +0100 Subject: [PATCH 5/5] Add "# Description", remove refs in "# Summary" --- Standard/src/Arithmetic/Modular.qs | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Standard/src/Arithmetic/Modular.qs b/Standard/src/Arithmetic/Modular.qs index d0d068c13c9..2f9bea6c89d 100644 --- a/Standard/src/Arithmetic/Modular.qs +++ b/Standard/src/Arithmetic/Modular.qs @@ -11,6 +11,7 @@ namespace Microsoft.Quantum.Arithmetic { /// # Summary /// Performs a modular increment of a qubit register by an integer constant. /// + /// # Description /// Let us denote `increment` by $a$, `modulus` by $N$ and integer encoded in `target` by $y$. /// Then the operation performs the following transformation: /// \begin{align} @@ -52,6 +53,7 @@ namespace Microsoft.Quantum.Arithmetic { /// # Summary /// Performs a modular increment of a qubit register by an integer constant. /// + /// # Description /// Let us denote `increment` by $a$, `modulus` by $N$ and integer encoded in `target` by $y$. /// Then the operation performs the following transformation: /// \begin{align} @@ -117,6 +119,7 @@ namespace Microsoft.Quantum.Arithmetic { /// # Summary /// Performs a modular multiply-and-add by integer constants on a qubit register. /// + /// # Description /// Implements the map /// $$ /// \begin{align} @@ -160,15 +163,15 @@ namespace Microsoft.Quantum.Arithmetic { } /// # Summary - /// The same as @"MultiplyAndAddByModularInteger", but assumes that the summand encodes + /// The same as MultiplyAndAddByModularInteger, but assumes that the summand encodes /// integers in QFT basis. /// - /// # See Also - /// - Microsoft.Quantum.Arithmetic.MultiplyAndAddByModularInteger - /// /// # Remarks /// Assumes that `phaseSummand` has the highest bit set to 0. /// Also assumes that the value of `phaseSummand` is less than $N$. + /// + /// # See Also + /// - Microsoft.Quantum.Arithmetic.MultiplyAndAddByModularInteger operation MultiplyAndAddPhaseByModularInteger(constMultiplier : Int, modulus : Int, multiplier : LittleEndian, phaseSummand : PhaseLittleEndian) : Unit is Adj + Ctl { EqualityFactB(modulus <= 2 ^ (Length(phaseSummand!) - 1), true, $"`multiplier` must be big enough to fit integers modulo `modulus`" + $"with highest bit set to 0"); EqualityFactB(constMultiplier >= 0 and constMultiplier < modulus, true, $"`constMultiplier` must be between 0 and `modulus`-1");