[WIP] Installation Guide Update (#175)

* start of installation guide

* update installer docs

* set max dgl version

* update for espaloma 0.3.1

* final pass on install docs

README.md

@@ -19,29 +19,14 @@ Here, we propose an alternative approach that uses _graph neural networks_ to pe
 Since all stages are built from smooth neural functions, the entire process---spanning chemical perception to parameter assignment---is modular and end-to-end differentiable with respect to model parameters, allowing new force fields to be easily constructed, extended, and applied to arbitrary molecules.
 We show that this approach is not only sufficiently expressive to reproduce legacy atom types, but that it can learn and extend existing molecular mechanics force fields, construct entirely new force fields applicable to both biopolymers and small molecules from quantum chemical calculations, and even learn to accurately predict free energies from experimental observables.
 
-# Manifest
 
-* `espaloma/` core code for graph-parametrized potential energy functions.
-    * `graphs/` data objects that contain various level of information we need.
-        * `graph.py` base modules for graphs.
-        * `molecule_graph.py` provide APIs to various molecular modelling toolkits.
-        * `homogeneous_graph.py` simplest graph representation of a molecule.
-        * `heterogeneous_graph.py` graph representation of a molecule that contains information regarding membership of lower-level nodes to higher-level nodes.
-        * `parametrized_graph.py` graph representation of a molecule with all parameters needed for energy evaluation.
-    * `nn/` neural network models that facilitates translation between graphs.
-        * `dgl_legacy.py` API to dgl models for atom-level message passing.
-    * `mm/` molecular mechanics functionalities for energy evaluation.
-        * `i/` energy terms used in Class-I force field.
-            * `bond.py` bond energy
-            * `angle.py` angle energy
-            * `torsion.py` torsion energy
-            * `nonbonded.py` nonbonded energy
-        * `ii/` energy terms used in Class-II force field.
-            * `coupling.py` coupling terms
-            * `polynomial.py` higher order polynomials.
+# Installation
 
+```bash
+$ conda install -c conda-forge -c dglteam "espaloma=0.3.1" "dgl<1"
+```
 
-# Example: Deploy espaloma 0.2.0 pretrained force field to arbitrary MM system
+# Example: Deploy espaloma 0.3.1 pretrained force field to arbitrary MM system
 
 ```python  
 # imports
@@ -70,6 +55,27 @@ openmm_system = esp.graphs.deploy.openmm_system_from_graph(molecule_graph)
 
 An example of using espaloma to parameterize small molecules in relative alchemical free energy calculations is provided in the `scripts/perses-benchmark/` directory.
 
+# Manifest
+
+* `espaloma/` core code for graph-parametrized potential energy functions.
+    * `graphs/` data objects that contain various level of information we need.
+        * `graph.py` base modules for graphs.
+        * `molecule_graph.py` provide APIs to various molecular modelling toolkits.
+        * `homogeneous_graph.py` simplest graph representation of a molecule.
+        * `heterogeneous_graph.py` graph representation of a molecule that contains information regarding membership of lower-level nodes to higher-level nodes.
+        * `parametrized_graph.py` graph representation of a molecule with all parameters needed for energy evaluation.
+    * `nn/` neural network models that facilitates translation between graphs.
+        * `dgl_legacy.py` API to dgl models for atom-level message passing.
+    * `mm/` molecular mechanics functionalities for energy evaluation.
+        * `i/` energy terms used in Class-I force field.
+            * `bond.py` bond energy
+            * `angle.py` angle energy
+            * `torsion.py` torsion energy
+            * `nonbonded.py` nonbonded energy
+        * `ii/` energy terms used in Class-II force field.
+            * `coupling.py` coupling terms
+            * `polynomial.py` higher order polynomials.
+
 # License
 
 This software is licensed under [MIT license](https://opensource.org/licenses/MIT).

devtools/conda-envs/espaloma.yaml

@@ -22,7 +22,7 @@ dependencies:
   - pydantic <2  # We need our deps to fix this
   # Pytorch
   - pytorch>=1.8.0
-  - dgl =0.9.0
+  - dgl <1
   # Testing
   - pytest
   - pytest-cov

docs/deploy.rst

@@ -1,4 +1,4 @@
-Deploy espaloma 0.2.0 force field to parametrize your MM system
+Deploy espaloma 0.3.1 force field to parametrize your MM system
 ===============================================================
 Pretrained espaloma force field could be deployed on arbitrary small molecule
 systems in a few lines::
@@ -7,21 +7,20 @@ systems in a few lines::
     import os
     import torch
     import espaloma as esp
-
-    # grab pretrained model
-    if not os.path.exists("espaloma_model.pt"):
-        os.system("wget http://data.wangyq.net/espaloma_model.pt")
-
+    
     # define or load a molecule of interest via the Open Force Field toolkit
     from openff.toolkit.topology import Molecule
     molecule = Molecule.from_smiles("CN1C=NC2=C1C(=O)N(C(=O)N2C)C")
-
+    
     # create an Espaloma Graph object to represent the molecule of interest
     molecule_graph = esp.Graph(molecule)
-
+    
+    # load pretrained model
+    espaloma_model = esp.get_model("latest")
+    
     # apply a trained espaloma model to assign parameters
-    espaloma_model = torch.load("espaloma_model.pt")
     espaloma_model(molecule_graph.heterograph)
-
+    
     # create an OpenMM System for the specified molecule
     openmm_system = esp.graphs.deploy.openmm_system_from_graph(molecule_graph)
+

docs/install.rst

@@ -1,19 +1,12 @@
 Installation
 ============
 
-While we are working to put `espaloma` on conda-forge, please follow the instructions below to install dependencies and the `espaloma` package separately.
+conda
+-----
 
-Install dependencies::
+While we are working to put `dgl` on conda-forge, please follow the instructions below to install `espaloma` from `conda-forge` and the package `dgl` package from `dglteam`.
 
-    conda install \
-      --yes \
-      --channel conda-forge \ 
-      --channel dglteam \
-      openmm openmmtools openmmforcefields rdkit openff-toolkit dgl-cuda10.0 qcportal
+Install espaloma::
 
+    conda install -c conda-forge -c dglteam "espaloma=0.3.1" "dgl<1"
 
-Install the package::
-
-    git clone https://github.com/choderalab/espaloma.git
-    cd espaloma
-    python setup.py install