Merge pull request #14 from MolSSI/bpp_docs

Add lots of documentation

docs/core-interface.md

@@ -0,0 +1,106 @@
+# Core Interface
+
+The core interface of QCManyBody is designed to allow for more flexibility in how the calculations are run.
+The primary responsibilities of the core interface are:
+
+1. Given a molecule and desired levels of MBE, return the fragments and levels that must be computed for each fragment
+2. Given a dictionary of the results of those computations, analyze those results and calculate the desired manybody properties
+
+Note that the user is expected to run the calculations themselves, and the core interface does not provide any tools for
+running the calculations.
+
+
+## Using the core interface
+
+The core interface is accessed through the [`ManyBodyCalculator`][qcmanybody.manybody.ManyBodyCalculator]
+class.
+
+The first step is to create a molecule. This molecule is a QCElemental molecule object, and must contain fragments.
+
+```python
+import qcmanybody as qcmb
+import qcelemental as qcel
+
+# Create a molecule with 3 hydrogen atoms, each as its own fragment
+mol = qcel.models.Molecule(symbols=['h', 'h', 'h'],
+                           geometry=[[0,0,0],[0,0,2],[0,0,4]],
+                           fragments=[[0], [1], [2]])
+```
+
+Next, create a `ManyBodyCalculator` object. This object is constructed using the molecule,
+the desired BSSE correction, levels of MBE, and other options of the MBE.
+
+```python
+mbc = qcmb.ManyBodyCalculator(
+    molecule=mol,
+    bsse_type=['cp'],
+    levels={1: 'mp2/aug-cc-pvtz', 2: 'b3lyp/def2-svp', 3: 'hf/sto-3g'},
+    return_total_data=True,
+    supersystem_ie_only=False
+)
+```
+
+The `levels` option is a dictionary that specifies the n-body level as a key, then an arbitrary
+string as the description of the calculation to be performed at the n-body level. This string is
+termed the 'model chemistry' is completely arbitrary; it only has meaning to the user, and the user is expected to map these strings
+to some meaningful definition of a calculation.
+
+**Note**: The core interface is less flexible than the high-level interface when it comes to the `levels` option.
+    In the core interface, all levels must be accounted for (that is, keys must go from 1 to the maximum
+    nbody you would like to calculate). All levels must be present even if the model chemistry
+    is the same for all levels.
+
+For a complete discussion of the other options available in the `ManyBodyCalculator` object, see the
+[keywords discussion](keywords.md)
+the [`ManyBodyCalculator API documentation`][qcmanybody.manybody.ManyBodyCalculator].
+
+The next step is to obtain the calculations to be run from the `ManyBodyCalculator` object.
+This is done with a python generator function `iterate_molecules` that returns
+a tuple. This tuple contains
+
+1. The string describing the calculation to be run (the model chemistry string, as defined in the `levels` dictionary)
+2. A label for the calculation. This label is opaque to the user but used to identify the calculation when analyzing the results.
+3. A `Molecule` object that contains the cluster of fragments to be computed.
+
+```python
+calculation_results = {}
+for model_chemistry, label, mol_cluster in mbc.iterate_molecules():
+    calculation_results[label] = run_calculation(mol_cluster, model_chemistry)
+```
+
+Note that it is entirely up to the user to run the calculation somehow - this level of interface
+does not provide any tools for running the calculations.
+
+### Results dictionary
+
+The data returned from the calculations is expected to be stored in a nested dictionary.
+The level is the opaque label as given from the `QCManyBodyCalculator`.
+The second level is the name of the property.
+
+```python
+calculation_results = {
+    'label1': {
+        'energy': -1.0,
+        'gradient': [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]],
+    },
+    'label2': {
+        'energy': -2.0,
+        'gradient': [[4.0, 5.0, 6.0], [7.0, 8.0, 9.0]],
+    },
+    'label3': {
+        'energy': -3.0,
+        'gradient': [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0], [7.0, 8.0, 9.0]],
+    },
+}
+```
+
+### Analysis
+
+This result dictionary is all that is needed to perform the final analysis and calculation
+of the MBE properties.
+
+```python
+final_results = mbc.analyze(calculation_results)
+```
+
+For a discussion about what the results contain, see the [results documentation](results.md).

docs/high-level-interface.md

@@ -0,0 +1,3 @@
+# High-Level Interface
+
+

docs/index.md

@@ -1,18 +1,36 @@
-# Welcome to MkDocs
+# QCManyBody Documentation
 
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+QCManyBody is a python package for running quantum chemistry manybody expansions and interaction calculations in a
+package-independent way.
 
-## Commands
+## Installation
 
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
+Currently, the package is only available on [GitHub](https://github.com/MolSSI/QCManyBody). To install directly
+from GitHub, use the following command:
 
-## Table Of Contents
+```bash
+pip install git+https://github.com/MolSSI/QCManyBody.git
+```
 
-1. [Tutorials](tutorials.md)
-2. [How-To Guides](how-to-guides.md)
-3. [Reference](reference.md)
-4. [Explanation](explanation.md)
+## Package Overview
 
+The package has two main interfaces. The high-level interface allows for a comprehensive workflow, where the user
+provides complete information about the calculation, including the full specification (method, basis set, etc.) of the
+manybody calculation. This is designed to work with [QCEngine](https://github.com/MolSSI/QCEngine) or other packages
+that implement the [QCSchema](https://github.com/MolSSI/QCSchema).
+
+For more information, see (High-level interface)(high-level-interface.md).
+
+QCManyBody also has a core low-level interface that allows for more flexibility in how the calculations are run. This
+interface generally takes a molecule and an arbitrary definition of quantum chemistry specifications, and expects
+the user to run them themselves.
+
+For more information, see (Core interface)(core-interface.md).
+
+## Table of Contents
+
+1. [Common Keywords and Options](keywords.md)
+2. [High-level Interface](high-level-interface.md)
+3. [Core Interface](core-interface.md)
+4. [Results](results.md)
+5. [How-To Guides](how-to-guides.md)

docs/keywords.md

@@ -0,0 +1,38 @@
+# Keywords and options
+
+## Required
+
+### Molecule
+
+### bsse_type
+
+### levels and max_nbody
+
+## Keywords and Options
+
+Both the high-level interface and core interface share the same terminology with respect to options
+
+
+### return_total_data
+
+When set to true, the manybody calculation will return the total data (energy/gradient/hessian/property) of the system.
+If not, the return will only contain interaction data.
+
+Note that the calculation of counterpoise corrected total properties implies the calculation of the energies of monomers
+in the monomer basis, hence specifying `return_total_data = True` may carry out more computations than.
+For some properties such as gradients and hessians, `return_total_data = False` is rarely useful.
+
+### supersystem_ie_only
+
+Target the supersystem total/interaction energy (IE) data over the many-body expansion (MBE)
+analysis, thereby omitting intermediate-body calculations. When false, each n-body level
+in the MBE up through `max_nbody` will be computed. When true (only allowed for `max_nbody = nfragments`),
+only compute enough for the overall interaction/total energy: max_nbody-body and 1-body.
+
+When true, properties `INTERACTION {driver} THROUGH {max_nbody}-BODY` will always be available;
+`TOTAL {driver} THROUGH {max_nbody}-BODY` will be available depending on `return_total_data`; and
+`{max_nbody}-BODY CONTRIBUTION TO {driver}` won't be available (except for dimers).
+
+This keyword produces no savings for a two-fragment molecule. But for the interaction energy of a three-fragment molecule, for example, 2-body
+subsystems can be skipped with `supersystem_ie_only=True` Do not use with `vmfc` in `bsse_type`
+as it cannot produce savings.

mkdocs.yml

@@ -1,4 +1,4 @@
-site_name: QCManyBody Docs
+site_name: QCManyBody Documentation
 site_url: https://molssi.github.io/QCManyBody/
 
 repo_name: MolSSI/QCManyBody
@@ -52,10 +52,9 @@ plugins:
         - https://molssi.github.io/QCFractal/objects.inv
 
 nav:
-  - QCManyBody Docs: index.md
-  - tutorials.md
-  - API Documentation: api.md
+  - Home: index.md
+  - high-level-interface.md
+  - core-interface.md
   - How-To Guides: how-to-guides.md
-  - reference.md
-  - explanation.md
+  - API Documentation: api.md
 

pyproject.toml

@@ -30,6 +30,11 @@ tests = [
     "pytest",
     "zstandard",
 ]
+docs = [
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocstrings[python]",
+]
 
 
 [tool.setuptools.package-data]