Setup nbsphinx; Document Callbacks; Add RBM Tutorial PDF to docs; sph…

…inx-autobuild livehtml now watches examples and python source folders too
PIQuIL · Jul 12, 2018 · 22d481f · 22d481f
1 parent ee1574b
commit 22d481f
Show file tree

Hide file tree

Showing 14 changed files with 352 additions and 121 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -20,4 +20,4 @@ help:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 livehtml:
-	sphinx-autobuild -b html $(SPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
+	sphinx-autobuild -z ../qucumber -z ../examples -b html $(SPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
diff --git a/docs/QuCumberTutorial.nblink b/docs/QuCumberTutorial.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../examples/QuCumberTutorial.ipynb"
+}
diff --git a/docs/QuCumberTutorialComplex.nblink b/docs/QuCumberTutorialComplex.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../examples/QuCumberTutorialComplex.ipynb"
+}
diff --git a/docs/QuCumberTutorialReal.nblink b/docs/QuCumberTutorialReal.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../examples/QuCumberTutorialReal.ipynb"
+}
diff --git a/docs/_static/RBM_tutorial.pdf b/docs/_static/RBM_tutorial.pdf
diff --git a/docs/callbacks.rst b/docs/callbacks.rst
@@ -0,0 +1,18 @@
+Callbacks
+=========
+
+.. autoclass:: qucumber.callbacks.Callback
+    :members:
+
+.. autoclass:: qucumber.callbacks.LambdaCallback
+
+.. autoclass:: qucumber.callbacks.ModelSaver
+
+.. autoclass:: qucumber.callbacks.Logger
+
+.. autoclass:: qucumber.callbacks.EarlyStopping
+
+.. autoclass:: qucumber.callbacks.VarianceBasedEarlyStopping
+
+.. autoclass:: qucumber.callbacks.MetricEvaluator
+    :members: get_value, __len__
diff --git a/docs/conf.py b/docs/conf.py
@@ -53,7 +53,9 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.linkcode',
     'sphinx.ext.githubpages',
-    'sphinx.ext.napoleon'
+    'sphinx.ext.napoleon',
+    'nbsphinx',
+    'nbsphinx_link'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -115,6 +117,9 @@
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
+
+autodoc_member_order = "bysource"
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'QuCumberdoc'
 
@@ -184,6 +189,8 @@
 imgmath_use_preview = True
 imgmath_latex_preamble = latex_elements['preamble']
 imgmath_image_format = 'svg'
+imgmath_font_size = 14
+imgmath_dvisvgm_args = ['--no-fonts', '-e', '-c', '100']
 
 
 # -- Options for napoleon ----------------------------------------------------

diff --git a/docs/cplx.rst b/docs/cplx.rst
@@ -1,5 +1,5 @@
 Complex Algebra
-======================
+===============
 
 .. automodule:: qucumber.cplx
    :members:
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,8 +1,3 @@
-.. QuCumber documentation master file, created by
-   sphinx-quickstart on Wed Jul  4 16:50:56 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to QuCumber's documentation!
 ====================================
 
@@ -12,7 +7,12 @@ Welcome to QuCumber's documentation!
 
    rbm
    cplx
+   callbacks
+   observables
    theory
+   QuCumberTutorial
+   QuCumberTutorialReal
+   QuCumberTutorialComplex
 
 
 Indices and tables

diff --git a/docs/observables.rst b/docs/observables.rst
@@ -0,0 +1,5 @@
+Observables
+===========
+
+.. automodule:: qucumber.observables
+    :members:
diff --git a/docs/rbm.rst b/docs/rbm.rst
@@ -12,7 +12,6 @@ Real Positive Wavefunction RBM
 .. autoclass:: qucumber.rbm.BinomialRBM
     :members:
 
-
 Complex Wavefunction RBM
 -----------------------------
 .. note:: Currently under development, use at own risk

diff --git a/docs/theory.rst b/docs/theory.rst
@@ -1,26 +1,5 @@
 Theory
 ======================
 
-Here we will explain the theory behind the code.
-
-compute_batch_gradient
-----------------------
-
-- The gradients for the amplitude and the phase are initialized as
-  zero tensors.
-- For each element in the batch the number of non-trivial unitaries is counted
-- If all the unitaries are trivial, the gradient for the amplitude reads:
-
-.. math::
-    \frac{1}{M}\nabla_{\lambda} \log p_{\lambda}(\hat{\bm\sigma})
-
-
-Calculating the gradients
--------------------------
-
-If the number of non-trivial unitaries :math:`N_U>0` is not equal zero we
-construct the following state for all possible :math:`S_j`
-(for simplicity we assume there is only one unitary):
-
-.. math::
-        \ket{\bm{\sigma}} = \ket{\sigma_1^{b=z} \dots S_j^{b=z} \sigma_{j+1}^{b=z}}
+For a basic introduction to Restricted Boltzmann Machines,
+click `here <../_static/RBM_tutorial.pdf>`_
diff --git a/examples/QuCumberTutorial_YourMachine.ipynb b/examples/QuCumberTutorial_YourMachine.ipynb