[Samples] Add samples for testing operations in Q#

build.py

@@ -515,3 +515,17 @@ def run_python_integration_tests(cwd, interpreter):
             raise Exception(f"Error running {notebook}")
 
     step_end()
+
+    step_start("Running qsharp testing samples")
+    project_directories = [
+        dir for dir in os.walk(samples_src) if "qsharp.json" in dir[2]
+    ]
+
+    test_projects_directories = [ dir
+        for dir, _, _ in project_directories
+        if dir.find("testing") != -1
+    ]
+
+    for test_project_dir in test_projects_directories:
+        run_python_tests(test_project_dir, python_bin)
+    step_end()

samples/testing/operations/README.md

@@ -0,0 +1,34 @@
+# Testing Operations in the QDK
+This sample project demonstrates different approaches to testing operations in the QDK, both via Python and within Q# itself.
+
+## Testing Methods
+
+There are two primary ways to test operations in the QDK:
+
+1. **Using Operation Matrix Representation:**
+   - Use the `dump_operation` Python API to retrieve the operation's representation as a matrix and compare it against the expected matrix.
+
+2. **Q# `Fact` Assertions:**
+   - Use a `Fact` function in your Q# code that uses the `CheckOperationsAreEqual` operation to verify if two operations are identical upto a global phase. The `Fact` function asserts that the check returns `true`.
+
+## Project Structure
+This sample project is a multi-file Q# project that showcases both testing methods. The project structure is as follows:
+
+- src
+    - `BellState.qs`: Q# file containing the `AllBellStates` operation to be tested
+    - `CustomOperation.qs`: Q# file containing the `ApplySWAP1` and `ApplySWAP2` operations to be tested
+    - `OperationEquivalence.qs`: Q# file containing the `TestEquivalence` operation to be called in Python wrapper
+- `qsharp.json`: Q# project manifest file, instructing compiler to include all files in `src` directory.
+- `test_dump_operation.py`: Python wrapper containing tests.
+
+## Installation
+- Install the `qsharp` Python package by following the instructions mentioned [here](https://learn.microsoft.com/azure/quantum/install-overview-qdk#add-support-for-python-and-jupyter-notebooks).
+- Install `pytest` Python package.
+
+## Running the sample
+Open the `samples/testing/operations` directory, and run `pytest` command.
+
+## Reference Links:
+- [Q# Testing guide](https://learn.microsoft.com/azure/quantum/user-guide/testing-debugging).
+- [Getting started with the QDK](https://learn.microsoft.com/azure/quantum/install-overview-qdk)
+- [Getting started with Pytest](https://docs.pytest.org/en/stable/getting-started.html)

samples/testing/operations/qsharp.json

@@ -0,0 +1 @@
+{}

samples/testing/operations/src/BellState.qs

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace BellState {
+    /// # Summary
+    /// Operation that generates all bell states for testing with `dump_operation.py`.
+    ///
+    /// # Input
+    /// ## qs
+    /// Input qubit register
+    ///
+    /// ## choice
+    /// Bell state to construct.
+    /// 0: |Φ+〉(PhiPlus)
+    /// 1: |Φ-〉(PhiMinus)
+    /// 2: |Ψ+〉(PsiPlus)
+    /// 3: |Ψ-〉(PsiMinus)
+
+    operation AllBellStates(qs : Qubit[], choice : Int) : Unit is Ctl + Adj {
+        open Microsoft.Quantum.Convert;
+
+        H(qs[0]);
+        CNOT(qs[0], qs[1]);
+
+        let bitmask = IntAsBoolArray(choice, 2);
+        if bitmask[1] {
+            X(qs[1]);
+        }
+
+        if bitmask[0] {
+            Z(qs[0]);
+        }
+
+    }
+}

samples/testing/operations/src/CustomOperation.qs

@@ -0,0 +1,18 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace CustomOperation {
+    // # Summary
+    /// CNOT based operation for testing with `TestEquivalence` operation.
+    ///
+    /// # Input
+    /// ## q1
+    /// First input qubit
+    /// ## q2
+    /// Second input qubit
+    operation ApplySWAP(q1 : Qubit, q2 : Qubit) : Unit is Ctl + Adj {
+        CNOT(q1, q2); // q1, q1 xor q2
+        CNOT(q2, q1); // q2, q1 xor q2
+        CNOT(q1, q2); // q2, q1
+    }
+}

samples/testing/operations/src/OperationEquivalence.qs

@@ -0,0 +1,17 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace OperationEquivalence {
+    open Microsoft.Quantum.Diagnostics;
+    open CustomOperation;
+    /// # Summary
+    /// Verifies the equivalence of quantum operations upto a global phase using `Fact` function
+    /// and the `CheckOperationsAreEqual` operation. You can either run this here,
+    /// by clicking `Run` in VsCode or call `TestEquivalence` operation in Python.
+    @EntryPoint()
+    operation TestEquivalence() : Unit {
+        let actual = qs => CustomOperation.ApplySWAP(qs[0], qs[1]);
+        let expected = qs => SWAP(qs[0], qs[1]);
+        Fact(CheckOperationsAreEqual(2, actual, expected), "Actual and expected operation should be same");
+    }
+}

samples/testing/operations/test_operations.py

@@ -0,0 +1,115 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+import pytest
+import qsharp
+from qsharp.utils import dump_operation
+
+@pytest.fixture(autouse=True)
+def setup():
+    """Fixture to execute before a test is run"""
+    # Setting the project root to current folder.
+    qsharp.init(project_root=".")
+    yield # this is where the testing happens
+
+def test_empty_operation() -> None:
+    res = dump_operation("qs => ()", 1)
+    assert res == [
+        [1, 0],
+        [0, 1],
+    ]
+
+
+def test_single_qubit_not_gate() -> None:
+    res = dump_operation("qs => X(qs[0])", 1)
+    assert res == [
+        [0, 1],
+        [1, 0],
+    ]
+
+def test_single_qubit_hadamard_gate() -> None:
+    res = dump_operation("qs => H(qs[0])", 1)
+    assert res == [
+        [0.707107, 0.707107],
+        [0.707107, -0.707107],
+    ]
+
+def test_two_qubit_cnot_gate() -> None:
+    res = dump_operation("qs => CNOT(qs[0], qs[1])", 2)
+    assert res == [
+        [1, 0, 0, 0],
+        [0, 1, 0, 0],
+        [0, 0, 0, 1],
+        [0, 0, 1, 0],
+    ]
+
+def test_custom_operation() -> None:
+    qsharp.eval(
+        "operation ApplySWAP(qs : Qubit[]) : Unit is Ctl + Adj { SWAP(qs[0], qs[1]); }"
+    )
+
+    res = dump_operation("ApplySWAP", 2)
+    assert res == [
+        [1, 0, 0, 0],
+        [0, 0, 1, 0],
+        [0, 1, 0, 0],
+        [0, 0, 0, 1],
+    ]
+
+def test_operation_no_args_in_qsharp_file() -> None:
+    qsharp.init(project_root='.')
+
+    res = dump_operation("qs => CustomOperation.ApplySWAP(qs[0], qs[1])", 2)
+    assert res == [
+        [1, 0, 0, 0],
+        [0, 0, 1, 0],
+        [0, 1, 0, 0],
+        [0, 0, 0, 1],
+    ]
+
+def test_operation_with_args_in_qsharp_file() -> None:
+    qsharp.init(project_root='.')
+
+    res0 = dump_operation("BellState.AllBellStates(_, 0)", 2)
+
+    assert res0 == [
+        [0.707107, 0.0, 0.707107, 0.0],
+        [0.0, 0.707107, 0.0, 0.707107],
+        [0.0, 0.707107, 0.0, -0.707107],
+        [0.707107, 0.0, -0.707107, 0.0],
+    ]
+
+    res1 = dump_operation("BellState.AllBellStates(_, 1)", 2)
+
+    assert res1 == [
+        [0.707107, 0.0, 0.707107, 0.0],
+        [0.0, 0.707107, 0.0, 0.707107],
+        [0.0, -0.707107, 0.0, 0.707107],
+        [-0.707107, 0.0, 0.707107, 0.0],
+    ]
+
+    res2 = dump_operation("BellState.AllBellStates(_, 2)", 2)
+
+    assert res2 == [
+        [0.0, 0.707107, 0.0, 0.707107],
+        [0.707107, 0.0, 0.707107, 0.0],
+        [0.707107, 0.0, -0.707107, 0.0],
+        [0.0, 0.707107, 0.0, -0.707107],
+    ]
+
+    res3 = dump_operation("BellState.AllBellStates(_, 3)", 2)
+
+    assert res3 == [
+        [0.0, 0.707107, 0.0, 0.707107],
+        [0.707107, 0.0, 0.707107, 0.0],
+        [-0.707107, 0.0, 0.707107, 0.0],
+        [0.0, -0.707107, 0.0, 0.707107],
+    ]
+
+
+def test_operation_equivalence_using_fact() -> None:
+    qsharp.init(project_root='.')
+
+    qsharp.eval(
+        "OperationEquivalence.TestEquivalence()"
+    )

samples/testing/operations/test_requirements.txt

@@ -0,0 +1 @@
+pytest