Skip to content

Commit

Permalink
Update docstring for circuit_drawer and QuantumCircuit.draw (Qiskit#3219
Browse files Browse the repository at this point in the history 
)

* 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 <[email protected]>

* Fix lint issues introduced by github web editor

* Add style dict doc to circuit draw() method
  • Loading branch information
@mtreinish
mtreinish authored Oct 12, 2019
1 parent 195f232 commit e5870a4
Show file tree
Hide file tree
Showing 2 changed files with 301 additions and 149 deletions.
200 changes: 160 additions & 40 deletions qiskit/circuit/quantumcircuit.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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 <style-dict-circ-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,
Expand Down
Loading

0 comments on commit e5870a4

Please sign in to comment.