Expanding SLC docstrings

Author: johnjasa

h2integrate/control/control_strategies/system_level/demand_following_control.py

@@ -8,13 +8,24 @@
 class DemandFollowingControl(SystemLevelControlBase):
     """Demand-following system-level controller.
 
-    Dispatch priority:
-    1. Curtailable techs run at rated capacity (zero marginal cost).
-    2. Storage absorbs surplus / provides deficit (set_point = net demand).
-    3. Remaining demand is split equally across dispatchable techs.
+    Dispatches technologies to meet a time-varying demand profile without
+    considering costs. The demand is satisfied in a fixed three-step priority
+    order, and each step's shortfall or surplus is passed to the next:
 
-    This strategy always attempts to meet demand exactly; it does not
-    consider costs.
+    1. **Curtailable techs** run at their full rated capacity. Their total
+       output is subtracted from the demand, which may drive the residual
+       demand negative (surplus).
+
+    2. **Storage techs** receive the residual demand (which may be positive
+       or negative). When demand is positive the storage is commanded to
+       discharge; when negative it is commanded to charge. If multiple
+       storage techs produce the demanded commodity, the residual demand is
+       split **evenly** across them (each receives ``demand / n_storage``).
+
+    3. **Dispatchable techs** cover any remaining positive demand after
+       storage. The remaining demand (floored at zero) is split **evenly**
+       across all dispatchable techs that produce the demanded commodity
+       (each receives ``remaining_demand / n_dispatchable``).
     """
 
     def compute(self, inputs, outputs):

h2integrate/control/control_strategies/system_level/solver_options.py

@@ -9,6 +9,25 @@
 
 @define(kw_only=True)
 class SLCSolverOptionsConfig(BaseConfig):
+    """Configuration for the nonlinear solver used by the system-level controller.
+
+    Controls which OpenMDAO nonlinear solver is applied to the plant group and
+    how it converges. The ``convergence_tolerance`` sets both ``atol`` and ``rtol``
+    by default; either can be overridden individually.
+
+    Attributes:
+        solver_name: Solver type. One of ``"gauss_seidel"``, ``"newton"``, or
+            ``"block_jacobi"``.
+        max_iter: Maximum number of nonlinear iterations.
+        atol: Absolute convergence tolerance. Defaults to ``convergence_tolerance``.
+        rtol: Relative convergence tolerance. Defaults to ``convergence_tolerance``.
+        convergence_tolerance: Convenience value used to set both ``atol`` and ``rtol``
+            when they are not specified individually.
+        iprint: Solver print level (0 = silent, 2 = verbose).
+        solver_option_kwargs: Additional keyword arguments passed directly to the
+            solver's ``options`` dict.
+    """
+
     solver_name: str = field(
         default="gauss_seidel", validator=contains(["gauss_seidel", "newton", "block_jacobi"])
     )
@@ -19,20 +38,31 @@ class SLCSolverOptionsConfig(BaseConfig):
     iprint: int = field(default=2)
     solver_option_kwargs: dict = field(default={})
 
+    # Maps user-facing solver names to OpenMDAO solver classes
     solver_map: ClassVar = {
         "gauss_seidel": om.NonlinearBlockGS,
         "newton": om.NewtonSolver,
         "block_jacobi": om.NonlinearBlockJac,
     }
 
     def __attrs_post_init__(self):
+        # Default atol/rtol to the shared convergence_tolerance if not set
         if self.atol is None:
             self.atol = self.convergence_tolerance
         if self.rtol is None:
             self.rtol = self.convergence_tolerance
 
     def get_solver_options(self):
+        """Build the options dict to apply to the nonlinear solver.
+
+        Merges config attributes with any extra ``solver_option_kwargs`` and
+        renames ``max_iter`` to ``maxiter`` (the OpenMDAO option name).
+
+        Returns:
+            dict: Keyword arguments suitable for ``solver.options[k] = v``.
+        """
         d = self.as_dict()
+        # These attrs configure *which* solver or are handled separately
         non_solver_option_attrs = [
             "solver_name",
             "solver_map",
@@ -41,10 +71,12 @@ def get_solver_options(self):
             "max_iter",
         ]
         solver_options = {k: v for k, v in d.items() if k not in non_solver_option_attrs}
+        # Merge extra kwargs and translate max_iter → maxiter for OpenMDAO
         solver_options_full = (
             solver_options | self.solver_option_kwargs | {"maxiter": self.max_iter}
         )
         return solver_options_full
 
     def return_nonlinear_solver(self):
+        """Return the OpenMDAO nonlinear solver class for ``solver_name``."""
         return self.solver_map[self.solver_name]