Add a sample for modern QDK project with Python (#1721)

This resolves [Issue
1384](#1384).

- Added [Teleportation project from the
documentation](https://learn.microsoft.com/en-us/azure/quantum/user-guide/how-to-work-with-qsharp-projects?tabs=tabid-qsharp%2Ctabid-python-run#steps-for-creating-a-q-project)
- Q# taking N, generating N random bits, and returning an array of them,
and Python counting the number of 1s in the results

---------

Co-authored-by: Mariia Mykhailova <michaylova@gmail.com>
Co-authored-by: Bill Ticehurst <billti@hotmail.com>
Co-authored-by: Manvi-Agrawal <40084144+Manvi-Agrawal@users.noreply.github.com>
Co-authored-by: César Zaragoza Cortés <cesarzc@microsoft.com>

samples/python_interop/generating_n_random_bits/README.md

@@ -0,0 +1,3 @@
+# Passing arguments from Python to Q# and processing measurement results in Python
+
+In this example, a Q# program generates an array of random bits of user-defined length (`nQubits`). The program creates a random bit sequence by applying an $H$ gate to each of the qubits, measuring them, and returning a tuple containing the measurement results in an array along with the integer representation of the generated bits or the random number. The Python program then processes the resulting array of bits by counting the number of `One`s and displays this count along with the array of random bits and the integer representation of the generated bits.

samples/python_interop/generating_n_random_bits/RunGenerateRandom.py

@@ -0,0 +1,15 @@
+import qsharp
+
+qsharp.init(project_root=".")
+
+nQubits = input("Enter the number of random bits to be generated: ")
+(results, number) = qsharp.eval(f"GenerateRandom.GenerateRandomNumbers({nQubits})")
+
+count = 0
+for result in results:
+    if result == qsharp.Result.One:
+        count += 1
+
+print(f"Bits generated: {results}")
+print(f"Number of Ones: {count}")
+print(f"The integer representation of the generated {nQubits} bits: {number}")

samples/python_interop/generating_n_random_bits/qsharp.json

@@ -0,0 +1,4 @@
+{
+    "author":"Microsoft",
+    "license":"MIT"
+}

samples/python_interop/generating_n_random_bits/src/GenerateRandomNumbers.qs

@@ -0,0 +1,15 @@
+namespace GenerateRandom {
+    open Microsoft.Quantum.Arrays;
+    open Microsoft.Quantum.Convert;
+
+    operation GenerateRandomNumbers(nQubits : Int) : (Result[], Int) {
+        use qubits = Qubit[nQubits];
+
+        ApplyToEach(H, qubits);
+
+        let result = MResetEachZ(qubits);
+        let number = ResultArrayAsInt(Reversed(result));
+
+        return (result, number);
+    }
+}

samples/python_interop/teleportation_project/README.md

@@ -0,0 +1,9 @@
+# An example multi-file Q# project with Python classical host
+
+The example project demonstrates a Q# quantum teleportation program implemented as a multi-file project, designed to be executed from Python classical code. 
+
+The `qsharp.json` manifest is located at the root folder. The `src` directory includes the Q# source files which are organized into subfolders. The main file, `RunTeleport.qs`, contains the entry point and references operations defined in other files. The teleportation logic is implemented in `Teleport.qs`, which uses a standard operation from `PrepareState.qs` to create a Bell pair.
+
+You can execute this project by navigating to its root folder and running `python .\RunTeleport.py`. Alternatively, you can open the folder in Visual Studio Code, open the file `RunTeleport.qs`, and select **Run**.
+
+Full details are available on the [Microsoft Learn page](https://learn.microsoft.com/azure/quantum/user-guide/how-to-work-with-qsharp-projects?tabs=tabid-qsharp%2Ctabid-python-run#example-project).

samples/python_interop/teleportation_project/RunTeleport.py

@@ -0,0 +1,10 @@
+import qsharp
+
+# set the root folder for the Q# project
+# the root folder of a Q# project is where the qsharp.json file is located
+# make adjustments to the path depending on the location of the qsharp.json file
+
+# this example assumes your Python program is in the same folder as the qsharp.json file
+qsharp.init(project_root=".")
+
+print(qsharp.eval("RunTeleport.RunTeleportationExample()"))

samples/python_interop/teleportation_project/qsharp.json

@@ -0,0 +1,4 @@
+{
+    "author":"Microsoft",
+    "license":"MIT"
+}

samples/python_interop/teleportation_project/src/RunTeleport.qs

@@ -0,0 +1,21 @@
+namespace RunTeleport {
+
+    open TeleportLib;   // references the TeleportLib namespace in Teleport.qs
+
+    @EntryPoint()       // @EntryPoint() not necessary for Python or Jupyter Notebook programs
+    operation RunTeleportationExample() : Unit {
+        use msg = Qubit();
+        use target = Qubit();
+
+        H(msg);
+        Teleport(msg, target);    // calls the Teleport() operation from Teleport.qs
+        H(target);
+
+        if M(target) == Zero {
+            Message("Teleported successfully!");
+
+            Reset(msg);
+            Reset(target);
+        }
+    }
+}

samples/python_interop/teleportation_project/src/TeleportOperations/PrepareState/PrepareState.qs

@@ -0,0 +1,7 @@
+namespace PrepareBell {
+
+    operation PrepareBellPair(left : Qubit, right : Qubit) : Unit is Adj + Ctl {
+        H(left);
+        CNOT(left, right);
+    }
+}

samples/python_interop/teleportation_project/src/TeleportOperations/Teleport.qs

@@ -0,0 +1,16 @@
+namespace TeleportLib {
+
+    open PrepareBell;     // references the PrepareBell namespace in PrepareState.qs
+
+    operation Teleport(msg : Qubit, target : Qubit) : Unit {
+        use here = Qubit();
+
+        PrepareBellPair(here, target);      // calls the PrepareBellPair() operation from PrepareState.qs
+        Adjoint PrepareBellPair(msg, here);
+
+        if M(msg) == One { Z(target); }
+        if M(here) == One { X(target); }
+
+        Reset(here);
+    }
+}