Refactor AA namespace to use Q# style guide

Standard/src/Oracles/CommonOracles.qs → Standard/src/AmplitudeAmplification/CommonOracles.qs

@@ -20,20 +20,15 @@ namespace Microsoft.Quantum.AmplitudeAmplification {
 
     /// # Summary
     /// Implementation of <xref:microsoft.quantum.canon.targetstatereflectionoracle>.
-    operation TargetStateReflectionOracleImpl (phase : Double, idxFlagQubit : Int, qubits : Qubit[]) : Unit {
-        body (...) {
-            R1(phase, qubits[idxFlagQubit]);
-        }
-
-        adjoint invert;
-        controlled distribute;
-        controlled adjoint distribute;
+    operation _TargetStateReflectionOracle(phase : Double, idxFlagQubit : Int, qubits : Qubit[])
+    : Unit is Adj + Ctl {
+        R1(phase, qubits[idxFlagQubit]);
     }
 
     /// # Summary
     /// Constructs a `ReflectionOracle` about the target state uniquely marked by the flag qubit.
-	///
-	/// The target state has a single qubit set to 1, and all others 0: $\ket{1}_f$.
+    ///
+    /// The target state has a single qubit set to 1, and all others 0: $\ket{1}_f$.
     ///
     /// # Input
     /// ## idxFlagQubit
@@ -44,8 +39,8 @@ namespace Microsoft.Quantum.AmplitudeAmplification {
     ///
     /// # See Also
     /// - Microsoft.Quantum.Canon.ReflectionOracle
-    function TargetStateReflectionOracle (idxFlagQubit : Int) : ReflectionOracle {
-        return ReflectionOracle(TargetStateReflectionOracleImpl(_, idxFlagQubit, _));
+    function TargetStateReflectionOracle(idxFlagQubit : Int) : ReflectionOracle {
+        return ReflectionOracle(_TargetStateReflectionOracle(_, idxFlagQubit, _));
     }
 
 }

Standard/src/AmplitudeAmplification/Convert.qs

@@ -0,0 +1,47 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Microsoft.Quantum.AmplitudeAmplification {
+    open Microsoft.Quantum.Math;
+
+    /// # Summary
+    /// Converts phases specified as single-qubit rotations to phases
+    /// specified as partial reflections.
+    ///
+    /// # Input
+    /// ## rotPhases
+    /// Array of single-qubit rotations to be converted to partial
+    /// reflections.
+    ///
+    /// # Output
+    /// An operation that implements phases specified as partial reflections.
+    ///
+    /// # References
+    /// We use the convention in
+    /// - [ *G.H. Low, I. L. Chuang* ](https://arxiv.org/abs/1707.05391)
+    /// for relating single-qubit rotation phases to reflection operator phases.
+    function RotationPhasesAsReflectionPhases(rotPhases : RotationPhases)
+    : ReflectionPhases {
+        let nPhasesRot = Length(rotPhases!);
+        let nPhasesRef = (nPhasesRot + 1) / 2;
+
+        if (nPhasesRot % 2 == 0) {
+            fail $"Number of rotations must be odd.";
+        }
+
+        mutable phasesTarget = new Double[nPhasesRef];
+        mutable phasesStart = new Double[nPhasesRef];
+        set phasesTarget w/= 0 <- ((rotPhases!)[0] - (rotPhases!)[1]) - PI();
+        set phasesStart w/= 0 <- -(rotPhases!)[0] + 0.5 * PI();
+
+        for (idxPhases in 1 .. nPhasesRef - 2) {
+            set phasesTarget w/= idxPhases <- ((rotPhases!)[2 * idxPhases] - (rotPhases!)[2 * idxPhases + 1]) - PI();
+            set phasesStart w/= idxPhases <- ((rotPhases!)[2 * idxPhases - 1] - (rotPhases!)[2 * idxPhases]) + PI();
+        }
+
+        set phasesTarget w/= nPhasesRef - 1 <- (rotPhases!)[2 * nPhasesRef - 2] - 0.5 * PI();
+        set phasesStart w/= nPhasesRef - 1 <- ((rotPhases!)[2 * nPhasesRef - 3] - (rotPhases!)[2 * nPhasesRef - 2]) + PI();
+        return ReflectionPhases(phasesStart, phasesTarget);
+    }
+
+}

Standard/src/AmplitudeAmplification/Deprecated.qs

@@ -0,0 +1,112 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Microsoft.Quantum.AmplitudeAmplification {
+    open Microsoft.Quantum.Oracles;
+
+
+    /// # Deprecated
+    /// Please use
+    /// @"microsoft.quantum.amplitudeamplification.rotationphasesasreflectionphases".
+    @Deprecated("Microsoft.Quantum.AmplitudeAmplification.RotationPhasesAsReflectionPhases")
+    function AmpAmpRotationToReflectionPhases (rotPhases : RotationPhases)
+    : ReflectionPhases {
+        return RotationPhasesAsReflectionPhases(rotPhases);
+    }
+
+    /// # Deprecated
+    /// Please use
+    /// @"microsoft.quantum.amplitudeamplification.standardreflectionphases".
+    @Deprecated("Microsoft.Quantum.AmplitudeAmplification.StandardReflectionPhases")
+    function AmpAmpPhasesStandard(nIterations : Int) : ReflectionPhases {
+        return StandardReflectionPhases(nIterations);
+    }
+
+    /// # Deprecated
+    /// Please use
+    /// @"microsoft.quantum.amplitudeamplification.fixedpointreflectionphases".
+    @Deprecated("Microsoft.Quantum.AmplitudeAmplification.FixedPointReflectionPhases")
+    function AmpAmpPhasesFixedPoint(nQueries : Int, successMin : Double) : ReflectionPhases {
+        return FixedPointReflectionPhases(nQueries, successMin);
+    }
+
+    /// # Deprecated
+    /// Please use @"microsoft.quantum.amplitudeamplification.obliviousamplitudeamplificationfrompartialreflections".
+    @Deprecated("Microsoft.Quantum.AmplitudeAmplification.ObliviousAmplitudeAmplificationFromPartialReflections")
+    function AmpAmpObliviousByReflectionPhases(
+        phases : ReflectionPhases,
+        startStateReflection : ReflectionOracle,
+        targetStateReflection : ReflectionOracle,
+        signalOracle : ObliviousOracle
+    )
+    : ((Qubit[], Qubit[]) => Unit is Adj + Ctl) {
+        return ObliviousAmplitudeAmplificationFromPartialReflections(
+            phases, startStateReflection, targetStateReflection, signalOracle
+        );
+    }
+
+    /// # Deprecated
+    /// Please use @"microsoft.quantum.amplitudeamplification.obliviousamplitudeamplificationfromstatepreparation".
+    @Deprecated("Microsoft.Quantum.AmplitudeAmplification.ObliviousAmplitudeAmplificationFromStatePreparation")
+    function AmpAmpObliviousByOraclePhases(
+        phases : ReflectionPhases,
+        startStateOracle : DeterministicStateOracle,
+        signalOracle : ObliviousOracle,
+        idxFlagQubit : Int
+    )
+    : ((Qubit[], Qubit[]) => Unit is Adj + Ctl) {
+        return ObliviousAmplitudeAmplificationFromStatePreparation(
+            phases, startStateOracle, signalOracle, idxFlagQubit
+        );
+    }
+
+    /// # Deprecated
+    /// Please use @"microsoft.quantum.amplitudeamplification.amplitudeamplificationfrompartialreflections".
+    @Deprecated("Microsoft.Quantum.AmplitudeAmplification.AmplitudeAmplificationFromPartialReflections")
+    function AmpAmpByReflectionPhases(
+        phases : ReflectionPhases,
+        startStateReflection : ReflectionOracle,
+        targetStateReflection : ReflectionOracle
+    )
+    : (Qubit[] => Unit is Adj + Ctl) {
+        return AmplitudeAmplificationFromPartialReflections(
+            phases, startStateReflection, targetStateReflection
+        );
+    }
+
+    /// # Deprecated
+    /// Please use @"microsoft.quantum.amplitudeamplification.amplitudeamplificationfromstatepreparation".
+    @Deprecated("Microsoft.Quantum.AmplitudeAmplification.AmplitudeAmplificationFromStatePreparation")
+    function AmpAmpByOraclePhases(
+        phases : ReflectionPhases,
+        stateOracle : StateOracle,
+        idxFlagQubit : Int
+    )
+    : (Qubit[] => Unit is Adj + Ctl) {
+        return AmplitudeAmplificationFromStatePreparation(
+            phases, stateOracle, idxFlagQubit
+        );
+    }
+
+    /// # Deprecated
+    /// Please use @"microsoft.quantum.amplitudeamplification.standardamplitudeamplification".
+    @Deprecated("Microsoft.Quantum.AmplitudeAmplification.StandardAmplitudeAmplification")
+    function AmpAmpByOracle(
+        nIterations : Int,
+        stateOracle : StateOracle,
+        idxFlagQubit : Int
+    )
+    : (Qubit[] => Unit is Adj + Ctl) {
+        return StandardAmplitudeAmplification(nIterations, stateOracle, idxFlagQubit);
+    }
+
+
+    /// # Deprecated
+    /// Please use @"microsoft.quantum.amplitudeamplification.applyfixedpointamplification".
+    @Deprecated("Microsoft.Quantum.AmplitudeAmplification.ApplyFixedPointAmplification")
+    operation AmpAmpRUSByOracle(statePrepOracle : StateOracle, startQubits : Qubit[])
+    : Unit {
+        ApplyFixedPointAmplification(statePrepOracle, startQubits);
+    }
+
+}

Standard/src/AmplitudeAmplification/StandardAlgorithms.qs

@@ -0,0 +1,78 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Microsoft.Quantum.AmplitudeAmplification {
+    open Microsoft.Quantum.Convert;
+    open Microsoft.Quantum.Arrays;
+    open Microsoft.Quantum.Math;
+
+    /// # Summary
+    /// Computes partial reflection phases for standard amplitude
+    /// amplification.
+    ///
+    /// # Input
+    /// ## nIterations
+    /// Number of amplitude amplification iterations to generate partial
+    /// reflection phases for.
+    ///
+    /// # Output
+    /// An operation that implements phases specified as partial reflections
+    ///
+    /// # Remarks
+    /// All phases are $\pi$, except for the first reflection about the start
+    /// state and the last reflection about the target state, which are $0$.
+    function StandardReflectionPhases(nIterations : Int) : ReflectionPhases {
+        let commonPhases = ConstantArray(nIterations, PI());
+        let targetPhases = commonPhases + [0.0];
+        let startPhases = [0.0] + commonPhases;
+        return ReflectionPhases(startPhases, targetPhases);
+    }
+
+    // We use the phases in "Fixed-Point Amplitude Amplification with an
+    // Optimal Number of Queires" [YoderLowChuang2014]
+    // See also "Methodology of composite quantum gates" [LowYoderChuang2016]
+    // for phases in the `RotationPhases` format
+
+    /// # Summary
+    /// Computes partial reflection phases for fixed-point amplitude
+    /// amplification.
+    ///
+    /// # Input
+    /// ## nQueries
+    /// Number of queries to the state preparation oracle. Must be an odd
+    /// integer.
+    /// ## successMin
+    /// Target minimum success probability.
+    ///
+    /// # Output
+    /// Array of phases that can be used in fixed-point amplitude amplification
+    /// quantum algorithm implementation.
+    ///
+    /// # References
+    /// We use the phases in "Fixed-Point Amplitude Amplification with
+    /// an Optimal Number of Queries"
+    /// - [YoderLowChuang2014](https://arxiv.org/abs/1409.3305)
+    /// See also "Methodology of composite quantum gates"
+    /// - [LowYoderChuang2016](https://arxiv.org/abs/1603.03996)
+    /// for phases in the `RotationPhases` format.
+    function FixedPointReflectionPhases(nQueries : Int, successMin : Double)
+    : ReflectionPhases {
+        let twoPi = 2.0 * PI();
+        mutable phasesRot = new Double[nQueries];
+        let nQueriesDouble = IntAsDouble(nQueries);
+        set phasesRot w/= 0 <- 0.0;
+        let beta = Cosh((1.0 / nQueriesDouble) * ArcCosh(Sqrt(successMin)));
+        let alpha = Sqrt(1.0 - beta * beta);
+
+        for (idxPhases in 1 .. nQueries - 1) {
+            set phasesRot w/= idxPhases <-
+                phasesRot[idxPhases - 1] +
+                2.0 * ArcTan(
+                    Tan(twoPi * IntAsDouble(idxPhases) / nQueriesDouble) * alpha
+                );
+        }
+
+        return RotationPhasesAsReflectionPhases(RotationPhases(phasesRot));
+    }
+
+}

Standard/src/AmplitudeAmplification/Types.qs

@@ -7,9 +7,14 @@ namespace Microsoft.Quantum.AmplitudeAmplification {
     /// Phases for a sequence of partial reflections in amplitude amplification.
     ///
     /// # Remarks
-    /// The first parameter is an array of phases for reflection about the start state. The second parameter is an array of phases for reflection about the target state.
+    /// The first parameter is an array of phases for reflection about the
+    /// start state. The second parameter is an array of phases for reflection
+    /// about the target state.
     /// Both arrays must be of equal length. Note that in many cases, the first phase about the start state and last phase about the target state introduces a global phase shift and may be set to $0$.
-    newtype ReflectionPhases = (Double[], Double[]);
+    newtype ReflectionPhases = (
+        AboutStart: Double[],
+        AboutTarget: Double[]
+    );
 
     /// # Summary
     /// Phases for a sequence of single-qubit rotations in amplitude amplification.