visualization documentation edits and examples added (#3308)

qiskit/visualization/circuit_visualization.py

@@ -203,8 +203,8 @@ def circuit_drawer(circuit,
 
             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.
+        displaycolor (dict):
-            The default values are::
+            The color codes to use for each circuit element. The default values are::
 
                 {
                     'id': '#F0E442',
@@ -246,6 +246,18 @@ def circuit_drawer(circuit,
         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`
+
+    Example:
+        .. jupyter-execute::
+
+            from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
+            from qiskit.tools.visualization import circuit_drawer
+            q = QuantumRegister(1)
+            c = ClassicalRegister(1)
+            qc = QuantumCircuit(q, c)
+            qc.h(q)
+            qc.measure(q, c)
+            circuit_drawer(qc)
     """
     image = None
     config = user_config.get_config()

qiskit/visualization/counts_visualization.py

@@ -75,7 +75,8 @@ def plot_histogram(data, figsize=(7, 5), color=None, number_to_keep=None,
             will be no returned Figure since it is redundant.
 
     Returns:
-        matplotlib.Figure: A figure for the rendered histogram, if the ``ax``
+        matplotlib.Figure:
+            A figure for the rendered histogram, if the ``ax``
             kwarg is not set.
 
     Raises:
@@ -97,7 +98,7 @@ def plot_histogram(data, figsize=(7, 5), color=None, number_to_keep=None,
 
            backend = BasicAer.get_backend('qasm_simulator')
            job = execute(qc, backend)
-           plot_histogram(job.result().get_counts())
+           plot_histogram(job.result().get_counts(), color='midnightblue', title="New Histogram")
     """
     if not HAS_MATPLOTLIB:
         raise ImportError('Must have Matplotlib installed.')

qiskit/visualization/dag_visualization.py

@@ -40,12 +40,31 @@ def dag_drawer(dag, scale=0.7, filename=None, style='color'):
                      'color' (default): color input/output/op nodes
 
     Returns:
-        Ipython.display.Image: if in Jupyter notebook and not saving to file,
+            Ipython.display.Image: if in Jupyter notebook and not saving to file,
             otherwise None.
 
     Raises:
         VisualizationError: when style is not recognized.
         ImportError: when nxpd or pydot not installed.
+
+    Example:
+        .. code-block::
+
+            from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
+            from qiskit.dagcircuit import DAGCircuit
+            from qiskit.converters import circuit_to_dag
+            from qiskit.visualization import dag_drawer
+
+            q = QuantumRegister(3, 'q')
+            c = ClassicalRegister(3, 'c')
+            circ = QuantumCircuit(q, c)
+            circ.h(q[0])
+            circ.cx(q[0], q[1])
+            circ.measure(q[0], c[0])
+            circ.rz(0.5, q[1]).c_if(c, 2)
+
+            dag = circuit_to_dag(circ)
+            dag_drawer(dag)
     """
     try:
         import nxpd

qiskit/visualization/gate_map.py

@@ -100,6 +100,18 @@ def plot_gate_map(backend, figsize=None,
     Raises:
         QiskitError: if tried to pass a simulator.
         ImportError: if matplotlib not installed.
+
+    Example:
+        .. code-block::
+
+           from qiskit import QuantumCircuit, BasicAer, execute, IBMQ
+           from qiskit.visualization import plot_gate_map
+           %matplotlib inline
+
+           provider = IBMQ.load_account()
+           accountProvider = IBMQ.get_provider(hub='ibm-q')
+           backend = accountProvider.get_backend('ibmq_vigo')
+           plot_gate_map(backend)
     """
     if not HAS_MATPLOTLIB:
         raise ImportError('Must have Matplotlib installed.')
@@ -269,6 +281,27 @@ def plot_circuit_layout(circuit, backend, view='virtual'):
     Raises:
         QiskitError: Invalid view type given.
         VisualizationError: Circuit has no layout attribute.
+
+    Example:
+        .. code-block::
+
+            import numpy as np
+            from qiskit import *
+            from qiskit.visualization import plot_histogram, plot_gate_map, plot_circuit_layout
+            from qiskit.tools.monitor import job_monitor
+            import matplotlib.pyplot as plt
+            %matplotlib inline
+
+            provider = IBMQ.get_provider(group='open')
+            ghz = QuantumCircuit(5, 5)
+            ghz.h(0)
+            for idx in range(1,5):
+                ghz.cx(0,idx)
+                ghz.barrier(range(5))
+                ghz.measure(range(5), range(5))
+                backend = provider.get_backend('ibmq_16_melbourne')
+                new_circ_lv0 = transpile(ghz, backend=backend, optimization_level=0)
+                plot_circuit_layout(new_circ_lv0, backend)
     """
     if circuit._layout is None:
         raise QiskitError('Circuit has no layout. '
@@ -328,6 +361,17 @@ def plot_error_map(backend, figsize=(12, 9), show_title=True):
 
     Raises:
         VisualizationError: Input is not IBMQ backend.
+
+    Example:
+        .. code-block::
+
+            from qiskit import QuantumCircuit, BasicAer, execute, IBMQ
+            from qiskit.visualization import plot_error_map
+            %matplotlib inline
+            provider = IBMQ.load_account()
+            accountProvider = IBMQ.get_provider(hub='ibm-q')
+            backend = accountProvider.get_backend('ibmq_vigo')
+            plot_error_map(backend)
     """
     color_map = cm.viridis
 

qiskit/visualization/interactive/iplot_blochsphere.py

@@ -38,6 +38,22 @@ def iplot_bloch_multivector(rho, figsize=None):
         Args:
             rho (array): State vector or density matrix
             figsize (tuple): Figure size in pixels.
+
+        Example:
+            .. code-block::
+
+                from qiskit import QuantumCircuit, BasicAer, execute
+                from qiskit.visualization import iplot_bloch_multivector
+                %matplotlib inline
+
+                qc = QuantumCircuit(2, 2)
+                qc.h(0)
+                qc.cx(0, 1)
+                qc.measure([0, 1], [0, 1])
+
+                backend = BasicAer.get_backend('statevector_simulator')
+                job = execute(qc, backend).result()
+                iplot_bloch_multivector(job.get_statevector(qc))
     """
 
     # HTML

qiskit/visualization/interactive/iplot_cities.py

@@ -35,6 +35,22 @@ def iplot_state_city(rho, figsize=None):
         Args:
             rho (array): State vector or density matrix.
             figsize (tuple): The figure size in pixels.
+
+        Example:
+            .. code-block::
+
+                from qiskit import QuantumCircuit, BasicAer, execute
+                from qiskit.visualization import iplot_state_city
+                %matplotlib inline
+
+                qc = QuantumCircuit(2, 2)
+                qc.h(0)
+                qc.cx(0, 1)
+                qc.measure([0, 1], [0, 1])
+
+                backend = BasicAer.get_backend('statevector_simulator')
+                job = execute(qc, backend).result()
+                iplot_state_city(job.get_statevector(qc))
     """
 
     # HTML

qiskit/visualization/interactive/iplot_hinton.py

@@ -36,6 +36,23 @@ def iplot_state_hinton(rho, figsize=None):
         Args:
             rho (array): Density matrix
             figsize (tuple): Figure size in pixels.
+
+        Example:
+            .. code-block::
+
+                from qiskit import QuantumCircuit, BasicAer, execute
+                from qiskit.visualization import iplot_state_hinton
+                %matplotlib inline
+
+                qc = QuantumCircuit(2, 2)
+                qc.h(0)
+                qc.cx(0, 1)
+                qc.measure([0, 1], [0, 1])
+
+                backend = BasicAer.get_backend('statevector_simulator')
+                job = execute(qc, backend).result()
+                iplot_state_hinton(job.get_statevector(qc))
+
     """
 
     # HTML

qiskit/visualization/interactive/iplot_histogram.py

@@ -73,9 +73,26 @@ def iplot_histogram(data, figsize=None, number_to_keep=None,
             sort (string): Could be 'asc' or 'desc'
             legend (list): A list of strings to use for labels of the data.
                 The number of entries must match the length of data.
+
         Raises:
             VisualizationError: When legend is provided and the length doesn't
                 match the input data.
+
+        Example:
+            .. code-block::
+
+                from qiskit import QuantumCircuit, BasicAer, execute
+                from qiskit.visualization import iplot_histogram
+                %matplotlib inline
+
+                qc = QuantumCircuit(2, 2)
+                qc.h(0)
+                qc.cx(0, 1)
+                qc.measure([0, 1], [0, 1])
+
+                backend = BasicAer.get_backend('qasm_simulator')
+                job = execute(qc, backend)
+                iplot_histogram(job.result().get_counts())
     """
 
     # HTML

qiskit/visualization/interactive/iplot_paulivec.py

@@ -53,6 +53,22 @@ def iplot_state_paulivec(rho, figsize=None, slider=False, show_legend=False):
             figsize (tuple): Figure size in pixels.
             slider (bool): activate slider
             show_legend (bool): show legend of graph content
+
+        Example:
+            .. code-block::
+
+                from qiskit import QuantumCircuit, BasicAer, execute
+                from qiskit.visualization import iplot_state_paulivec
+                %matplotlib inline
+
+                qc = QuantumCircuit(2, 2)
+                qc.h(0)
+                qc.cx(0, 1)
+                qc.measure([0, 1], [0, 1])
+
+                backend = BasicAer.get_backend('statevector_simulator')
+                job = execute(qc, backend).result()
+                iplot_state_paulivec(job.get_statevector(qc))
     """
 
     # HTML

qiskit/visualization/interactive/iplot_qsphere.py

@@ -44,6 +44,22 @@ def iplot_state_qsphere(rho, figsize=None):
         Args:
             rho (array): State vector or density matrix.
             figsize (tuple): Figure size in pixels.
+
+        Example:
+            .. code-block::
+
+                from qiskit import QuantumCircuit, BasicAer, execute
+                from qiskit.visualization import iplot_state_qsphere
+                %matplotlib inline
+
+                qc = QuantumCircuit(2, 2)
+                qc.h(0)
+                qc.cx(0, 1)
+                qc.measure([0, 1], [0, 1])
+
+                backend = BasicAer.get_backend('statevector_simulator')
+                job = execute(qc, backend).result()
+                iplot_state_qsphere(job.get_statevector(qc))
     """
 
     # HTML

qiskit/visualization/pass_manager_visualization.py

@@ -58,6 +58,26 @@ def pass_manager_drawer(pass_manager, filename, style=None, raw=False):
     Raises:
         ImportError: when nxpd or pydot not installed.
         VisualizationError: If raw=True and filename=None.
+
+    Example:
+        .. code-block::
+
+            from qiskit import QuantumCircuit
+            from qiskit.compiler import transpile
+            from qiskit.transpiler import PassManager
+            from qiskit.visualization import pass_manager_drawer
+            from qiskit.transpiler.passes import Unroller
+
+            circ = QuantumCircuit(3)
+            circ.ccx(0, 1, 2)
+            circ.draw()
+
+            pass_ = Unroller(['u1', 'u2', 'u3', 'cx'])
+            pm = PassManager(pass_)
+            new_circ = pm.run(circ)
+            new_circ.draw(output='mpl')
+
+            pass_manager_drawer(pm, "passmanager.jpg")
     """
 
     try:

qiskit/visualization/state_visualization.py

@@ -59,7 +59,7 @@ if HAS_MATPLOTLIB:
 
 
 def plot_state_hinton(rho, title='', figsize=None, ax_real=None, ax_imag=None):
-    """Plot a hinton diagram for the quanum state.
+    """Plot a hinton diagram for the quantum state.
 
     Args:
         rho (ndarray): Numpy array for state vector or density matrix.
@@ -79,11 +79,28 @@ def plot_state_hinton(rho, title='', figsize=None, ax_real=None, ax_imag=None):
             it is redundant.
 
     Returns:
-         matplotlib.Figure: The matplotlib.Figure of the visualization if
+         matplotlib.Figure:
+            The matplotlib.Figure of the visualization if
             neither ax_real or ax_imag is set.
 
     Raises:
         ImportError: Requires matplotlib.
+
+    Example:
+        .. jupyter-execute::
+
+            from qiskit import QuantumCircuit, BasicAer, execute
+            from qiskit.visualization import plot_state_hinton
+            %matplotlib inline
+
+            qc = QuantumCircuit(2, 2)
+            qc.h(0)
+            qc.cx(0, 1)
+            qc.measure([0, 1], [0, 1])
+
+            backend = BasicAer.get_backend('statevector_simulator')
+            job = execute(qc, backend).result()
+            plot_state_hinton(job.get_statevector(qc), title="New Hinton Plot")
     """
     if not HAS_MATPLOTLIB:
         raise ImportError('Must have Matplotlib installed.')
@@ -169,13 +186,21 @@ def plot_bloch_vector(bloch, title="", ax=None, figsize=None):
         title (str): a string that represents the plot title
         ax (matplotlib.axes.Axes): An Axes to use for rendering the bloch
             sphere
-        figsize (tuple): Figure size in inches. Has no effect is passing `ax`.
+        figsize (tuple): Figure size in inches. Has no effect is passing ``ax``.
 
     Returns:
-        Figure: A matplotlib figure instance if `ax = None`.
+        Figure: A matplotlib figure instance if ``ax = None``.
 
     Raises:
         ImportError: Requires matplotlib.
+
+    Example:
+        .. jupyter-execute::
+
+           from qiskit.visualization import plot_bloch_vector
+           %matplotlib inline
+
+           plot_bloch_vector([0,1,0], title="New Bloch Sphere")
     """
     if not HAS_MATPLOTLIB:
         raise ImportError('Must have Matplotlib installed.')
@@ -205,10 +230,27 @@ def plot_bloch_multivector(rho, title='', figsize=None):
         figsize (tuple): Has no effect, here for compatibility only.
 
     Returns:
-        Figure: A matplotlib figure instance.
+        matplotlib.Figure:
+            A matplotlib figure instance.
 
     Raises:
         ImportError: Requires matplotlib.
+
+    Example:
+        .. jupyter-execute::
+
+            from qiskit import QuantumCircuit, BasicAer, execute
+            from qiskit.visualization import plot_bloch_multivector
+            %matplotlib inline
+
+            qc = QuantumCircuit(2, 2)
+            qc.h(0)
+            qc.cx(0, 1)
+            qc.measure([0, 1], [0, 1])
+
+            backend = BasicAer.get_backend('statevector_simulator')
+            job = execute(qc, backend).result()
+            plot_bloch_multivector(job.get_statevector(qc), title="New Bloch Multivector")
     """
     if not HAS_MATPLOTLIB:
         raise ImportError('Must have Matplotlib installed.')
@@ -247,7 +289,7 @@ def plot_state_city(rho, title="", figsize=None, color=None,
         title (str): a string that represents the plot title
         figsize (tuple): Figure size in inches.
         color (list): A list of len=2 giving colors for real and
-        imaginary components of matrix elements.
+            imaginary components of matrix elements.
         alpha (float): Transparency value for bars
         ax_real (matplotlib.axes.Axes): An optional Axes object to be used for
             the visualization output. If none is specified a new matplotlib
@@ -263,12 +305,30 @@ def plot_state_city(rho, title="", figsize=None, color=None,
             it is redundant.
 
     Returns:
-         matplotlib.Figure: The matplotlib.Figure of the visualization if the
+         matplotlib.Figure:
-             ``ax_real`` and ``ax_imag`` kwargs are not set
+            The matplotlib.Figure of the visualization if the
+            ``ax_real`` and ``ax_imag`` kwargs are not set
 
     Raises:
         ImportError: Requires matplotlib.
         ValueError: When 'color' is not a list of len=2.
+
+    Example:
+        .. jupyter-execute::
+
+           from qiskit import QuantumCircuit, BasicAer, execute
+           from qiskit.visualization import plot_state_city
+           %matplotlib inline
+
+           qc = QuantumCircuit(2, 2)
+           qc.h(0)
+           qc.cx(0, 1)
+           qc.measure([0, 1], [0, 1])
+
+           backend = BasicAer.get_backend('statevector_simulator')
+           job = execute(qc, backend).result()
+           plot_state_city(job.get_statevector(qc), color=['midnightblue', 'midnightblue'],
+                title="New State City")
     """
     if not HAS_MATPLOTLIB:
         raise ImportError('Must have Matplotlib installed.')
@@ -428,10 +488,29 @@ def plot_state_paulivec(rho, title="", figsize=None, color=None, ax=None):
             will be no returned Figure since it is redundant.
 
     Returns:
-         matplotlib.Figure: The matplotlib.Figure of the visualization if the
+         matplotlib.Figure:
-         ``ax`` kwarg is not set
+            The matplotlib.Figure of the visualization if the
+            ``ax`` kwarg is not set
+
     Raises:
         ImportError: Requires matplotlib.
+
+    Example:
+        .. jupyter-execute::
+
+           from qiskit import QuantumCircuit, BasicAer, execute
+           from qiskit.visualization import plot_state_paulivec
+           %matplotlib inline
+
+           qc = QuantumCircuit(2, 2)
+           qc.h(0)
+           qc.cx(0, 1)
+           qc.measure([0, 1], [0, 1])
+
+           backend = BasicAer.get_backend('statevector_simulator')
+           job = execute(qc, backend).result()
+           plot_state_paulivec(job.get_statevector(qc), color='midnightblue',
+                title="New PauliVec plot")
     """
     if not HAS_MATPLOTLIB:
         raise ImportError('Must have Matplotlib installed.')
@@ -542,7 +621,7 @@ def plot_state_qsphere(rho, figsize=None, ax=None):
 
     Args:
         rho (ndarray): State vector or density matrix representation.
-        of quantum state.
+            of quantum state.
         figsize (tuple): Figure size in inches.
         ax (matplotlib.axes.Axes): An optional Axes object to be used for
             the visualization output. If none is specified a new matplotlib
@@ -554,6 +633,22 @@ def plot_state_qsphere(rho, figsize=None, ax=None):
 
     Raises:
         ImportError: Requires matplotlib.
+
+    Example:
+        .. jupyter-execute::
+
+           from qiskit import QuantumCircuit, BasicAer, execute
+           from qiskit.visualization import plot_state_qsphere
+           %matplotlib inline
+
+           qc = QuantumCircuit(2, 2)
+           qc.h(0)
+           qc.cx(0, 1)
+           qc.measure([0, 1], [0, 1])
+
+           backend = BasicAer.get_backend('statevector_simulator')
+           job = execute(qc, backend).result()
+           plot_state_qsphere(job.get_statevector(qc))
     """
     if not HAS_MATPLOTLIB:
         raise ImportError('Must have Matplotlib installed.')