[WIP] Better docs!

.github/workflows/python-package-conda.yml

@@ -28,7 +28,12 @@ jobs:
           flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
           # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
           flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-      - name: Test with pytest
+      - name: Test with pytest and get coverage
         run: |
           conda install pytest
-          pytest
+          pip install pytest-cov
+          pytest --cov=unlockgnn
+      - name: Coveralls
+        uses: coverallsapp/github-action@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}

.readthedocs.yml

@@ -13,4 +13,4 @@ python:
       path: .
 
 sphinx:
-  configuration: docs/source/conf.py
+  configuration: docs/conf.py

dev_environment.yml

@@ -13,14 +13,14 @@ dependencies:
   - pytest
   - pytest-cov
   - python=3.8
-  - sphinx
-  - sphinx_rtd_theme
   - virtualenv
   - pip:
       - bumpversion
       - coveralls
+      - insegel
       - pymatgen==2021.2.8
       - megnet
+      - sphinx
       - tensorflow
       - tensorflow-probability
       - tox

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/conf.py → docs/conf.py

@@ -19,9 +19,12 @@
 # -- Project information -----------------------------------------------------
 
 project = "unlockGNN"
-copyright = "2020, Alexander Moriarty"
+copyright = "2021, Alexander Moriarty"
 author = "Alexander Moriarty"
 
+# The full version, including alpha/beta/rc tags
+release = "2.0.0"
+
 
 # -- General configuration ---------------------------------------------------
 
@@ -31,9 +34,13 @@
 extensions = [
     "sphinx.ext.napoleon",
     "sphinx.ext.doctest",
-    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
 ]
 
+# master_doc = "index"
+
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -48,9 +55,9 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "insegel"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ["_static"]
+html_static_path = ["_static"]

docs/index.rst

@@ -0,0 +1,48 @@
+.. unlockGNN documentation master file, created by
+   sphinx-quickstart on Wed Aug 18 15:33:30 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+.. module:: unlockgnn
+
+What is unlockGNN?
+==================
+
+UnlockGNN is a Python package for adding uncertainty quantification to
+Keras models for materials property prediction.
+
+This documentation was built on |today|.
+
+Installation
+------------
+
+Using ``pip``::
+
+   $ pip install unlockGNN
+
+From source
+^^^^^^^^^^^
+
+First, clone the repository::
+
+   $ git clone https://github.com/a-ws-m/unlockGNN.git
+   $ cd unlockGNN
+
+Then, either install dependencies using ``conda``::
+
+   $ conda env create -f environment.yml
+   $ pip install .
+
+Or simply install using ``pip`` exclusively::
+
+   $ pip install .
+
+
+.. toctree::
+   :hidden:
+   :caption: Modules
+
+   modules/unlockgnn.model
+   modules/unlockgnn.kernel_layers
+   modules/unlockgnn.megnet_utils
+   modules/unlockgnn.metrics
+   modules/unlockgnn.initializers

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/modules/unlockgnn.initializers.rst

@@ -0,0 +1,15 @@
+.. currentmodule:: unlockgnn.initializers
+
+Inducing index points initializers
+==================================
+
+This experimental module contains work-in-progress algorithms for more intelligently
+initializing the locations of inducing index points
+for the variational Gaussian process (VGP).
+As per the `TensorFlow documentation <https://www.tensorflow.org/probability/api_docs/python/tfp/layers/VariationalGaussianProcess#args>`_,
+VGPs are highly sensitive to the location of these points, so improving the initializer could substantially increase performance.
+
+So far, only one custom initializer has been implemented and it does not seem to offer any performance improvement
+over the default initializer:
+
+.. autoclass:: SampleInitializer

docs/modules/unlockgnn.kernel_layers.rst

@@ -0,0 +1,38 @@
+.. currentmodule:: unlockgnn.kernel_layers
+
+Kernel layers
+=============
+
+UnlockGNN provides Keras-compatible implementations of a few kernel
+functions for use with the Gaussian process, as well as an extensible
+API for implementing your own kernels.
+
+Built-in kernels
+----------------
+
+.. autosummary::
+
+   RBFKernelFn
+   MaternOneHalfFn
+
+Each of these kernels can be saved using their :meth:`KernelLayer.save` method and then
+loaded using :func:`load_kernel`:
+
+.. autofunction:: load_kernel
+
+Extending the kernels API
+-------------------------
+
+All kernels must inherit from the :class:`KernelLayer` abstract base class:
+
+.. autoclass:: KernelLayer
+   :members:
+   :special-members: __init__
+
+Both of the current built-in kernels are parameterized by an amplitude and
+a length scale. The :class:`AmpAndLengthScaleFn` abstract base class initializes
+these weights during instantiation and other kernels that are parameterized as
+such may inherit from this class also:
+
+.. autoclass:: AmpAndLengthScaleFn
+   :special-members: __init__

docs/modules/unlockgnn.megnet_utils.rst

@@ -0,0 +1,6 @@
+MEGNet utilities
+================
+
+
+
+

docs/modules/unlockgnn.metrics.rst

@@ -0,0 +1,3 @@
+Uncertainty quantification metrics
+==================================
+

docs/modules/unlockgnn.model.rst

@@ -0,0 +1,36 @@
+.. currentmodule:: unlockgnn.model
+
+Probabilistic models
+====================
+
+UnlockGNN includes an extensible interface for adding uncertainty quantification
+to any trained keras model using a
+`variational Gaussian process <https://www.tensorflow.org/probability/api_docs/python/tfp/distributions/VariationalGaussianProcess>`_
+(VGP). A VGP is a modification of a `Gaussian process <https://distill.pub/2019/visual-exploration-gaussian-processes>`_
+that vastly improves model scalability; instead of using the entire training dataset
+as index points, a VGP uses variational inference to compute a smaller set of *inducing* index
+points that lead to a good approximation of the "full" Gaussian process.
+
+By supplanting the last layer(s) of a keras model with a VGP, the model's
+predictions become Gaussian distributions, rather than tensors. The mean of
+this distribution is the *de facto* "prediction" and the standard
+deviation indicates uncertainty. For example, two standard deviations
+gives the 95% confidence interval.
+
+.. note::
+    The caveat of using a VGP is that the probabilistic model must undergo
+    further training to determine the inducing index point
+    locations and the kernel parameters, which can be expensive!
+
+The module also contains a specific implementation for use with
+`MEGNet <https://github.com/materialsvirtuallab/megnet>`_, a highly performant
+graph neural network model for materials property prediction.
+
+MEGNet probabilistic model
+--------------------------
+
+The bread and butter of unlockGNN, use :class:`MEGNetProbModel` to add uncertainty quantification
+to a :class:`MEGNetModel`:
+
+.. autoclass:: MEGNetProbModel
+    :members: train, predict, evaluate, save, load, set_frozen, gnn_frozen, norm_frozen, vgp_frozen