Merge pull request #41 from qsharp-community/quantikz-scope

added scope grouping for quantikz

Author: filipw

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "qsharp-bridge"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

Cargo.toml

@@ -6,7 +6,7 @@
    "source": [
     "First, import the library.\n",
     "\n",
-    "You will also need to have LaTeX installed on your system for rendering the diagrams. We also import official Q# library as we will use it for comparison of the generated diagrams."
+    "We will also need to have LaTeX installed on your system for rendering the diagrams. We also import official Q# library as we will use it for comparison of the generated diagrams."
    ]
   },
   {
@@ -29,7 +29,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Next, load the Jupyter TikZ extension. "
+    "Next, let's load the Jupyter TikZ extension. "
    ]
   },
   {
@@ -45,7 +45,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now you can write some Q# code. This will be the Q# code for which we will generate a circuit diagram."
+    "Now we can write some Q# code. This will be the Q# code for which we will generate a circuit diagram. We will set up two test code snippets - one that consists of a single operation, and another that has an operation calling another operation."
    ]
   },
   {
@@ -55,6 +55,23 @@
    "outputs": [],
    "source": [
     "code_1 = \"\"\"\n",
+    "operation Main() : Result[] {\n",
+    "    use qubits = Qubit[8];\n",
+    "\n",
+    "    // apply Hadamard gate to the first qubit\n",
+    "    H(qubits[0]);\n",
+    "\n",
+    "    // apply CNOT gates to create entanglement\n",
+    "    for qubit in qubits[1..Length(qubits) - 1] {\n",
+    "        CNOT(qubits[0], qubit);\n",
+    "    }\n",
+    "\n",
+    "    // return measurement results\n",
+    "    MResetEachZ(qubits)\n",
+    "}\n",
+    "\"\"\"\n",
+    "\n",
+    "code_2 = \"\"\"\n",
     "namespace MyQuantumApp {\n",
     "    @EntryPoint()\n",
     "    operation Run() : (Result, Result) {\n",
@@ -71,31 +88,14 @@
     "        CNOT(q1, q2);\n",
     "    }\n",
     "}\n",
-    "\"\"\"\n",
-    "\n",
-    "code_2 = \"\"\"\n",
-    "operation Main() : Result[] {\n",
-    "    use qubits = Qubit[8];\n",
-    "\n",
-    "    // apply Hadamard gate to the first qubit\n",
-    "    H(qubits[0]);\n",
-    "\n",
-    "    // apply CNOT gates to create entanglement\n",
-    "    for qubit in qubits[1..Length(qubits) - 1] {\n",
-    "        CNOT(qubits[0], qubit);\n",
-    "    }\n",
-    "\n",
-    "    // return measurement results\n",
-    "    MResetEachZ(qubits)\n",
-    "}\n",
     "\"\"\""
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Once the Q# code is written, you can use the `quantikz` function to generate and display the circuit diagram directly in the Jupyter notebook."
+    "Once the Q# code is written, we can use the `quantikz` function to generate and display the circuit diagram directly in the Jupyter notebook."
    ]
   },
   {
@@ -104,8 +104,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "quantikz_diagram_1 = quantikz(code_1)\n",
-    "quantikz_diagram_2 = quantikz(code_2)\n",
+    "quantikz_diagram_1 = quantikz(code_1, options=QuantikzGenerationOptions(group_by_scope=False))\n",
+    "quantikz_diagram_2 = quantikz(code_2, options=QuantikzGenerationOptions(group_by_scope=False))\n",
     "\n",
     "# for debugging, display the generated LaTeX code\n",
     "print(quantikz_diagram_1)\n",
@@ -116,7 +116,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Use the TikZ extension to render a PDF from the LaTeX code generated by Q# Bridge."
+    "We can now use the TikZ extension to render a PDF from the LaTeX code generated by Q# Bridge to verify the output."
    ]
   },
   {
@@ -143,6 +143,13 @@
     "shell.run_cell_magic('tikz', '-l quantikz', quantikz_diagram_2)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Notice how the two-operation sample was actually decomposed into its constituent individual gates in the generated diagram - this is because we set `group_by_scope` to `False` in the `QuantikzGenerationOptions` when generating the diagrams."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -158,7 +165,7 @@
    "source": [
     "qsharp.init() # this ensures clean state\n",
     "qsharp.eval(code_1)\n",
-    "Circuit(qsharp.circuit(\"MyQuantumApp.Run()\")) "
+    "Circuit(qsharp.circuit(\"Main()\"))  "
    ]
   },
   {
@@ -170,7 +177,7 @@
     "\n",
     "qsharp.init() # this ensures clean state\n",
     "qsharp.eval(code_2)\n",
-    "Circuit(qsharp.circuit(\"Main()\"))  "
+    "Circuit(qsharp.circuit(\"MyQuantumApp.Run()\")) "
    ]
   },
   {
@@ -179,6 +186,39 @@
    "source": [
     "We should see that the diagrams generated using `quantikz` and the built-in `Circuit` widget are identical. This confirms that our LaTeX generation is working correctly!"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Q# compiler (and, by extension, Q# Bridge) can also group gates on the circuit into groups scoped by an operation. In our case that would mean a large single block representing `PrepareBellState`.\n",
+    "\n",
+    "Let's set `group_by_scope` of the `QuantikzGenerationOptions` to `True` and pass that into the `quantikz` function - and see how the generated diagram changes."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "quantikz_diagram_3 = quantikz(code_2, options=QuantikzGenerationOptions(group_by_scope=True))\n",
+    "\n",
+    "# for debugging, display the generated LaTeX code\n",
+    "print(quantikz_diagram_3)\n",
+    "\n",
+    "shell = get_ipython()\n",
+    "assert shell is not None\n",
+    "\n",
+    "shell.run_cell_magic('tikz', '-l quantikz', quantikz_diagram_3)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Congratualations! You have successfully generated quantum circuit diagrams from Q# code using Q# Bridge and LaTeX in a Jupyter notebook."
+   ]
   }
  ],
  "metadata": {

examples/python/jupyter/quantikz.ipynb

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <TargetFramework>net8.0</TargetFramework>
-    <Version>0.2.0</Version>
+    <Version>0.2.1</Version>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>

platforms/csharp/QSharp.Community.QSharpBridge/QSharp.Community.QSharpBridge.csproj

@@ -14,7 +14,7 @@
 CARGO_MANIFEST_PATH = os.path.abspath(os.path.join(HERE, "../../../Cargo.toml"))
 CARGO_TARGET_DIR = os.path.abspath(os.path.join(HERE, "../../../target/release"))
 BINDINGS_SRC = os.path.abspath(os.path.join(HERE, "../../../bindings/qsharp_bridge.py"))
-VERSION = os.environ.get("PACKAGE_VERSION", "0.2.0")
+VERSION = os.environ.get("PACKAGE_VERSION", "0.2.1")
 
 def get_lib_filename():
     """

platforms/python/qsharp-bridge/setup.py

@@ -17,6 +17,7 @@ use crate::sim::run_qs;
 use crate::sim::run_qs_with_options;
 use crate::quantikz::quantikz;
 use crate::quantikz::quantikz_operation;
+use crate::quantikz::QuantikzGenerationOptions;
 
 pub mod noise;
 pub mod qasm;

src/lib.rs

@@ -16,10 +16,10 @@ namespace qsharp_bridge {
     string qasm2_expression([ByRef]string expression, QasmGenerationOptions generation_options);
 
     [Throws=QsError]
-    string quantikz([ByRef]string source);
+    string quantikz([ByRef]string source, QuantikzGenerationOptions options);
 
     [Throws=QsError]
-    string quantikz_operation([ByRef]string operation, [ByRef]string source);
+    string quantikz_operation([ByRef]string operation, [ByRef]string source, QuantikzGenerationOptions options);
 
     [Throws=QsError]
     string estimate([ByRef]string source, string? job_params);
@@ -33,6 +33,10 @@ dictionary QasmGenerationOptions {
     QasmResetBehavior reset_behavior;
 };
 
+dictionary QuantikzGenerationOptions {
+    boolean group_by_scope;
+};
+
 enum QasmResetBehavior {
     "Supported",
     "Ignored",