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

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

@@ -45,7 +45,13 @@ def __init__(
 
     def __hash__(self) -> int:
         """
-        Return the hash
+        Return the hash.
+        The hash is generated using the sorted
+        nodes and edges of the graph, so the hash should be invariant to
+        node and edge order.
+
+        After being initially generated, the hash is cached for future use.
+
 
         Parameters
         ----------
@@ -310,7 +316,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/besmarts/core/topology.py

@@ -251,14 +251,14 @@ def pair_topology() -> structure_topology:
 
 
 # Singletons
-null = null_topology()
-atom = atom_topology()
-bond = bond_topology()
-angle = angle_topology()
-torsion = torsion_topology()
-outofplane = outofplane_topology()
-pair = n_body_topology(2)
-triplet = n_body_topology(3)
+null: structure_topology = null_topology()
+atom: structure_topology = atom_topology()
+bond: structure_topology = bond_topology()
+angle: structure_topology = angle_topology()
+torsion: structure_topology = torsion_topology()
+outofplane: structure_topology = outofplane_topology()
+pair: structure_topology = n_body_topology(2)
+triplet: structure_topology = n_body_topology(3)
 
 atom_to_atom = transcode_topology(
     atom,

besmarts-core/python/besmarts/mechanics/fits.py

@@ -1725,7 +1725,11 @@ def ff_optimize(
     initial_objective: objective_tier,
     tiers: List[objective_tier],
     final_objective: objective_tier,
-) -> mm.chemical_system:
+) -> tuple[
+        mm.chemical_system,
+        tuple[float, float],
+        tuple[float, float]
+    ]:
     """
     The toplevel function to run a full BESMARTS force field fit.
 
@@ -1740,6 +1744,15 @@ def ff_optimize(
     tiers: The tiers that will score each parameter candidate
     final_objective: The objective_tier that will score the remaining
     candidates passed by the tiers
+
+    Returns
+    -------
+    csys: mm.chemical_system
+        The final chemical system
+    physical_objectives: tuple[float, float]
+        The initial and final physical objectives
+    chemical_objectives: tuple[float, float]
+        The initial and final chemical objectives
     """
 
     started = datetime.datetime.now()

besmarts-core/python/besmarts/mechanics/molecular_models.py

@@ -459,7 +459,30 @@ def __init__(self, models: Dict[str, chemical_model], pcp_model):
         self.perception: perception.perception_model = pcp_model
 
 
-def chemical_system_iter_keys(csys):
+def chemical_system_iter_keys(
+    csys: chemical_system
+) -> dict[tuple[int, str, int], Any]:
+    """
+    Generate a flat mapping of keys and values of the system terms
+    in the chemical system.
+
+    Parameters
+    ----------
+    csys: :class:`chemical_system`
+
+    Returns
+    -------
+    dict[tuple[int, str, int], system_term]
+        The mapping of keys to system terms.
+        Each key is a tuple of three elements:
+        the model index (integer),
+        the term symbol (string),
+        the value index (integer).
+        Each value is the actual value of the term.
+        The type of each value can be found by looking up the
+        term in csys with
+        `csys.models[model_index].system_terms[term_symbol].cast`.
+    """
     kv = {}
     for m, cm in enumerate(csys.models):
         for t in cm.system_terms: