add better docstring about gathering

Author: lukelowry

GridKit/Model/OptimalPowerFlow/ComponentImpl.hpp

@@ -2,10 +2,14 @@
  * @file ComponentImpl.hpp
  * @brief Definition of `Component`, included by model translation units.
  *
- * `gather` copies the internal variables, then those at each port, into a
- * local array where the model evaluates, and the scatters add the results back.
- * Devices at the same bus add to the same entries, so a parallel evaluation
- * must synchronize those additions.
+ * A component evaluates on a local copy. `gather` copies its own variables,
+ * then the variables at each port, into one fixed-size array, the model
+ * evaluates there, and the scatter functions add the results back into the
+ * system vectors.
+ *
+ * Gathers only read, so they are safe in parallel. Scatters are not: every
+ * device at a bus adds to that bus's entries, so those additions must be
+ * synchronized, and buses with many devices are the likely bottleneck.
  */
 
 #pragma once
@@ -91,7 +95,7 @@ namespace GridKit
       return 0;
     }
 
-    /// Internal, then each port's variables
+    /// Copy the internal variables, then the variables each port reads from its component, into `x`
     template <typename scalar_type, typename index_type>
     void Component<scalar_type, index_type>::gather(ScalarT* x) const
     {

GridKit/Model/OptimalPowerFlow/SystemModel.hpp

@@ -24,6 +24,13 @@ namespace GridKit
     /**
      * @brief AC optimal power flow in Cartesian coordinates
      *
+     * `allocate()` gives each component a contiguous block of the system
+     * vectors. Each evaluation loops over the components, which gather,
+     * evaluate, and scatter as described in ComponentImpl.hpp.
+     *
+     * @todo Address thread safety. Constraint and gradient scatters and the
+     * derivative refill add to entries shared by devices at the same bus.
+     *
      * @todo Replace the temporary STL containers of system-level data.
      */
     template <typename scalar_type, typename index_type>

GridKit/Model/OptimalPowerFlow/SystemModelEnzyme.cpp

@@ -2,9 +2,10 @@
  * @file SystemModelEnzyme.cpp
  * @brief Optimal power flow system derivatives from component Enzyme entries.
  *
- * Each component writes its derivative entries to its own buffer. `refill`
- * adds them into the CSR values, where entries of different components can
- * share a value, so a parallel refill must synchronize those additions.
+ * Each component writes its derivative entries to its own buffer, so the
+ * components can be differentiated in parallel. `refill` then adds every entry
+ * into the CSR values, and entries from devices at the same bus land on the
+ * same value, so a parallel refill must synchronize those additions.
  */
 
 #include <algorithm>