Add documentation for QASM export (#6891)

* Add documentation for QASM export - This PR adds documentation for OpenQASM export, and also shows how to change version of OpenQASM output. It also clarifies which versions are supported. * Add missing metadata keys. * execution count * Update isolated notebook * Add disclaimer. * Add missing comma --------- Co-authored-by: Michael Hucka <mhucka@caltech.edu>
quantumlib · Jan 2, 2025 · c5d29fe · c5d29fe
1 parent 4ad58f6
commit c5d29fe
Show file tree

Hide file tree

Showing 2 changed files with 107 additions and 3 deletions.
diff --git a/dev_tools/notebooks/isolated_notebook_test.py b/dev_tools/notebooks/isolated_notebook_test.py
@@ -44,6 +44,8 @@
 NOTEBOOKS_DEPENDING_ON_UNRELEASED_FEATURES: List[str] = [
     # Requires pinned quimb from #6438
     'cirq-core/cirq/contrib/quimb/Contract-a-Grid-Circuit.ipynb',
+    # Requires OpenQASM 3.0 support from cirq 1.6
+    'docs/build/interop.ipynb',
     # get_qcs_objects_for_notebook
     'docs/noise/calibration_api.ipynb',
     'docs/noise/floquet_calibration_example.ipynb',

diff --git a/docs/build/interop.ipynb b/docs/build/interop.ipynb
@@ -74,7 +74,8 @@
     "    import cirq\n",
     "except ImportError:\n",
     "    print(\"installing cirq...\")\n",
-    "    !pip install --quiet cirq\n",
+    "    # Cirq 1.6 needed for OpenQASM 3.0 support",
+    "    !pip install --quiet cirq~=1.0.dev\n",
     "    print(\"installed cirq.\")"
    ]
   },
@@ -84,7 +85,8 @@
     "id": "S541ev7MvVe4"
    },
    "source": [
-    "Cirq has several features that allow the user to import/export from other quantum languages."
+    "Cirq has several features that allow the user to import/export from other quantum languages.",
+    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install cirq~=1.0.dev`."
    ]
   },
   {
@@ -190,7 +192,7 @@
    "source": [
     "## Importing from OpenQASM\n",
     "\n",
-    "The QASM importer is in an experimental state and currently only supports a subset of the full **OpenQASM spec**. Amongst others, classical control, arbitrary gate definitions, and even some of the gates that don't have a one-to-one representation in Cirq, are not yet supported. The functionality should be sufficient to import interesting quantum circuits. Error handling is very simple - on any lexical or syntactical error, a `QasmException` is raised.\n",
+    "The QASM importer is in an experimental state and currently only supports a subset of the full **OpenQASM spec**. However, both OpenQASM 2.0 and 3.0 have this limited support. Amongst others, classical control, arbitrary gate definitions, and even some of the gates that don't have a one-to-one representation in Cirq, are not yet supported. The functionality should be sufficient to import interesting quantum circuits. Error handling is very simple - on any lexical or syntactical error, a `QasmException` is raised.\n",
     "\n",
     "### Importing cirq.Circuit from QASM format\n",
     "\n",
@@ -250,6 +252,48 @@
     "print(circuit)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "source": [
+     "OpenQASM 3.0 also has limited support, which can be seen by the following code:"
+   ],
+   "metadata": {
+     "id": "K_aS_FJxVoHI"
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "source": [
+     "from cirq.contrib.qasm_import import circuit_from_qasm\n",
+     "circuit = circuit_from_qasm(\"\"\"\n",
+     "OPENQASM 3.0;\n",
+     "include \"stdgates.inc\";\n",
+     "\n",
+     "// Qubits: [q0]\n",
+     "qubit[2] q;\n",
+     "bit[2] m_mmm;\n",
+     "\n",
+     "x q;\n",
+     "m_mmm = measure q;\n",
+     "\"\"\")\n",
+     "print(circuit)"
+   ],
+   "metadata": {
+        "id": "LHFjG9trvhla"
+   },
+   "outputs": [
+     {
+       "output_type": "stream",
+       "name": "stdout",
+       "text": [
+         "q_0: ───X───M('m_mmm_0')───\n",
+         "\n",
+         "q_1: ───X───M('m_mmm_1')───\n"
+       ]
+     }
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {
@@ -336,6 +380,64 @@
     "For a classical register `creg cbar[n];` the QASM importer will create measurement keys named `cbar_0`..`cbar_<n-1>`. "
    ]
   },
+  {
+   "cell_type": "markdown",
+   "source": [
+     "### Exporting cirq.Circuit to QASM format\n",
+     "\n",
+     "Cirq also has the ability to export circuits in OpenQASM format using either OpenQasm 2.0 or 3.0 formats. This can be done using the `circuit.to_qasm()` function, such as\n",
+     "`circuit.to_qasm(version=\"3.0\")` or by using the `cirq.qasm` protocol, as follows:\n"
+   ],
+   "metadata": {
+     "id": "fyyz_GGdY5uZ"
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "source": [
+     "q0 = cirq.NamedQubit('q0')\n",
+     "circuit = cirq.Circuit(cirq.X(q0), cirq.measure(q0, key='mmm'))\n",
+     "qasm_str = cirq.qasm(circuit, args=cirq.QasmArgs(version=\"3.0\"))\n",
+     "print(qasm_str)"
+   ],
+   "metadata": {
+        "id": "w62L_PMeVvYl"
+   },
+   "outputs": [
+     {
+       "output_type": "stream",
+       "name": "stdout",
+       "text": [
+         "// Generated from Cirq v1.5.0.dev20241221000556\n",
+         "\n",
+         "OPENQASM 3.0;\n",
+         "include \"stdgates.inc\";\n",
+         "\n",
+         "\n",
+         "// Qubits: [q0]\n",
+         "qubit[1] q;\n",
+         "bit[1] m_mmm;\n",
+         "\n",
+         "\n",
+         "x q[0];\n",
+         "m_mmm[0] = measure q[0];\n",
+         "\n"
+       ]
+     }
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+     " Currently supported version strings are \"2.0\" and \"3.0\".\n",
+     "\n",
+     " By default, if no version is specified, circuits are currently exported in OpenQasm 2.0 format.  This default behavior may change in the future so be sure to specify the argument if a specific version of OpenQASM is desired.\n"
+   ],
+   "metadata": {
+     "id": "E496hCqZZZUt"
+   }
+  },
   {
    "cell_type": "markdown",
    "metadata": {