Add comments to ff fitting example, + some function signatures/docstrings

besmarts-core/python/besmarts/core/graphs.py

@@ -310,7 +310,20 @@ def graph_copy(beg: graph) -> graph:
     return g
 
 def graph_same(g: graph, h: graph) -> bool:
+    """
+    Compare two graphs for equality.
+
+    This function compares the nodes and edges of two graphs for equality.
+    Nodes and edges must satisfy the following conditions:
+
+    1. The nodes and edges must have the same keys.
+    2. These keys must map to the same atom/edge primitives.
 
+    While the node indices must map to the same primitives,
+    and therefore the order of atoms in each graph must be the same,
+    the order of the node key itself in the ``graph`` structure can differ.
+
+    """
     if set(g.nodes).symmetric_difference(h.nodes):
         return False
     if set(g.edges).symmetric_difference(h.edges):

besmarts-core/python/examples/07_besmarts_fit.py

@@ -8,7 +8,7 @@
 
 import tempfile
 import os
-from typing import Dict, List
+from typing import Dict, List, Optional
 from besmarts.mechanics import fits
 from besmarts.mechanics import smirnoff_models
 from besmarts.mechanics import molecular_models as mm
@@ -58,7 +58,24 @@
 """
 
 
-def load_xyz(flist, indices=None) -> assignments.graph_db_row:
+def load_xyz(flist: list[str], indices=Optional[list[int]]) -> assignments.graph_db_row:
+    """
+    Convert a list of xyz strings into a graph_db_row.
+    A graph_db_row is a collection of graph_db_columns, each of which
+    contains a selection of atoms and their coordinates.
+
+    Parameters
+    ----------
+    flist : list[str]
+        A list of xyz strings
+    indices: list[int]
+        A list of indices to use for the atoms. If None, the indices are
+        taken from the xyz files.
+
+    Returns
+    -------
+    assignments.graph_db_row
+    """
     s = 0
     N = None
     gdr = assignments.graph_db_row()
@@ -83,7 +100,17 @@ def load_xyz(flist, indices=None) -> assignments.graph_db_row:
                 s += 1
     return gdr
 
-def make():
+def make() -> dict[str, list[dict[int, str]]]:
+    """
+    Make a dataset for the optimization.
+    This returns a dictionary with a single molecule.
+    The key is its SMILES string. The value is a list with one dictionary.
+    The dictionary keys are essentially
+    integer enum values for property types,
+    where the integer value represents the index of the property in a
+    :class:`besmarts.core.assignments.graph_db_entry`.
+    """
+
     global smi
     global xyz_positions
     global xyz_grad
@@ -100,7 +127,11 @@ def make():
     return d
 
 
-def new_gdb(f: Dict[str, List[str]]) -> assignments.graph_db:
+def new_gdb(f: Dict[str, List[Dict[int, str]]]) -> assignments.graph_db:
+    """
+    This creates a ``graph_db`` from a dataset
+    as generated by ``make()``.
+    """
     gcd = codec_rdkit.graph_codec_rdkit()
     gdb = assignments.graph_db()
 
@@ -109,11 +140,6 @@ def new_gdb(f: Dict[str, List[str]]) -> assignments.graph_db:
         g = gcd.smiles_decode(smi)
         gid = assignments.graph_db_add_graph(gdb, smi, g)
 
-        gdb.graphs[gid] = g
-        gdb.smiles[gid] = smi
-        gdb.selections[topology.index_of(topology.atom)] = {
-            gid: {k: v for k, v in enumerate(graphs.graph_atoms(g))}
-        }
         gde = assignments.graph_db_entry()
         gdb.entries[len(gdb.entries)] = gde
         for rid, rdata in enumerate(fn_dict):