Functions for arithmetic, logical, and bitwise functions. (#152)

* Slightly improved complex in Microsoft.Quantum.Math.

* First set of operators as functions.

* Added operatorfns to Microsoft.Quantum.Logical.

* Fixed layout of Bitwise.qs.

* Added tests for logical functions.

* Refactored equality facts to use common base fact, add ℂ.

* Polishing up tests and hunting down bugs.

* One last test fix.

* Fixed truncation error in bigint left-shift test.

* Addressing feedback.

* Addressing feedback in Bitwise.

* Addressing more feedback.

Author: Chris Granade

Chemistry/tests/ChemistryTests/UnitaryCoupledClusterTests.qs

@@ -69,9 +69,9 @@ namespace Microsoft.Quantum.Chemistry.Tests {
             let s = sortedIndices[3];
 
             Fact(p<q and q<r and r<s, "Expected p<q<r<s");
-            NearEqualityFact(globalSign, expectedGlobalSign);
+            NearEqualityFactD(globalSign, expectedGlobalSign);
             for (signIdx in 0..Length(signs)-1) {
-                NearEqualityFact(signs[signIdx], expectedSigns[signIdx]);
+                NearEqualityFactD(signs[signIdx], expectedSigns[signIdx]);
             }
         }
     }

Standard/src/Bitwise/Bitwise.qs

@@ -0,0 +1,101 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Microsoft.Quantum.Bitwise {
+
+    /// # Summary
+    /// Shifts the bitwise representation of a number left by a given number of
+    /// bits.
+    ///
+    /// # Input
+    /// ## value
+    /// The number whose bitwise representation is to be shifted to the left
+    /// (more significant).
+    /// ## amount
+    /// The number of bits by which `value` is to be shifted to the left.
+    ///
+    /// # Output
+    /// The value of `value`, shifted left by `amount` bits.
+    ///
+    /// # Remarks
+    /// The following are equivalent:
+    /// ```Q#
+    /// let c = a <<< b;
+    /// let c = LeftShiftedI(a, b);
+    /// ```
+    function LeftShiftedI(value : Int, amount : Int) : Int {
+        return value <<< amount;
+    }
+
+    /// # Summary
+    /// Shifts the bitwise representation of a number left by a given number of
+    /// bits.
+    ///
+    /// # Input
+    /// ## value
+    /// The number whose bitwise representation is to be shifted to the left
+    /// (more significant).
+    /// ## amount
+    /// The number of bits by which `value` is to be shifted to the left.
+    ///
+    /// # Output
+    /// The value of `value`, shifted left by `amount` bits.
+    ///
+    /// # Remarks
+    /// The following are equivalent:
+    /// ```Q#
+    /// let c = a <<< b;
+    /// let c = LeftShiftedL(a, b);
+    /// ```
+    function LeftShiftedL(value : BigInt, amount : Int) : BigInt {
+        return value <<< amount;
+    }
+
+    /// # Summary
+    /// Shifts the bitwise representation of a number right by a given number of
+    /// bits.
+    ///
+    /// # Input
+    /// ## value
+    /// The number whose bitwise representation is to be shifted to the right
+    /// (less significant).
+    /// ## amount
+    /// The number of bits by which `value` is to be shifted to the right.
+    ///
+    /// # Output
+    /// The value of `value`, shifted right by `amount` bits.
+    ///
+    /// # Remarks
+    /// The following are equivalent:
+    /// ```Q#
+    /// let c = a >>> b;
+    /// let c = RightShiftedI(a, b);
+    /// ```
+    function RightShiftedI(value : Int, amount : Int) : Int {
+        return value >>> amount;
+    }
+
+    /// # Summary
+    /// Shifts the bitwise representation of a number right by a given number of
+    /// bits.
+    ///
+    /// # Input
+    /// ## value
+    /// The number whose bitwise representation is to be shifted to the right
+    /// (less significant).
+    /// ## amount
+    /// The number of bits by which `value` is to be shifted to the right.
+    ///
+    /// # Output
+    /// The value of `value`, shifted right by `amount` bits.
+    ///
+    /// # Remarks
+    /// The following are equivalent:
+    /// ```Q#
+    /// let c = a >>> b;
+    /// let c = RightShiftedL(a, b);
+    /// ```
+    function RightShiftedL(value : BigInt, amount : Int) : BigInt {
+        return value >>> amount;
+    }
+}

Standard/src/Bitwise/Properties/NamespaceInfo.qs

@@ -0,0 +1,7 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/// # Summary
+/// This namespace contains functions for acting on the bitwise representation of
+/// classical data types.
+namespace Microsoft.Quantum.Bitwise { }

Standard/src/Diagnostics/Deprecated.qs

@@ -14,10 +14,17 @@ namespace Microsoft.Quantum.Canon {
     }
 
     /// # Deprecated
-    /// Please use @"Microsoft.Quantum.Diagnostics.NearEqualityFact" instead.
+    /// Please use @"Microsoft.Quantum.Diagnostics.NearEqualityFactD" instead.
     function AssertAlmostEqual(actual : Double, expected : Double) : Unit {
-        _Renamed("Microsoft.Quantum.Canon.AssertAlmostEqual", "Microsoft.Quantum.Diagnostics.NearEqualityFact");
-        NearEqualityFact(actual, expected);
+        _Renamed("Microsoft.Quantum.Canon.AssertAlmostEqual", "Microsoft.Quantum.Diagnostics.NearEqualityFactD");
+        NearEqualityFactD(actual, expected);
+    }
+
+    /// # Deprecated
+    /// Please use @"Microsoft.Quantum.Diagnostics.NearEqualityFactD" instead.
+    function NearEqualityFact(actual : Double, expected : Double) : Unit {
+        _Renamed("Microsoft.Quantum.Diagnostics.NearEqualityFact", "Microsoft.Quantum.Diagnostics.NearEqualityFactD");
+        NearEqualityFactD(actual, expected);
     }
 
     /// # Deprecated

Standard/src/Diagnostics/Facts.qs

@@ -3,7 +3,15 @@
 
 namespace Microsoft.Quantum.Diagnostics {
     open Microsoft.Quantum.Canon;
+    open Microsoft.Quantum.Math;
     open Microsoft.Quantum.Arrays;
+    open Microsoft.Quantum.Logical;
+
+    /// # Summary
+    /// Private function used to generate meaningful error messages.
+    function _FormattedExpectation<'T>(actual : 'T, expected : 'T) : String {
+        return $"Expected: '{expected}'. Actual: '{actual}'";
+    }
 
     /// # Summary
     /// Declares that a classical condition is true.
@@ -33,12 +41,12 @@ namespace Microsoft.Quantum.Diagnostics {
     function EqualityWithinToleranceFact(actual : Double, expected : Double, tolerance : Double) : Unit {
         let delta = actual - expected;
         if (delta > tolerance or delta < -tolerance) {
-            fail $"Fact was false. Expected: '{expected}'. Actual: '{actual}'";
+            fail _FormattedExpectation(actual, expected);
         }
     }
 
     /// # Summary
-    /// Asserts that a classical floating point variable has the expected value up to a
+    /// Asserts that a classical floating point value has the expected value up to a
     /// small tolerance of 1e-10.
     ///
     /// # Input
@@ -50,8 +58,42 @@ namespace Microsoft.Quantum.Diagnostics {
     /// # Remarks
     /// This is equivalent to <xref:microsoft.quantum.diagnostics.equalitywithintolerancefact> with
     /// hardcoded tolerance of $10^{-10}$.
-    function NearEqualityFact(actual : Double, expected : Double) : Unit {
-        EqualityWithinToleranceFact(actual, expected, 1E-10);
+    function NearEqualityFactD(actual : Double, expected : Double) : Unit {
+        EqualityWithinToleranceFact(actual, expected, 1e-10);
+    }
+
+    /// # Summary
+    /// Asserts that a classical complex number has the expected value up to a
+    /// small tolerance of 1e-10.
+    ///
+    /// # Input
+    /// ## actual
+    /// The number to be checked.
+    /// ## expected
+    /// The expected value.
+    function NearEqualityFactC(actual : Complex, expected : Complex) : Unit {
+        // Don't reduce to the base case of Fact, since we need to check two
+        // conditions.
+        let ((reA, imA), (reE, imE)) = (actual!, expected!);
+        if (AbsD(reA - reE) >= 1e-10 or AbsD(imA - imE) >= 1e-10) {
+            fail _FormattedExpectation(actual, expected);
+        }
+    }
+
+    /// # Summary
+    /// Asserts that a classical complex number has the expected value up to a
+    /// small tolerance of 1e-10.
+    ///
+    /// # Input
+    /// ## actual
+    /// The number to be checked.
+    /// ## expected
+    /// The expected value.
+    function NearEqualityFactCP(actual : ComplexPolar, expected : ComplexPolar) : Unit {
+        return NearEqualityFactC(
+            ComplexPolarAsComplex(actual),
+            ComplexPolarAsComplex(expected)
+        );
     }
 
     /// # Summary
@@ -65,12 +107,8 @@ namespace Microsoft.Quantum.Diagnostics {
     ///
     /// ## message
     /// Failure message string to be used when the assertion is triggered.
-    function EqualityFactI(actual : Int, expected : Int, message : String) : Unit
-    {
-        if (actual != expected)
-        {
-            fail message;
-        }
+    function EqualityFactI(actual : Int, expected : Int, message : String) : Unit {
+        Fact(actual == expected, $"{actual} ≠ {expected}: {message}");
     }
 
     /// # Summary
@@ -84,12 +122,8 @@ namespace Microsoft.Quantum.Diagnostics {
     ///
     /// ## message
     /// Failure message string to be used when the assertion is triggered.
-    function EqualityFactL(actual : BigInt, expected : BigInt, message : String) : Unit
-    {
-        if (actual != expected)
-        {
-            fail message;
-        }
+    function EqualityFactL(actual : BigInt, expected : BigInt, message : String) : Unit {
+        Fact(actual == expected, $"{actual} ≠ {expected}: {message}");
     }
 
     /// # Summary
@@ -104,12 +138,8 @@ namespace Microsoft.Quantum.Diagnostics {
     ///
     /// ## message
     /// Failure message string to be used when the assertion is triggered.
-    function EqualityFactB(actual : Bool, expected : Bool, message : String) : Unit
-    {
-        if (actual != expected)
-        {
-            fail message;
-        }
+    function EqualityFactB(actual : Bool, expected : Bool, message : String) : Unit {
+        Fact(actual == expected, $"{actual} ≠ {expected}: {message}");
     }
 
     /// # Summary
@@ -125,10 +155,39 @@ namespace Microsoft.Quantum.Diagnostics {
     /// ## message
     /// Failure message string to be used when the assertion is triggered.
     function EqualityFactR (actual : Result, expected : Result, message : String) : Unit {
-        if (actual != expected)
-        {
-            fail message;
-        }
+        Fact(actual == expected, $"{actual} ≠ {expected}: {message}");
+    }
+
+    /// # Summary
+    /// Asserts that a complex number has the expected value.
+    ///
+    /// # Input
+    /// ## actual
+    /// The value to be checked.
+    ///
+    /// ## expected
+    /// The expected value.
+    ///
+    /// ## message
+    /// Failure message string to be used when the assertion is triggered.
+    function EqualityFactC(actual : Complex, expected : Complex, message : String) : Unit {
+        Fact(EqualC(actual, expected), $"{actual} ≠ {expected}: {message}");
+    }
+
+    /// # Summary
+    /// Asserts that a complex number has the expected value.
+    ///
+    /// # Input
+    /// ## actual
+    /// The value to be checked.
+    ///
+    /// ## expected
+    /// The expected value.
+    ///
+    /// ## message
+    /// Failure message string to be used when the assertion is triggered.
+    function EqualityFactCP(actual : ComplexPolar, expected : ComplexPolar, message : String) : Unit {
+        Fact(EqualCP(actual, expected), $"{actual} ≠ {expected}: {message}");
     }
 
     /// # Summary