Clean up the docs (#183)

* Begin clean of docs, setup notebook linking. * Ignore superop autogen * Linked examples notebooks to module page for rb, dfe. * Add tomography notebooks and do_tomography. * Add examples and clean up warnings * Clean up classical logic docs. * Add progress bar to adder, include notebook in docs. * Fix compilation errors and typos. * Clean up doc errors in dfe. * Revert accidental template change. * Cleanup dm docstrings. * Clean up operator_tools docs. * Clean up op_est docs. * Finish resolving build warnings. * Notebook spellcheck and format fix. * Resolve last batch of warnings besides notebook interlinks. * Finish cleaning up and evaluating notebooks. * Fill out examples in quick start, shorten header title for obs_est. * Add do methods to docs. * Move examples to docs. * Move examples to docs and tweak the nb links. * Add a link to the examples folder. * Update example nb test link. * Remove reference to nblink
rigetti · Aug 5, 2019 · 4fd7ad6 · 4fd7ad6
1 parent 612448c
commit 4fd7ad6
Show file tree

Hide file tree

Showing 100 changed files with 10,019 additions and 9,444 deletions.
diff --git a/.gitignore b/.gitignore
@@ -68,6 +68,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/operator_tools/autogen
 
 # PyBuilder
 target/

diff --git a/Link to examples b/Link to examples
@@ -0,0 +1 @@
+/home/kylegulshen/forest-benchmarking/docs/examples
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
@@ -1,5 +1,4 @@
 {% extends "!layout.html" %}
-{% set script_files = script_files + ["_static/mathjax_macros.js"] %}
 {% block extrahead %}
     {{ super() }}
 {% endblock %}
diff --git a/docs/class_logic.rst b/docs/class_logic.rst
@@ -1,4 +1,5 @@
-.. currentmodule:: forest.benchmarking.classical_logic
+.. module:: forest.benchmarking.classical_logic
+
 Classical Logic
 ===============
 
@@ -7,11 +8,10 @@ The code is contained in the module `classical_logic`.
 
 The benchmark is simplistic and not very rigorous as it does not test any specific feature of the hardware. Further the whole circuit is classical in the sense that we start and end in computational basis states and all gates simply perform classical not, controlled not (`CNOT`), or doubly controlled not (`CCNOT` aka a Toffoli gate). Finally, even for the modest task of adding two one bit numbers, the `CZ` gate (our fundamental two qubit gate) count is very high for the circuit. This in turn implies a low probability of the entire circuit working.
 
-Running DFE
------------
 
-.. todo:: Put an overview or mini tutorial here.
+.. toctree::
 
+    examples/ripple_adder_benchmark
 
 Circuit Primitives
 ------------------
@@ -28,7 +28,6 @@ Circuit Primitives
 
 Ripple Carry adder
 ------------------
-.. currentmodule:: forest.benchmarking.direct_fidelity_estimation
 .. autosummary::
     :toctree: autogen
     :template: autosumm.rst

diff --git a/docs/compilation.rst b/docs/compilation.rst
@@ -1,20 +1,15 @@
-.. currentmodule:: forest.benchmarking.compilation
+.. module:: forest.benchmarking.compilation
+
 Basic Compilation
 =================
 
-Rigetti's native compiler ``quilc`` is a highly advanced and world class complier. It
+Rigetti's native compiler ``quilc`` is a highly advanced and world class compiler. It
 has many features to optimize the performance of quantum  algorithms.
 
 In QCVV we need to be certain that the circuit we wish to run is the one that is run. For this
-reason we have built the module ``compilation`` it's functionality is rudimentary but easy to
+reason we have built the module ``compilation``.  Its functionality is rudimentary but easy to
 understand.
 
-Overview of Basic Compile
--------------------------
-
-.. todo:: Put an overview or mini tutorial here.
-
-
 Basic Compile
 -------------
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -46,7 +46,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
-    'sphinx_autodoc_typehints',
+    # 'sphinx_autodoc_typehints',
     'sphinx.ext.doctest',
     'sphinx.ext.todo',
     'sphinx.ext.intersphinx',
@@ -59,7 +59,7 @@
 autosummary_generate = True
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates/']
+templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:

diff --git a/docs/dfe.rst b/docs/dfe.rst
@@ -1,28 +1,30 @@
+.. module:: forest.benchmarking.direct_fidelity_estimation
+
 Direct Fidelity Estimation
 ==========================
 
-Direct fidelity estimation (DFE) uses knowledge about the target state or process to perform a
-target measurements to quickly certify a quantum state or a quantum process at lower cost than full
-tomography.
+Direct fidelity estimation (DFE) uses knowledge about the ideal target state or process to perform
+a tailored set of measurements to quickly certify a quantum state or a quantum process at lower
+cost than full tomography.
 
+.. toctree::
 
-Running DFE
------------
+    examples/direct_fidelity_estimation
 
-.. todo:: Put an overview or mini tutorial here.
+.. autosummary::
+    :toctree: autogen
+    :template: autosumm.rst
 
+    do_dfe
 
 State DFE
 ---------
-.. currentmodule:: forest.benchmarking.direct_fidelity_estimation
 .. autosummary::
     :toctree: autogen
     :template: autosumm.rst
 
     generate_exhaustive_state_dfe_experiment
     generate_monte_carlo_state_dfe_experiment
-    acquire_dfe_data
-    estimate_dfe
 
 
 Process DFE
@@ -33,5 +35,21 @@ Process DFE
 
     generate_exhaustive_process_dfe_experiment
     generate_monte_carlo_process_dfe_experiment
+
+
+Data Acquisition
+----------------
+.. autosummary::
+    :toctree: autogen
+    :template: autosumm.rst
+
     acquire_dfe_data
-    estimate_dfe
+
+
+Analysis
+--------
+.. autosummary::
+    :toctree: autogen
+    :template: autosumm.rst
+
+    estimate_dfe
diff --git a/docs/dist_meas.rst b/docs/dist_meas.rst
@@ -1,4 +1,4 @@
-.. currentmodule:: forest.benchmarking.distance_measures
+.. module:: forest.benchmarking.distance_measures
 
 Distance Measures
 =================
@@ -10,6 +10,9 @@ allows you to explore some quantitative measures of comparing quantum states and
 
 Distance measures between states or processes can be subtle. We recommend thinking about the *operational interpretation* of each measure before using the measure.
 
+.. toctree::
+
+    examples/distance_measures
 
 Distance measures between quantum states
 ----------------------------------------

diff --git a/docs/ent_states.rst b/docs/ent_states.rst
@@ -1,10 +1,13 @@
-.. currentmodule:: forest.benchmarking.entangled_states
+.. module:: forest.benchmarking.entangled_states
 
 Entangled States
 ================
 
 The module ``entangled_states.py`` allows you to simply create graph states GHZ states.
 
+.. toctree::
+
+    examples/entangled_states
 
 .. autosummary::
     :toctree: autogen

diff --git a/examples/direct_fidelity_estimation.ipynb → ...examples/direct_fidelity_estimation.ipynb b/examples/direct_fidelity_estimation.ipynb → ...examples/direct_fidelity_estimation.ipynb
@@ -70,17 +70,17 @@
     "$$F(\\mathcal U,\\mathcal E) = \\frac{ {\\rm Tr} [\\mathcal E \\mathcal U^\\dagger] + d} {d^2+d}$$\n",
     "\n",
     "where the processes are represented by linear superoperators acting on vectorized\n",
-    "density matrices, and d is the dimension of the Hilbert space $\\mathcal H$ that $\\mathcal E$ and $\\mathcal U$ act on. If you are unfamiliar with these terms look at [superoperator tools notebook](superoperator_tools.ipynb) and [superoperator_representations.md](../docs/superoperator_representations.md)\n",
+    "density matrices, and d is the dimension of the Hilbert space $\\mathcal H$ that $\\mathcal E$ and $\\mathcal U$ act on. If you are unfamiliar with these terms look at [superoperator tools notebook](superoperator_tools.ipynb) and [superoperator_representations.md](../superoperator_representations.rst)\n",
     "\n",
-    "Using the $d^2$ dimensional orthonormal Pauli basis $\\{P_k\\}$ for superoperators on $\\mathcal H$--e.g. $\\{I/\\sqrt{2}, X/\\sqrt{2}, Y/\\sqrt{2}, Z/\\sqrt{2} \\}$ for a single qubit--we can expand the trace and insert an identity superoperator between $\\mathcal U$ and $\\mathcal E$; this amounts to re-casting these superoperators in the Pauli-Liouville representation (aka Pauli Transfer Matrix). (again, see [superoperator_representations.md](../docs/superoperator_representations.md) if you are unfamiliar with vec notation $P_k \\iff \\left| P_k \\rangle\\rangle\\langle\\langle P_k\\right|$):\n",
+    "Using the $d^2$ dimensional orthonormal Pauli basis $\\{P_k\\}$ for superoperators on $\\mathcal H$--e.g. $\\{I/\\sqrt{2}, X/\\sqrt{2}, Y/\\sqrt{2}, Z/\\sqrt{2} \\}$ for a single qubit--we can expand the trace and insert an identity superoperator between $\\mathcal U$ and $\\mathcal E$; this amounts to re-casting these superoperators in the Pauli-Liouville representation (aka Pauli Transfer Matrix). (again, see [superoperator_representations.md](../superoperator_representations.rst) if you are unfamiliar with vec notation $P_k \\iff \\left| P_k \\rangle\\rangle\\langle\\langle P_k\\right|$):\n",
     "\n",
     "$${\\rm Tr} [\\mathcal E \\mathcal U^\\dagger] = {\\rm Tr} [\\mathcal E   \\left( \\sum_k \\left| P_k \\rangle\\rangle\\langle\\langle P_k\\right| \\right) \\mathcal U^\\dagger]$$\n",
     "\n",
     "$$= \\sum_k {\\rm Tr} [  \\left( \\langle\\langle P_k | \\mathcal U^\\dagger \\right) \\left(\\mathcal E | P_k \\rangle\\rangle \\right) ]$$\n",
     "\n",
     "$$= \\sum_k {\\rm Tr} [  \\left( \\mathcal U |  P_k \\rangle\\rangle  \\right)^\\dagger \\left(\\mathcal E | P_k \\rangle\\rangle \\right) ]$$\n",
     "\n",
-    "Now we switch representations by unveccing  $|  P_k \\rangle\\rangle$ and representing $ \\mathcal U$ by its unitary action on the matrix $P_k$.\n",
+    "Now we switch representations by unveccing  $|  P_k \\rangle\\rangle$ and representing $\\mathcal U$ by its unitary action on the matrix $P_k$.\n",
     "\n",
     "$$= \\sum_k {\\rm Tr} [  \\left( U P_k U^\\dagger \\right)^\\dagger \\cdot \\mathcal E \\left( P_k \\right) ]$$\n",
     "\n",
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		/home/kylegulshen/forest-benchmarking/docs/examples