From e5870a44ab8b866c6acb8b5449ec1bb15633dcc8 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Fri, 11 Oct 2019 21:18:26 -0400 Subject: [PATCH] Update docstring for circuit_drawer and QuantumCircuit.draw (#3219) * Update docstring for circuit_drawer and QuantumCircuit.draw The docstrings for both the qiskit.visualization.circuit_drawer() function and the qiskit.circuit.QuantumCircuit.draw() method were quite stale. With numerous formatting issues and out of date information. This commit goes through them and updates both the style and contents to render correctly in sphinx and reflect the current state of the functions. * Apply suggestions from code review Co-Authored-By: Ali Javadi-Abhari * Fix lint issues introduced by github web editor * Add style dict doc to circuit draw() method --- qiskit/circuit/quantumcircuit.py | 200 +++++++++++--- qiskit/visualization/circuit_visualization.py | 250 ++++++++++-------- 2 files changed, 301 insertions(+), 149 deletions(-) diff --git a/qiskit/circuit/quantumcircuit.py b/qiskit/circuit/quantumcircuit.py index a7b738c66d5b..4633945b3e29 100644 --- a/qiskit/circuit/quantumcircuit.py +++ b/qiskit/circuit/quantumcircuit.py @@ -564,72 +564,192 @@ def draw(self, scale=0.7, filename=None, style=None, output=None, with_layout=True, fold=None, ax=None): """Draw the quantum circuit - Using the output parameter you can specify the format. The choices are: - 0. text: ASCII art string - 1. latex: high-quality images, but heavy external software dependencies - 2. matplotlib: purely in Python with no external dependencies + **text**: ASCII art TextDrawing that can be printed in the console. - Defaults to an overcomplete basis, in order to not alter gates. + **latex**: high-quality images compiled via latex. + + **latex_source**: raw uncompiled latex output. + + **matplotlib**: images with color rendered purely in Python. Args: scale (float): scale of image to draw (shrink if < 1) filename (str): file path to save image to style (dict or str): dictionary of style or file name of style - file. You can refer to the - :ref:`Style Dict Doc ` for more information - on the contents. + file. This option is only used by the ``mpl`` output type. If a + str is passed in that is the path to a json file which contains + that will be open, parsed, and then used just as the input + dict. See: :ref:`Style Dict Doc ` for more + information on the contents. output (str): Select the output method to use for drawing the - circuit. Valid choices are `text`, `latex`, `latex_source`, - `mpl`. By default the 'text' drawer is used unless a user - config file has an alternative backend set as the default. If - the output is passed in that backend will always be used. + circuit. Valid choices are ``text``, ``latex``, + ``latex_source``, or ``mpl``. By default the `'text`' drawer is + used unless a user config file has an alternative backend set + as the default. If the output kwarg is set, that backend + will always be used over the default in a user config file. interactive (bool): when set true show the circuit in a new window (for `mpl` this depends on the matplotlib backend being used supporting this). Note when used with either the `text` or the `latex_source` output type this has no effect and will be silently ignored. - line_length (int): sets the length of the lines generated by `text` + line_length (int): Deprecated, see `fold` which supersedes this + option. Sets the length of the lines generated by `text` output + type. This useful when the drawing does not fit in the console. + If None (default), it will try to guess the console width using + ``shutil.get_terminal_size()``. However, if you're running in + jupyter the default line length is set to 80 characters. If you + don't want pagination at all, set ``line_length=-1``. reverse_bits (bool): When set to True reverse the bit order inside registers for the output visualization. plot_barriers (bool): Enable/disable drawing barriers in the output circuit. Defaults to True. - justify (string): Options are `left`, `right` or `none`, if anything - else is supplied it defaults to left justified. It refers to where - gates should be placed in the output circuit if there is an option. - `none` results in each gate being placed in its own column. Currently - only supported by text drawer. - vertical_compression (string): `high`, `medium` or `low`. It merges the - lines generated by `text` so the drawing will take less vertical room. - Default is `medium`. It is ignored if output is not `text`. - idle_wires (bool): Include idle wires. Default is True. - with_layout (bool): Include layout information, with labels on the physical - layout. Default is True. + justify (string): Options are ``left``, ``right`` or + ``none``, if anything else is supplied it defaults to left + justified. It refers to where gates should be placed in the + output circuit if there is an option. ``none`` results in + each gate being placed in its own column. + vertical_compression (string): ``high``, ``medium`` or ``low``. It + merges the lines generated by the ``text`` output so the + drawing will take less vertical room. Default is ``medium``. + Only used by the ``text`` output, will be silently ignored + otherwise. + idle_wires (bool): Include idle wires (wires with no circuit + elements) in output visualization. Default is True. + with_layout (bool): Include layout information, with labels on the + physical layout. Default is True. fold (int): Sets pagination. It can be disabled using -1. In `text`, sets the length of the lines. This useful when the - drawing does not fit in the console. If None (default), it will try to - guess the console width using `shutil.get_terminal_size()`. However, if - running in jupyter, the default line length is set to 80 characters. - In `mpl` is the amount of operations before folding. Default is 25. + drawing does not fit in the console. If None (default), it will + try to guess the console width using ``shutil. + get_terminal_size()``. However, if running in jupyter, the + default line length is set to 80 characters. In ``mpl`` is the + number of (visual) layers before folding. Default is 25. ax (matplotlib.axes.Axes): An optional Axes object to be used for the visualization output. If none is specified a new matplotlib - Figure will be created and used. Additionally, if specified there - will be no returned Figure since it is redundant. This is only used - when the ``output`` kwarg is set to use the ``mpl`` backend. It - will be silently ignored with all other outputs. + Figure will be created and used. Additionally, if specified + there will be no returned Figure since it is redundant. This is + only used when the ``output`` kwarg is set to use the ``mpl`` + backend. It will be silently ignored with all other outputs. Returns: - PIL.Image or matplotlib.figure or str or TextDrawing: - * PIL.Image: (output `latex`) an in-memory representation of the - image of the circuit diagram. - * matplotlib.figure: (output `mpl`) a matplotlib figure object - for the circuit diagram, if the ``ax`` kwarg is not set. - * str: (output `latex_source`). The LaTeX source code. - * TextDrawing: (output `text`). A drawing that can be printed as - ascii art + :class:`PIL.Image` or :class:`matplotlib.figure` or :class:`str` or + :class:`TextDrawing`: + + * `PIL.Image` (output='latex') + an in-memory representation of the image of the circuit + diagram. + * `matplotlib.figure.Figure` (output='mpl') + a matplotlib figure object for the circuit diagram. + * `str` (output='latex_source') + The LaTeX source code for visualizing the circuit diagram. + * `TextDrawing` (output='text') + A drawing that can be printed as ascii art Raises: VisualizationError: when an invalid output method is selected + ImportError: when the output methods requires non-installed + libraries. + + .. _style-dict-circ-doc: + + **Style Dict Details** + + The style dict kwarg contains numerous options that define the style of + the output circuit visualization. The style dict is only used by the + ``mpl`` output. The options available in the style dict are defined + below: + + Args: + textcolor (str): The color code to use for text. Defaults to + `'#000000'` + subtextcolor (str): The color code to use for subtext. Defaults to + `'#000000'` + linecolor (str): The color code to use for lines. Defaults to + `'#000000'` + creglinecolor (str): The color code to use for classical register + lines. Defaults to `'#778899'` + gatetextcolor (str): The color code to use for gate text. Defaults + to `'#000000'` + gatefacecolor (str): The color code to use for gates. Defaults to + `'#ffffff'` + barrierfacecolor (str): The color code to use for barriers. + Defaults to `'#bdbdbd'` + backgroundcolor (str): The color code to use for the background. + Defaults to `'#ffffff'` + fontsize (int): The font size to use for text. Defaults to 13 + subfontsize (int): The font size to use for subtext. Defaults to 8 + displaytext (dict): A dictionary of the text to use for each + element type in the output visualization. The default values + are:: + + { + 'id': 'id', + 'u0': 'U_0', + 'u1': 'U_1', + 'u2': 'U_2', + 'u3': 'U_3', + 'x': 'X', + 'y': 'Y', + 'z': 'Z', + 'h': 'H', + 's': 'S', + 'sdg': 'S^\\dagger', + 't': 'T', + 'tdg': 'T^\\dagger', + 'rx': 'R_x', + 'ry': 'R_y', + 'rz': 'R_z', + 'reset': '\\left|0\\right\\rangle' + } + + You must specify all the necessary values if using this. There + is no provision for passing an incomplete dict in. + displaycolor (dict): The color codes to use for each circuit + element. The default values are:: + + { + 'id': '#F0E442', + 'u0': '#E7AB3B', + 'u1': '#E7AB3B', + 'u2': '#E7AB3B', + 'u3': '#E7AB3B', + 'x': '#58C698', + 'y': '#58C698', + 'z': '#58C698', + 'h': '#70B7EB', + 's': '#E0722D', + 'sdg': '#E0722D', + 't': '#E0722D', + 'tdg': '#E0722D', + 'rx': '#ffffff', + 'ry': '#ffffff', + 'rz': '#ffffff', + 'reset': '#D188B4', + 'target': '#70B7EB', + 'meas': '#D188B4' + } + + Also, just like `displaytext` there is no provision for an + incomplete dict passed in. + + latexdrawerstyle (bool): When set to True enable latex mode which + will draw gates like the `latex` output modes. + usepiformat (bool): When set to True use radians for output + fold (int): The number of circuit elements to fold the circuit at. + Defaults to 20 + cregbundle (bool): If set True bundle classical registers + showindex (bool): If set True draw an index. + compress (bool): If set True draw a compressed circuit + figwidth (int): The maximum width (in inches) for the output figure. + dpi (int): The DPI to use for the output image. Defaults to 150 + margin (list): A list of margin values to adjust spacing around + output image. Takes a list of 4 ints: + [x left, x right, y bottom, y top]. + creglinestyle (str): The style of line to use for classical + registers. Choices are `'solid'`, `'doublet'`, or any valid + matplotlib `linestyle` kwarg value. Defaults to `doublet` """ + # pylint: disable=cyclic-import from qiskit.visualization import circuit_drawer return circuit_drawer(self, scale=scale, diff --git a/qiskit/visualization/circuit_visualization.py b/qiskit/visualization/circuit_visualization.py index 9ee337ee7ac7..31e8b9d3a354 100644 --- a/qiskit/visualization/circuit_visualization.py +++ b/qiskit/visualization/circuit_visualization.py @@ -14,10 +14,17 @@ """ -Two quantum circuit drawers based on: - 0. Ascii art - 1. LaTeX - 2. Matplotlib +Module for the primary interface to the circuit drawers. + +This module contains the end user facing API for drawing quantum circuits. +There are 3 available drawer backends available: + + 0. Ascii art + 1. LaTeX + 2. Matplotlib + +This provides a single function entrypoint to drawing a circuit object with +any of the backends. """ import errno @@ -59,161 +66,186 @@ def circuit_drawer(circuit, fold=None, ax=None): """Draw a quantum circuit to different formats (set by output parameter): - 0. text: ASCII art TextDrawing that can be printed in the console. - 1. latex: high-quality images, but heavy external software dependencies - 2. matplotlib: purely in Python with no external dependencies + + **text**: ASCII art TextDrawing that can be printed in the console. + + **latex**: high-quality images compiled via latex. + + **latex_source**: raw uncompiled latex output. + + **matplotlib**: images with color rendered purely in Python. Args: circuit (QuantumCircuit): the quantum circuit to draw scale (float): scale of image to draw (shrink if < 1) filename (str): file path to save image to style (dict or str): dictionary of style or file name of style file. - This option is only used by the `mpl`, `latex`, and `latex_source` - output types. If a str is passed in that is the path to a json - file which contains that will be open, parsed, and then used just - as the input dict. + This option is only used by the ``mpl`` output type. If a str is + passed in that is the path to a json file which contains that will + be open, parsed, and then used just as the input dict. See: + :ref:`Style Dict Doc ` for more information on the + contents. output (str): Select the output method to use for drawing the circuit. - Valid choices are `text`, `latex`, `latex_source`, `mpl`. By - default the 'text' drawer is used unless a user config file has - an alternative backend set as the default. If the output is passed - in that backend will always be used. + Valid choices are ``text``, ``latex``, ``latex_source``, ``mpl``. + By default the `'text`' drawer is used unless a user config file + has an alternative backend set as the default. If the output kwarg + is set, that backend will always be used over the default in a user + config file. interactive (bool): when set true show the circuit in a new window (for `mpl` this depends on the matplotlib backend being used supporting this). Note when used with either the `text` or the `latex_source` output type this has no effect and will be silently ignored. - line_length (int): Deprecated. See `fold`. + line_length (int): Deprecated, see `fold` which supersedes this option. + Sets the length of the lines generated by `text` output type. + This useful when the drawing does not fit in the console. If None + (default), it will try to guess the console width using + ``shutil.get_terminal_size()``. However, if you're running in + jupyter the default line length is set to 80 characters. If you + don't want pagination at all, set ``line_length=-1``. reverse_bits (bool): When set to True reverse the bit order inside registers for the output visualization. plot_barriers (bool): Enable/disable drawing barriers in the output circuit. Defaults to True. - justify (string): Options are `left`, `right` or `none`, if anything - else is supplied it defaults to left justified. It refers to where - gates should be placed in the output circuit if there is an option. - `none` results in each gate being placed in its own column. Currently - only supported by text drawer. - vertical_compression (string): `high`, `medium` or `low`. It merges the - lines generated by `text` so the drawing will take less vertical room. - Default is `medium`. It is ignored if output is not `text`. - idle_wires (bool): Include idle wires. Default is True. - with_layout (bool): Include layout information, with labels on the physical - layout. + justify (string): Options are ``left``, ``right`` or ``none``, if + anything else is supplied it defaults to left justified. It refers + to where gates should be placed in the output circuit if there is + an option. ``none`` results in each gate being placed in its own + column. + vertical_compression (string): ``high``, ``medium`` or ``low``. It + merges the lines generated by the ``text`` output so the drawing + will take less vertical room. Default is ``medium``. Only used by + the ``text`` output, will be silently ignored otherwise. + idle_wires (bool): Include idle wires (wires with no circuit elements) + in output visualization. Default is True. + with_layout (bool): Include layout information, with labels on the + physical layout. Default is True. fold (int): Sets pagination. It can be disabled using -1. In `text`, sets the length of the lines. This useful when the - drawing does not fit in the console. If None (default), it will try to - guess the console width using `shutil.get_terminal_size()`. However, if - running in jupyter, the default line length is set to 80 characters. - In `mpl` is the amount of operations before folding. Default is 25. + drawing does not fit in the console. If None (default), it will try + to guess the console width using ``shutil.get_terminal_size()``. + However, if running in jupyter, the default line length is set to + 80 characters. In ``mpl`` it is the number of (visual) layers before + folding. Default is 25. ax (matplotlib.axes.Axes): An optional Axes object to be used for the visualization output. If none is specified a new matplotlib Figure will be created and used. Additionally, if specified there will be no returned Figure since it is redundant. This is only used when the ``output`` kwarg is set to use the ``mpl`` backend. It will be silently ignored with all other outputs. + Returns: - PIL.Image: (output `latex`) an in-memory representation of the image - of the circuit diagram. - matplotlib.figure: (output `mpl`) a matplotlib figure object for the - circuit diagram, if the ``ax`` kwarg is not set - String: (output `latex_source`). The LaTeX source code. - TextDrawing: (output `text`). A drawing that can be printed as ascii art + :class:`PIL.Image` or :class:`matplotlib.figure` or :class:`str` or + :class:`TextDrawing`: + + * `PIL.Image` (output='latex') + an in-memory representation of the image of the circuit diagram. + * `matplotlib.figure.Figure` (output='mpl') + a matplotlib figure object for the circuit diagram. + * `str` (output='latex_source') + The LaTeX source code for visualizing the circuit diagram. + * `TextDrawing` (output='text') + A drawing that can be printed as ascii art + Raises: VisualizationError: when an invalid output method is selected - ImportError: when the output methods requieres non-installed libraries. + ImportError: when the output methods requires non-installed libraries. .. _style-dict-doc: + **Style Dict Details** + The style dict kwarg contains numerous options that define the style of the - output circuit visualization. While the style dict is used by the `mpl`, - `latex`, and `latex_source` outputs some options in that are only used - by the `mpl` output. These options are defined below, if it is only used by - the `mpl` output it is marked as such: + output circuit visualization. The style dict is only used by the ``mpl`` + output. The options available in the style dict are defined below: + Args: textcolor (str): The color code to use for text. Defaults to - `'#000000'` (`mpl` only) + `'#000000'` subtextcolor (str): The color code to use for subtext. Defaults to - `'#000000'` (`mpl` only) + `'#000000'` linecolor (str): The color code to use for lines. Defaults to - `'#000000'` (`mpl` only) + `'#000000'` creglinecolor (str): The color code to use for classical register - lines. Defaults to `'#778899'`(`mpl` only) + lines. Defaults to `'#778899'` gatetextcolor (str): The color code to use for gate text. Defaults to - `'#000000'` (`mpl` only) + `'#000000'` gatefacecolor (str): The color code to use for gates. Defaults to - `'#ffffff'` (`mpl` only) + `'#ffffff'` barrierfacecolor (str): The color code to use for barriers. Defaults to - `'#bdbdbd'` (`mpl` only) + `'#bdbdbd'` backgroundcolor (str): The color code to use for the background. - Defaults to `'#ffffff'` (`mpl` only) - fontsize (int): The font size to use for text. Defaults to 13 (`mpl` - only) + Defaults to `'#ffffff'` + fontsize (int): The font size to use for text. Defaults to 13 subfontsize (int): The font size to use for subtext. Defaults to 8 - (`mpl` only) displaytext (dict): A dictionary of the text to use for each element - type in the output visualization. The default values are: - { - 'id': 'id', - 'u0': 'U_0', - 'u1': 'U_1', - 'u2': 'U_2', - 'u3': 'U_3', - 'x': 'X', - 'y': 'Y', - 'z': 'Z', - 'h': 'H', - 's': 'S', - 'sdg': 'S^\\dagger', - 't': 'T', - 'tdg': 'T^\\dagger', - 'rx': 'R_x', - 'ry': 'R_y', - 'rz': 'R_z', - 'reset': '\\left|0\\right\\rangle' - } + type in the output visualization. The default values are:: + + { + 'id': 'id', + 'u0': 'U_0', + 'u1': 'U_1', + 'u2': 'U_2', + 'u3': 'U_3', + 'x': 'X', + 'y': 'Y', + 'z': 'Z', + 'h': 'H', + 's': 'S', + 'sdg': 'S^\\dagger', + 't': 'T', + 'tdg': 'T^\\dagger', + 'rx': 'R_x', + 'ry': 'R_y', + 'rz': 'R_z', + 'reset': '\\left|0\\right\\rangle' + } + You must specify all the necessary values if using this. There is - no provision for passing an incomplete dict in. (`mpl` only) + no provision for passing an incomplete dict in. displaycolor (dict): The color codes to use for each circuit element. - The default values are: - { - 'id': '#F0E442', - 'u0': '#E7AB3B', - 'u1': '#E7AB3B', - 'u2': '#E7AB3B', - 'u3': '#E7AB3B', - 'x': '#58C698', - 'y': '#58C698', - 'z': '#58C698', - 'h': '#70B7EB', - 's': '#E0722D', - 'sdg': '#E0722D', - 't': '#E0722D', - 'tdg': '#E0722D', - 'rx': '#ffffff', - 'ry': '#ffffff', - 'rz': '#ffffff', - 'reset': '#D188B4', - 'target': '#70B7EB', - 'meas': '#D188B4' - } + The default values are:: + + { + 'id': '#F0E442', + 'u0': '#E7AB3B', + 'u1': '#E7AB3B', + 'u2': '#E7AB3B', + 'u3': '#E7AB3B', + 'x': '#58C698', + 'y': '#58C698', + 'z': '#58C698', + 'h': '#70B7EB', + 's': '#E0722D', + 'sdg': '#E0722D', + 't': '#E0722D', + 'tdg': '#E0722D', + 'rx': '#ffffff', + 'ry': '#ffffff', + 'rz': '#ffffff', + 'reset': '#D188B4', + 'target': '#70B7EB', + 'meas': '#D188B4' + } + Also, just like `displaytext` there is no provision for an - incomplete dict passed in. (`mpl` only) + incomplete dict passed in. + latexdrawerstyle (bool): When set to True enable latex mode which will - draw gates like the `latex` output modes. (`mpl` only) - usepiformat (bool): When set to True use radians for output (`mpl` - only) + draw gates like the `latex` output modes. + usepiformat (bool): When set to True use radians for output fold (int): The number of circuit elements to fold the circuit at. - Defaults to 20 (`mpl` only) - cregbundle (bool): If set True bundle classical registers (`mpl` only) - showindex (bool): If set True draw an index. (`mpl` only) - compress (bool): If set True draw a compressed circuit (`mpl` only) + Defaults to 20 + cregbundle (bool): If set True bundle classical registers + showindex (bool): If set True draw an index. + compress (bool): If set True draw a compressed circuit figwidth (int): The maximum width (in inches) for the output figure. - (`mpl` only) - dpi (int): The DPI to use for the output image. Defaults to 150 (`mpl` - only) - margin (list): `mpl` only + dpi (int): The DPI to use for the output image. Defaults to 150 + margin (list): A list of margin values to adjust spacing around output + image. Takes a list of 4 ints: [x left, x right, y bottom, y top]. creglinestyle (str): The style of line to use for classical registers. Choices are `'solid'`, `'doublet'`, or any valid matplotlib - `linestyle` kwarg value. Defaults to `doublet`(`mpl` only) + `linestyle` kwarg value. Defaults to `doublet` """ image = None config = user_config.get_config()