Initial draft of documentation (#39)

* Install examol before building

* Initial API docs

* Document storage formats

* Start in on documentation about simulation

* Include TF and sklearn in environment

* Make sure NFP gets installed

* Flesh out documentation on Simualte

* Start on the ML docs

* Add documentation for scorers

* Add missing files

* Handle imports from tf, nfp, scikit-learn

* Add documentation on selectors

* Documentation for steering

* Document how to run ExaMol

* Add installation docs

* Document the utils module

* Add docs to the README

* Add source code to docs

* Links to source code

.github/workflows/gh-pages.yml

@@ -14,6 +14,7 @@ jobs:
       - uses: actions/setup-python@v3
       - name: Install dependencies
         run: |
+          pip install -e .
           pip install -r docs/requirements.txt
       - name: Sphinx build
         run: |

README.md

@@ -1,8 +1,12 @@
 # ExaMol
 [![CI](https://github.com/exalearn/ExaMol/actions/workflows/python-app.yml/badge.svg)](https://github.com/exalearn/ExaMol/actions/workflows/python-app.yml)
+[![Deploy Docs](https://github.com/exalearn/ExaMol/actions/workflows/gh-pages.yml/badge.svg)](https://exalearn.github.io/ExaMol/)
 [![Coverage Status](https://coveralls.io/repos/github/exalearn/ExaMol/badge.svg?branch=main)](https://coveralls.io/github/exalearn/ExaMol?branch=main)
 
-Designing new molecules as fast as possible with AI and simulation
+Designing new molecules as fast as possible with AI and simulation.
+
+- Documentation: [exalearn.github.io/ExaMol/](https://exalearn.github.io/ExaMol/)
+- Source Code: [github.com/exalearn/ExaMol](https://github.com/exalearn/ExaMol)
 
 ## Installation
 

docs/api/examol.rst

@@ -0,0 +1,13 @@
+API Documentation
+=================
+
+.. toctree::
+    :maxdepth: 2
+
+    examol.score
+    examol.select
+    examol.simulate
+    examol.specify
+    examol.steer
+    examol.store
+    examol.utils

docs/api/examol.score.rst

@@ -0,0 +1,30 @@
+examol.score
+============
+
+.. automodule:: examol.score
+   :members:
+   :show-inheritance:
+
+examol.score.base
+-----------------
+
+.. automodule:: examol.score.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+examol.score.nfp
+----------------
+
+.. automodule:: examol.score.nfp
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+examol.score.rdkit
+------------------
+
+.. automodule:: examol.score.rdkit
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/examol.select.rst

@@ -0,0 +1,22 @@
+examol.select
+=============
+
+.. automodule:: examol.select
+   :members:
+   :show-inheritance:
+
+examol.select.base
+------------------
+
+.. automodule:: examol.select.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+examol.select.baseline
+----------------------
+
+.. automodule:: examol.select.baseline
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/examol.simulate.rst

@@ -0,0 +1,42 @@
+examol.simulate
+===============
+
+.. automodule:: examol.simulate
+   :members:
+   :show-inheritance:
+
+examol.simulate.base
+--------------------
+
+.. automodule:: examol.simulate.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+examol.simulate.initialize
+--------------------------
+
+.. automodule:: examol.simulate.initialize
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+examol.simulate.ase
+-------------------
+
+.. automodule:: examol.simulate.ase
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+examol.simulate.ase.utils
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: examol.simulate.ase.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+

docs/api/examol.specify.rst

@@ -0,0 +1,7 @@
+examol.specify
+==============
+
+.. automodule:: examol.specify
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/examol.steer.rst

@@ -0,0 +1,22 @@
+examol.steer
+============
+
+.. automodule:: examol.steer
+   :members:
+   :show-inheritance:
+
+examol.steer.base
+-----------------
+
+.. automodule:: examol.steer.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+examol.steer.single
+-------------------
+
+.. automodule:: examol.steer.single
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/examol.store.rst

@@ -0,0 +1,21 @@
+examol.store
+============
+
+.. automodule:: examol.store
+   :members:
+   :show-inheritance:
+
+examol.store.models
+-------------------
+
+.. automodule:: examol.store.models
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+examol.store.recipes
+--------------------
+
+.. automodule:: examol.store.recipes
+   :members:
+   :show-inheritance:

docs/api/examol.utils.rst

@@ -0,0 +1,22 @@
+examol.utils
+============
+
+.. automodule:: examol.utils
+   :members:
+   :show-inheritance:
+
+examol.utils.chemistry
+----------------------
+
+.. automodule:: examol.utils.chemistry
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+examol.utils.conversions
+------------------------
+
+.. automodule:: examol.utils.conversions
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/components/index.rst

@@ -0,0 +1,13 @@
+Components
+==========
+
+The ExaMol library is built around components each dedicated to different aspects of a design application.
+
+.. toctree::
+    :maxdepth: 1
+
+    score
+    select
+    simulate
+    steer
+    store

docs/components/score.rst

@@ -0,0 +1,65 @@
+Score
+=====
+
+The Score module defines interfaces for running machine learning (ML) tasks on distributed systems.
+Each implementation of :class:`~examol.score.base.Scorer` provides tools for sending models to
+remote compute nodes,
+preparing molecular data for training or inference,
+and functions for executing training and inference on remote nodes.
+
+Available Interfaces
+--------------------
+
+ExaMol provides interfaces to several libraries which support ML on molecular property data.
+
+.. list-table::
+    :header-rows: 1
+
+    * - Interface
+      - Model Types
+      - Description
+    * - :class:`~examol.score.rdkit.RDKitScorer`
+      - Conventional ML
+      - Models which use fingerprints computed from RDKit as inputs to scikit-learn Pipelines.
+    * - :class:`~examol.score.nfp.NFPScorer`
+      - MPNNs
+      - Neural networks based on the `Neural Fingerprints (nfp) library <https://github.com/NREL/nfp>`_,
+        which is backed by Tensorflow
+
+Using Scorers
+-------------
+
+Scorers separate pre-processing data, transmitting models, and running ML tasks into separate steps
+so that they can be distributed across supercomputing resources.
+
+Consider model training as an example.
+Start by creating a scorer, a model it will train, and the recipe describing the computations to be learned.
+
+.. code-block:: python
+
+    scorer = RDKitScorer()
+    recipe = RedoxEnergy(charge=1, config_name='xtb')
+    model = make_knn_model()
+
+Training the model requires first transforming the available molecule data
+(as `molecule data records <store.html#data-models>`_)
+into inputs and outputs compatible with the scorer.
+
+.. code-block:: python
+
+    outputs = model.transform_outputs(records, recipe)  # Outputs are specific to a recipe
+    inputs = model.transform_inputs(records)  # Inputs are not
+
+Then, convert the model into a form that can be transmitted across nodes
+
+.. code-block:: python
+
+    model_msg = model.prepare_message(model, training=True)
+
+ExaMol is now ready to run training on a remote node, and will use the output of training to update the local
+copy of the model:
+
+.. code-block:: python
+
+    update_msg = scorer.retrain(model_msg, inputs, outputs)  # Can be run remotely
+    model = scorer.update(model, update_msg)

docs/components/select.rst

@@ -0,0 +1,55 @@
+Select
+======
+
+The Select model define adaptive experimental design algorithms
+that select the next computations based on predictions from the
+`machine learning models <score.html>`_.
+
+Available Selectors
+-------------------
+
+ExaMol includes selectors that have a variety of characteristics
+
+.. list-table::
+   :header-rows: 1
+
+   * - Selector
+     - Category
+     - Batch Aware
+     - Multi-Fidelity
+   * - :class:`~examol.select.baseline.RandomSelector`
+     - Baseline
+     - ✘
+     - ✘
+   * - :class:`~examol.select.baseline.GreedySelector`
+     - Baseline
+     - ✘
+     - ✘
+
+Using a Selector
+----------------
+
+Selectors employ a batching strategy to work with very large search spaces.
+
+Start the selection process by creating the Selector then signaling that it should prepare to receive batches.
+
+.. code-block:: python
+
+    selector = GreedySelector(to_select=2, maximize=True)
+    selector.start_gathering()
+
+The Selector can then receive new predictions as a list of "keys" that define which computation
+associated with a list of of predictions from a machine learning model.
+
+
+.. code-block:: python
+
+    selector.add_possibilities(keys=[1, 2, 3], samples=np.array([[1, 2, 3]]).T)
+
+Retrieve the list of selected computations by stopping the gathering mode then generating them
+from the "dispense" function.
+
+.. code-block:: python
+
+    selector.start_dispensing()
+    print(list(selector.dispense())) # [(3, 3.), (2, 2.)]