Improvements on docs (#402)

* Improvements on docs

* Add tips

docs/api.rst

@@ -5,6 +5,8 @@ TorchANI
     :members:
 .. autoclass:: torchani.ANIModel
 .. autoclass:: torchani.Ensemble
+.. autoclass:: torchani.SpeciesConverter
+    :members:
 .. autoclass:: torchani.EnergyShifter
     :members:
 .. autoclass:: torchani.nn.Gaussian

docs/conf.py

@@ -18,7 +18,6 @@ extensions = [
 ]
 
 templates_path = ['_templates']
-html_static_path = ['_static']
 
 source_suffix = '.rst'
 master_doc = 'index'

docs/index.rst

@@ -9,6 +9,7 @@ Welcome to TorchANI's documentation!
     :caption: Getting Started
 
     start
+    tips
 
 .. toctree::
     :maxdepth: 2
@@ -21,7 +22,6 @@ Welcome to TorchANI's documentation!
     examples/load_from_neurochem
     examples/nnp_training
     examples/nnp_training_force
-    examples/nnp_training_ignite
     examples/neurochem_trainer
 
 .. toctree::

docs/tips.rst

+Tips
+====
+
+- Coordinates are in Angstrom, energies are in Hartree
+    - Therefore, forces are in Hartree/Angstrom
+- Species are indexed by 0, 1, 2, 3, ....
+    - You could use :class:`torchani.SpeciesConverter` to convert from periodic table element index to 0, 1, 2, 3, ...
+    - Builtin models has an argument ``periodic_table_index`` in its constructor. You can set this to ``True`` when
+      constructing models to switch to periodic table indexing.
\ No newline at end of file

examples/energy_force.py

@@ -24,7 +24,8 @@ device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
 # issue in your application.
 #
 # The ``periodic_table_index`` arguments tells TorchANI to use element index
-# in periodic table to index species.
+# in periodic table to index species. If not specified, you need to use
+# 0, 1, 2, 3, ... to index species
 model = torchani.models.ANI1ccx(periodic_table_index=True).to(device)
 
 ###############################################################################
@@ -36,7 +37,7 @@ model = torchani.models.ANI1ccx(periodic_table_index=True).to(device)
 # training. If you have ``N`` different structures to compute, then make it
 # ``N``.
 #
-# The coordinates are in Angstrom, and the energies you get are in Hartree
+# .. note:: The coordinates are in Angstrom, and the energies you get are in Hartree
 coordinates = torch.tensor([[[0.03192167, 0.00638559, 0.01301679],
                              [-0.83140486, 0.39370209, -0.26395324],
                              [-0.66518241, -0.84461308, 0.20759389],

torchani/aev.py

@@ -374,6 +374,14 @@ class AEVComputer(torch.nn.Module):
                 ``(C, A, 3)`` where ``C`` is the number of molecules in a chunk,
                 and ``A`` is the number of atoms.
 
+                .. warning::
+
+                    The species must be indexed in 0, 1, 2, 3, ..., not the element
+                    index in periodic table. Check :class:`torchani.SpeciesConverter`
+                    if you want periodic table indexing.
+
+                .. note:: The coordinates, and cell are in Angstrom.
+
                 If you want to apply periodic boundary conditions, then the input
                 would be a tuple of two tensors (species, coordinates) and two keyword
                 arguments `cell=...` , and `pbc=...` where species and coordinates are
@@ -389,8 +397,6 @@ class AEVComputer(torch.nn.Module):
                 and pbc is boolean vector of size 3 storing if pbc is enabled
                 for that direction.
 
-                The coordinates, and cell are in Angstrom.
-
         Returns:
             NamedTuple: Species and AEVs. species are the species from the input
             unchanged, and AEVs is a tensor of shape ``(C, A, self.aev_length())``

torchani/nn.py

@@ -22,7 +22,13 @@ class ANIModel(torch.nn.ModuleDict):
     be applied to its AEV, after that, outputs of modules will be reduced along
     different atoms to obtain molecular energies.
 
-    The resulting energies are in Hartree.
+    .. warning::
+
+        The species must be indexed in 0, 1, 2, 3, ..., not the element
+        index in periodic table. Check :class:`torchani.SpeciesConverter`
+        if you want periodic table indexing.
+
+    .. note:: The resulting energies are in Hartree.
 
     Arguments:
         modules (:class:`collections.abc.Sequence`): Modules for each atom
@@ -124,5 +130,6 @@ class SpeciesConverter(torch.nn.Module):
     def forward(self, input_: Tuple[Tensor, Tensor],
                 cell: Optional[Tensor] = None,
                 pbc: Optional[Tensor] = None):
+        """Convert species from periodic table element index to 0, 1, 2, 3, ... indexing"""
         species, coordinates = input_
         return SpeciesCoordinates(self.conv_tensor[species], coordinates)