{ "cells": [ { "cell_type": "markdown", "id": "0af88701-d9bc-47f2-8ceb-2ae51f567934", "metadata": {}, "source": [ "---\n", "title: Visualize circuits\n", "description: Create visualizations of circuits and plot job data using the Qiskit visualization module\n", "---\n", "\n", "{/* cspell:ignore qcircuit mactex, backgroundcolor, lightgreen */}\n", "\n" ] }, { "cell_type": "markdown", "id": "8d75dc24-b8d2-45f8-830b-48e45f794a31", "metadata": {}, "source": [ "# Visualize circuits\n", "\n" ] }, { "cell_type": "markdown", "id": "7ea76afb-aecf-4ea2-b173-5d5e7e7d68ec", "metadata": { "tags": [ "version-info" ] }, "source": [ "{/*\n", " DO NOT EDIT THIS CELL!!!\n", " This cell's content is generated automatically by a script. Anything you add\n", " here will be removed next time the notebook is run. To add new content, create\n", " a new cell before or after this one.\n", " */}\n", "\n", "\n", " \n", " The code on this page was developed using the following requirements.\n", " We recommend using these versions or newer.\n", "\n", " ```\n", " qiskit[all]~=2.4.0\n", " ```\n", " \n", "\n", "\n" ] }, { "cell_type": "markdown", "id": "bd5865b3-adfa-4c87-be55-51f693335184", "metadata": {}, "source": [ "It's often useful to see the circuits you're creating. Use the following options to display Qiskit circuits.\n", "\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "488c8d7d-5615-40ec-bf84-f1fa94832fce", "metadata": {}, "outputs": [], "source": [ "from qiskit import QuantumCircuit" ] }, { "cell_type": "markdown", "id": "8bbddcca-300c-4f20-98dd-a0723cdef026", "metadata": {}, "source": [ "## Draw a quantum circuit\n", "\n", "The `QuantumCircuit` class supports drawing circuits through the `draw()` method, or by printing the circuit object. By default, both render an ASCII art version of the circuit diagram.\n", "\n", "Note that `print` returns `None` but has the side effect of printing the diagram, whereas `QuantumCircuit.draw` returns the diagram with no side effects. Since Jupyter notebooks display the output of the last line of each cell, they appear to have the same effect.\n", "\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "547f07e8-7891-433c-ac53-3186196b3aa7", "metadata": {}, "outputs": [], "source": [ "# Build a quantum circuit\n", "circuit = QuantumCircuit(3, 3)\n", "circuit.x(1)\n", "circuit.h(range(3))\n", "circuit.cx(0, 1)\n", "circuit.measure(range(3), range(3));" ] }, { "cell_type": "code", "execution_count": 3, "id": "d69ae2df-c31c-414f-bba2-4c4a1012de41", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " ┌───┐ ┌─┐ \n", "q_0: ┤ H ├───────■──┤M├───\n", " ├───┤┌───┐┌─┴─┐└╥┘┌─┐\n", "q_1: ┤ X ├┤ H ├┤ X ├─╫─┤M├\n", " ├───┤└┬─┬┘└───┘ ║ └╥┘\n", "q_2: ┤ H ├─┤M├───────╫──╫─\n", " └───┘ └╥┘ ║ ║ \n", "c: 3/═══════╩════════╩══╩═\n", " 2 0 1 \n" ] } ], "source": [ "print(circuit)" ] }, { "cell_type": "code", "execution_count": 4, "id": "04c91fd9-50a1-4ff3-84e4-0b51a6b1541a", "metadata": {}, "outputs": [ { "data": { "text/plain": [ " ┌───┐ ┌─┐ \n", "q_0: ┤ H ├───────■──┤M├───\n", " ├───┤┌───┐┌─┴─┐└╥┘┌─┐\n", "q_1: ┤ X ├┤ H ├┤ X ├─╫─┤M├\n", " ├───┤└┬─┬┘└───┘ ║ └╥┘\n", "q_2: ┤ H ├─┤M├───────╫──╫─\n", " └───┘ └╥┘ ║ ║ \n", "c: 3/═══════╩════════╩══╩═\n", " 2 0 1 " ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "circuit.draw()" ] }, { "cell_type": "markdown", "id": "2159af06-93b8-441d-b8aa-c29324d26c6e", "metadata": {}, "source": [ "### Alternative renderers\n", "\n", "A text output is useful for quickly seeing the output while developing a circuit, but it doesn't provide the most flexibility. There are two alternative output renderers for the quantum circuit. One uses [Matplotlib](https://matplotlib.org/) and the other uses [LaTeX](https://www.latex-project.org/). The LaTeX renderer requires the [qcircuit package](https://github.com/CQuIC/qcircuit). Select these renderers by setting the \"output\" argument to the strings `mpl` and `latex`.\n", "\n", "\n", " OSX users can get the required LaTeX packages through the [mactex package](https://www.tug.org/mactex/).\n", "\n", "\n" ] }, { "cell_type": "code", "execution_count": 5, "id": "3f9c61c9-58f9-4315-a639-455fa2e58450", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Matplotlib drawing\n", "circuit.draw(output=\"mpl\")" ] }, { "cell_type": "code", "execution_count": 6, "id": "94948dab-57de-45f0-8dd7-5901ae69b70a", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Latex drawing\n", "circuit.draw(output=\"latex\")" ] }, { "cell_type": "markdown", "id": "51fc6f51-6345-435d-abed-857f29a3f451", "metadata": {}, "source": [ "### Save output\n", "\n", "Drawing a large-scale circuit inline in a Jupyter notebook can be slow or unreadable.\n", "You can save the diagram directly to a file, then open it in an image viewer and zoom in as needed.\n", "\n" ] }, { "cell_type": "code", "execution_count": 7, "id": "17889caf-d953-4661-9188-00505c17064e", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Save as an image using the Matplotlib drawer\n", "circuit.draw(output=\"mpl\", filename=\"circuit-mpl.jpeg\")" ] }, { "cell_type": "code", "execution_count": 8, "id": "a36d1aa9-fa0d-4e27-ac83-5deee43a20dd", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Or save a LaTeX rendering\n", "circuit.draw(output=\"latex\", filename=\"circuit-latex.pdf\")" ] }, { "cell_type": "markdown", "id": "78688e6c-3ed2-4ef2-b3db-80fdae35e585", "metadata": { "jp-MarkdownHeadingCollapsed": true }, "source": [ "### Control circuit drawings\n", "\n", "By default, the `draw()` method returns the rendered image as an object and does not output anything. The exact class returned depends on the output specified: `'text'` (the default) returns a `TextDrawer` object, `'mpl'` returns a `matplotlib.Figure` object, and `latex` returns a `PIL.Image` object. Jupyter notebooks understand these return types and render them properly, but when running outside of Jupyter, images will not display automatically.\n", "\n", "The `draw()` method has optional arguments to display or save the output. When specified, the `filename` kwarg takes a path to which it saves the rendered output. Alternatively, if you're using the `mpl` or `latex` outputs, you can use the `interactive` kwarg to open the image in a new window (this will not always work from within a notebook).\n", "\n" ] }, { "cell_type": "markdown", "id": "fc41270b-3518-40af-8921-dfa9666fc8e0", "metadata": {}, "source": [ "### Customize the output\n", "\n", "Depending on the output, there are also options to customize the circuit diagram.\n", "\n", "#### Disable plot barriers and reverse bit order\n", "\n", "The first two options are shared among all three backends. They allow you to configure both the bit orders and whether or not you draw barriers. These can be set by the `reverse_bits` kwarg and `plot_barriers` kwarg, respectively. The following examples work with any output renderer; `mpl` is used here for brevity.\n", "\n" ] }, { "cell_type": "code", "execution_count": 9, "id": "db61dc71-4cdc-4bb7-8139-8820e7785e55", "metadata": {}, "outputs": [], "source": [ "from qiskit import QuantumRegister, ClassicalRegister\n", "\n", "# Draw a new circuit with barriers and more registers\n", "q_a = QuantumRegister(3, name=\"a\")\n", "q_b = QuantumRegister(5, name=\"b\")\n", "c_a = ClassicalRegister(3)\n", "c_b = ClassicalRegister(5)\n", "\n", "circuit = QuantumCircuit(q_a, q_b, c_a, c_b)\n", "circuit.x(q_a[1])\n", "circuit.x(q_b[1])\n", "circuit.x(q_b[2])\n", "circuit.x(q_b[4])\n", "circuit.barrier()\n", "circuit.h(q_a)\n", "circuit.barrier(q_a)\n", "circuit.h(q_b)\n", "circuit.cswap(q_b[0], q_b[1], q_b[2])\n", "circuit.cswap(q_b[2], q_b[3], q_b[4])\n", "circuit.cswap(q_b[3], q_b[4], q_b[0])\n", "circuit.barrier(q_b)\n", "circuit.measure(q_a, c_a)\n", "circuit.measure(q_b, c_b);" ] }, { "cell_type": "code", "execution_count": 10, "id": "8e57cd43-8a48-469d-8f69-8e7c936d4a1e", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 10, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Draw the circuit\n", "circuit.draw(output=\"mpl\")" ] }, { "cell_type": "code", "execution_count": 11, "id": "8e7a251a-0a4f-43e0-8cf5-48493df7bad9", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 11, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Draw the circuit with reversed bit order\n", "circuit.draw(output=\"mpl\", reverse_bits=True)" ] }, { "cell_type": "code", "execution_count": 12, "id": "b4a601ad-1c04-4b16-afbd-ac5a0ad42653", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 12, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Draw the circuit without barriers\n", "circuit.draw(output=\"mpl\", plot_barriers=False)" ] }, { "cell_type": "markdown", "id": "18b0bfbe-b586-4182-9a0d-b858655a9240", "metadata": {}, "source": [ "### Renderer-specific customizations\n", "\n", "Some available customizing options are specific to a renderer.\n", "\n", "The `fold` argument sets a maximum width for the output. In the `text` renderer, this sets the length of the lines of the diagram before it is wrapped to the next line. When using the 'mpl' renderer, this is the number of (visual) layers before folding to the next line.\n", "\n", "The `mpl` renderer has the `style` kwarg, which changes the colors and outlines. See the [API documentation](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#draw) for more details.\n", "\n", "The `scale` option scales the output of the `mpl` and `latex` renderers.\n", "\n" ] }, { "cell_type": "code", "execution_count": 13, "id": "1e08bf74-378f-45e6-b195-a9539061013d", "metadata": {}, "outputs": [ { "data": { "text/plain": [ " ┌───┐┌───┐┌───┐┌───┐┌───┐┌───┐┌───┐»\n", "q: ┤ H ├┤ H ├┤ H ├┤ H ├┤ H ├┤ H ├┤ H ├»\n", " └───┘└───┘└───┘└───┘└───┘└───┘└───┘»\n", "« ┌───┐┌───┐┌───┐\n", "«q: ┤ H ├┤ H ├┤ H ├\n", "« └───┘└───┘└───┘" ] }, "execution_count": 13, "metadata": {}, "output_type": "execute_result" } ], "source": [ "circuit = QuantumCircuit(1)\n", "for _ in range(10):\n", " circuit.h(0)\n", "# limit line length to 40 characters\n", "circuit.draw(output=\"text\", fold=40)" ] }, { "cell_type": "code", "execution_count": 14, "id": "decadf88-4866-45a0-9e2f-836c51491f9e", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 14, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Change the background color in mpl\n", "\n", "style = {\"backgroundcolor\": \"lightgreen\"}\n", "circuit.draw(output=\"mpl\", style=style)" ] }, { "cell_type": "code", "execution_count": 15, "id": "ade9a653-3243-4ac9-bb0e-c8fb82f7a034", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 15, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Scale the mpl output to 1/2 the normal size\n", "circuit.draw(output=\"mpl\", scale=0.5)" ] }, { "cell_type": "markdown", "id": "495b560a-d835-448b-aa01-5025a7a0689e", "metadata": {}, "source": [ "### Standalone circuit-drawing function\n", "\n", "If you have an application where you prefer to draw a circuit with a self-contained function instead of as a method of a circuit object, you can directly use the `circuit_drawer()` function, which is part of the public stable interface from `qiskit.visualization`. The function behaves identically to the `circuit.draw()` method, except that it takes in a circuit object as a required argument.\n", "\n" ] }, { "cell_type": "code", "execution_count": 16, "id": "256dd092-b2eb-47af-a025-0ecdf85c2d5a", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 16, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from qiskit.visualization import circuit_drawer\n", "\n", "circuit_drawer(circuit, output=\"mpl\", plot_barriers=False)" ] }, { "cell_type": "markdown", "id": "0761df2f-183f-48e3-9070-766a9920c2b9", "metadata": {}, "source": [ "## Next steps\n", "\n", "\n", " * See an example of circuit visualization in the [Grover's Algorithm](/docs/tutorials/grovers-algorithm) tutorial.\n", " * Visualize simple circuits using [IBM Quantum Composer](/docs/guides/composer).\n", " * [Visualize circuit timing](/docs/guides/visualize-circuit-timing).\n", " * Review the [Qiskit visualizations API documentation](/docs/api/qiskit/visualization).\n", "\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "id": "a1b8767d", "source": "© IBM Corp., 2017-2026" } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3" } }, "nbformat": 4, "nbformat_minor": 4 }