Add additional documentation to circuit module (#4118)

* add supp docs to circuit

* reformat headers

* fix exclude

* fix underbar

* lint

docs/_static/custom.css

@@ -23,5 +23,5 @@
 }
 
 .toggle{
-  background: #EBEBEB;
-}
+  background: #FBFBFB;
+}

docs/conf.py

@@ -108,7 +108,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ['_build', '**.ipynb_checkpoints']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'colorful'

qiskit/circuit/__init__.py

@@ -19,8 +19,158 @@
 
 .. currentmodule:: qiskit.circuit
 
+Overview
+========
+
+The fundamental element of quantum computing is the **quantum circuit**.
+A quantum circuit is a computational routine consisting of coherent quantum
+operations on quantum data, such as qubits. It is an ordered sequence of quantum
+gates, measurements and resets, which may be conditioned on real-time classical
+computation. A set of quantum gates is said to be universal if any unitary
+transformation of the quantum data can be efficiently approximated arbitrarily well
+as as sequence of gates in the set. Any quantum program can be represented by a
+sequence of quantum circuits and classical near-time computation.
+
+In Qiskit, this core element is represented by the :class:`QuantumCircuit` class.
+Below is an example of a quantum circuit that makes a three-qubit GHZ state
+defined as:
+
+.. math::
+
+   |\\psi\\rangle = \\left(|000\\rangle+|111\\rangle\\right)/\\sqrt{2}
+
+
+.. jupyter-execute::
+
+   from qiskit import QuantumCircuit
+   # Create a circuit with a register of three qubits
+   circ = QuantumCircuit(3)
+   # H gate on qubit 0, putting this qubit in a superposition of |0> + |1>.
+   circ.h(0)
+   # A CX (CNOT) gate on control qubit 0 and target qubit 1 generating a Bell state.
+   circ.cx(0, 1)
+   # CX (CNOT) gate on control qubit 0 and target qubit 2 resulting in a GHZ state.
+   circ.cx(0, 2)
+   # Draw the circuit
+   circ.draw()
+
+
+Supplementary Information
+=========================
+
+.. container:: toggle
+
+   .. container:: header
+
+      **Quantum Circuit Properties**
+
+   When constructing quantum circuits, there are several properties that help quantify
+   the "size" of the circuits, and their ability to be run on a noisy quantum device.
+   Some of these, like number of qubits, are straightforward to understand, while others
+   like depth and number of tensor components require a bit more explanation.  Here we will
+   explain all of these properties, and, in preparation for understanding how circuits change
+   when run on actual devices, highlight the conditions under which they change.
+
+   Consider the following circuit:
+
+   .. jupyter-execute::
+
+      from qiskit import QuantumCircuit
+      qc = QuantumCircuit(12)
+      for idx in range(5):
+         qc.h(idx)
+         qc.cx(idx, idx+5)
+
+      qc.cx(1, 7)
+      qc.x(8)
+      qc.cx(1, 9)
+      qc.x(7)
+      qc.cx(1, 11)
+      qc.swap(6, 11)
+      qc.swap(6, 9)
+      qc.swap(6, 10)
+      qc.x(6)
+      qc.draw()
+
+   From the plot, it is easy to see that this circuit has 12 qubits, and a collection of
+   Hadamard, CNOT, X, and SWAP gates.  But how to quantify this programmatically? Because we
+   can do single-qubit gates on all the qubits simultaneously, the number of qubits in this
+   circuit is equal to the **width** of the circuit:
+
+   .. jupyter-execute::
+
+      qc.width()
+
+
+   We can also just get the number of qubits directly:
+
+   .. jupyter-execute::
+
+      qc.num_qubits
+
+
+   .. important::
+
+      For a quantum circuit composed from just qubits, the circuit width is equal
+      to the number of qubits. This is the definition used in quantum computing. However,
+      for more complicated circuits with classical registers, and classically controlled gates,
+      this equivalence breaks down. As such, from now on we will not refer to the number of
+      qubits in a quantum circuit as the width.
+
+
+   It is also straightforward to get the number and type of the gates in a circuit using
+   :meth:`QuantumCircuit.count_ops`:
+
+   .. jupyter-execute::
+
+      qc.count_ops()
+
+
+   We can also get just the raw count of operations by computing the circuits
+   :meth:`QuantumCircuit.size`:
+
+   .. jupyter-execute::
+
+      qc.size()
+
+
+   A particularly important circuit property is known as the circuit **depth**.  The depth
+   of a quantum circuit is a measure of how many "layers" of quantum gates, executed in
+   parallel, it takes to complete the computation defined by the circuit.  Because quantum
+   gates take time to implement, the depth of a circuit roughly corresponds to the amount of
+   time it takes the quantum computer to execute the circuit.  Thus, the depth of a circuit
+   is one important quantity used to measure if a quantum circuit can be run on a device.
+
+   The depth of a quantum circuit has a mathematical definition as the longest path in a
+   directed acyclic graph (DAG).  However, such a definition is a bit hard to grasp, even for
+   experts.  Fortunately, the depth of a circuit can be easily understood by anyone familiar
+   with playing `Tetris <https://en.wikipedia.org/wiki/Tetris>`_.  Lets see how to compute this
+   graphically:
+
+   .. image:: /source_images/depth.gif
+
+
+   .. raw:: html
+
+      <br><br>
+
+
+   We can verify our graphical result using :meth:`QuantumCircuit.depth`:
+
+   .. jupyter-execute::
+
+      qc.depth()
+
+
+   .. raw:: html
+
+      <br>
+
+Quantum Circuit API
+===================
+
 Quantum Circuit Construction
-============================
+----------------------------
 
 .. autosummary::
    :toctree: ../stubs/
@@ -32,7 +182,7 @@
    Clbit
 
 Gates and Instructions
-======================
+----------------------
 
 .. autosummary::
    :toctree: ../stubs/
@@ -46,7 +196,7 @@
    EquivalenceLibrary
 
 Parametric Quantum Circuits
-===========================
+---------------------------
 
 .. autosummary::
    :toctree: ../stubs/
@@ -56,7 +206,7 @@
     ParameterExpression
 
 Random Circuits
-===============
+---------------
 
 .. autosummary::
    :toctree: ../stubs/

qiskit/transpiler/__init__.py

@@ -19,8 +19,8 @@
 
 .. currentmodule:: qiskit.transpiler
 
-Pass Managment
-==============
+Pass Management
+===============
 
 .. autosummary::
    :toctree: ../stubs/