Add variable monitor for solver iteration output (#308)

* Add variable monitor for solver iteration output

* Update enum values style; fix template parameter convention for VariableMonitor

* Enable multiple styles specified through JSON input

* Add specific guidelines for enums

* Enable different variable types

* Switched to private implementation using magic_enum

---------

Co-authored-by: Nicholson Koukpaizan <koukpaizannk@ornl.gov>
Co-authored-by: pelesh <peless@ornl.gov>

Author: 3 people

CHANGELOG.md

@@ -39,6 +39,7 @@
 - Added a header file defining constants to be used throughout the code.
 - Added `GridKitDocs` target for Doxygen documentation.
 - Added a header file defining common math functions (e.g., sigmoid) to be used throughout the code.
+- Added capability to print monitored variables in multiple formats, triggered from `Ida::runSimulation`.
 
 ## v0.1
 

CONTRIBUTING.md

@@ -249,17 +249,6 @@ For consistency, use the same name everywhere the same type is used.
   template <typename real_type>; // No, `_type` used in a template parameter name
 ```
 
-### Enums (enumerated types)
-
-Always define `enum`s inside `GridKit` namespace. Type names should be
-capitalized and the constant names should be uppercase with underscores
-(but there is no underscore at the end!).
-
-```c++
-  enum ExampleEnum { CONST_ONE = 0,
-                     CONST_TWO = 8,
-                     YET_ANOTHER_CONST = 17 };
-```
 
 ### Constants
 
@@ -274,6 +263,23 @@ name. Use all caps (screaming snake case).
    constexpr double EXP = 2.7183      // Yes
 ```
 
+### Enums (enumerated types)
+
+Always define `enum`s inside `GridKit` namespace. The `enum` name should
+be upper camel case, same as class names. The `enum` element names should
+match symbol for physics quantity they represent or they should be uppercase
+(same as names for constants) if they do not represent a physics quantity.
+For example, enum element for real component of voltage $V_r$ should be `Vr`.
+A name for `enum` element for a "fast mode", for example, should be something
+like `FAST_MODE`, capitalized with underscores separating words (but no
+underscore at the end!).
+
+```c++
+  enum ExampleEnum { Vr, // Yes, it matches symbol for real voltage component
+                     VR, // No, the element name should match the physics symbol
+                     FAST_MODE}; // Yes, element name is all caps.
+```
+
 ### Pointers and references
 
 The pointer `*` or reference `&` belong to the type and there should be no space between them and the type name.

GridKit/Model/CMakeLists.txt

@@ -9,4 +9,8 @@ add_subdirectory(PhasorDynamics)
 add_subdirectory(PowerFlow)
 add_subdirectory(PowerElectronics)
 
-install(FILES Evaluator.hpp DESTINATION include/GridKit/Model)
+install(FILES
+  Evaluator.hpp
+  VariableMonitor.hpp
+  VariableMonitorController.hpp
+  DESTINATION include/GridKit/Model)

GridKit/Model/Evaluator.hpp

@@ -5,6 +5,7 @@
 #include <GridKit/CommonMath.hpp>
 #include <GridKit/Constants.hpp>
 #include <GridKit/LinearAlgebra/SparseMatrix/COO_Matrix.hpp>
+#include <GridKit/Model/VariableMonitor.hpp>
 #include <GridKit/ScalarTraits.hpp>
 
 namespace GridKit
@@ -45,6 +46,43 @@ namespace GridKit
       virtual IdxT size() = 0;
       virtual IdxT nnz()  = 0;
 
+      /**
+       * @brief Is there something to monitor? Defaults to `false`
+       */
+      virtual bool monitoring() const
+      {
+        return false;
+      }
+
+      /**
+       * @brief Print variables at current state
+       */
+      virtual void printMonitoredVariables() const
+      {
+      }
+
+      /**
+       * @brief Get non-owning reference to monitor
+       */
+      virtual const VariableMonitorBase* getMonitor() const
+      {
+        return nullptr;
+      }
+
+      /**
+       * @brief Get monitor ready for output
+       */
+      virtual void startMonitor()
+      {
+      }
+
+      /**
+       * @brief Tell monitor to wrap up
+       */
+      virtual void stopMonitor()
+      {
+      }
+
       /**
        * @brief Is the Jacobian defined. Used in IDA to determine wether DQ is used or not
        *

GridKit/Model/PhasorDynamics/Branch/Branch.hpp

@@ -8,8 +8,10 @@
  */
 #pragma once
 
+#include <GridKit/Model/PhasorDynamics/Branch/BranchData.hpp>
 #include <GridKit/Model/PhasorDynamics/Component.hpp>
 #include <GridKit/Model/PhasorDynamics/ComponentSignals.hpp>
+#include <GridKit/Model/VariableMonitor.hpp>
 
 // Forward declarations.
 namespace GridKit
@@ -51,11 +53,12 @@ namespace GridKit
       using Component<ScalarT, IdxT>::h_;
       using Component<ScalarT, IdxT>::J_;
 
+    public:
       using RealT           = typename Component<ScalarT, IdxT>::RealT;
       using bus_type        = BusBase<ScalarT, IdxT>;
       using model_data_type = BranchData<RealT, IdxT>;
+      using MonitorT        = Model::VariableMonitor<Branch, BranchData>;
 
-    public:
       Branch(bus_type* bus1, bus_type* bus2);
       Branch(bus_type* bus1, bus_type* bus2, RealT R, RealT X, RealT G, RealT B);
       Branch(bus_type* bus1, bus_type* bus2, const model_data_type& data);
@@ -77,7 +80,6 @@ namespace GridKit
       {
       }
 
-    public:
       void setR(RealT R)
       {
         R_ = R;
@@ -103,7 +105,11 @@ namespace GridKit
         setDerivedParams();
       }
 
+      const Model::VariableMonitorBase* getMonitor() const override;
+
     private:
+      void initializeParameters(const model_data_type& data);
+      void initializeMonitor();
       void setDerivedParams();
 
       ScalarT& Vr1()
@@ -162,9 +168,12 @@ namespace GridKit
       IdxT      bus1_id_{0};
       IdxT      bus2_id_{0};
 
-      /* Derivied parameters */
+      /* Derived parameters */
       RealT b_;
       RealT g_;
+
+      /// Variable monitor
+      std::unique_ptr<MonitorT> monitor_;
     };
 
   } // namespace PhasorDynamics

GridKit/Model/PhasorDynamics/Branch/BranchData.hpp

@@ -40,7 +40,7 @@ namespace GridKit
       ii2,
       im2,
       p2,
-      q2,
+      q2
     };
 
     /**

GridKit/Model/PhasorDynamics/Branch/BranchImpl.hpp

@@ -13,6 +13,7 @@
 #include <GridKit/Model/PhasorDynamics/Branch/Branch.hpp>
 #include <GridKit/Model/PhasorDynamics/Branch/BranchData.hpp>
 #include <GridKit/Model/PhasorDynamics/Bus/Bus.hpp>
+#include <GridKit/Model/VariableMonitorImpl.hpp>
 
 namespace GridKit
 {
@@ -74,37 +75,11 @@ namespace GridKit
     template <class ScalarT, typename IdxT>
     Branch<ScalarT, IdxT>::Branch(bus_type* bus1, bus_type* bus2, const model_data_type& data)
       : bus1_(bus1),
-        bus2_(bus2)
+        bus2_(bus2),
+        monitor_(std::make_unique<MonitorT>(data))
     {
-      if (data.parameters.contains(model_data_type::Parameters::R))
-      {
-        R_ = std::get<RealT>(data.parameters.at(model_data_type::Parameters::R));
-      }
-
-      if (data.parameters.contains(model_data_type::Parameters::X))
-      {
-        X_ = std::get<RealT>(data.parameters.at(model_data_type::Parameters::X));
-      }
-
-      if (data.parameters.contains(model_data_type::Parameters::G))
-      {
-        G_ = std::get<RealT>(data.parameters.at(model_data_type::Parameters::G));
-      }
-
-      if (data.parameters.contains(model_data_type::Parameters::B))
-      {
-        B_ = std::get<RealT>(data.parameters.at(model_data_type::Parameters::B));
-      }
-
-      if (data.ports.contains(model_data_type::Ports::bus1))
-      {
-        bus1_id_ = data.ports.at(model_data_type::Ports::bus1);
-      }
-
-      if (data.ports.contains(model_data_type::Ports::bus2))
-      {
-        bus2_id_ = data.ports.at(model_data_type::Ports::bus2);
-      }
+      initializeParameters(data);
+      initializeMonitor();
 
       size_ = 0;
       setDerivedParams();
@@ -277,6 +252,66 @@ namespace GridKit
       return 0;
     }
 
+    template <class ScalarT, typename IdxT>
+    void Branch<ScalarT, IdxT>::initializeParameters(const model_data_type& data)
+    {
+      if (data.parameters.contains(model_data_type::Parameters::R))
+      {
+        R_ = std::get<RealT>(data.parameters.at(model_data_type::Parameters::R));
+      }
+
+      if (data.parameters.contains(model_data_type::Parameters::X))
+      {
+        X_ = std::get<RealT>(data.parameters.at(model_data_type::Parameters::X));
+      }
+
+      if (data.parameters.contains(model_data_type::Parameters::G))
+      {
+        G_ = std::get<RealT>(data.parameters.at(model_data_type::Parameters::G));
+      }
+
+      if (data.parameters.contains(model_data_type::Parameters::B))
+      {
+        B_ = std::get<RealT>(data.parameters.at(model_data_type::Parameters::B));
+      }
+
+      if (data.ports.contains(model_data_type::Ports::bus1))
+      {
+        bus1_id_ = data.ports.at(model_data_type::Ports::bus1);
+      }
+
+      if (data.ports.contains(model_data_type::Ports::bus2))
+      {
+        bus2_id_ = data.ports.at(model_data_type::Ports::bus2);
+      }
+    }
+
+    template <class ScalarT, typename IdxT>
+    const Model::VariableMonitorBase* Branch<ScalarT, IdxT>::getMonitor() const
+    {
+      return monitor_.get();
+    }
+
+    template <class ScalarT, typename IdxT>
+    void Branch<ScalarT, IdxT>::initializeMonitor()
+    {
+      using Variable = typename model_data_type::MonitorableVariables;
+      monitor_->set(Variable::ir1, [this]
+                    { return Ir1(); });
+      monitor_->set(Variable::ii1, [this]
+                    { return Ii1(); });
+      // monitor_->set(Variable::im1, [this] { return ?(); });
+      // monitor_->set(Variable::p1, [this] { return ?(); });
+      // monitor_->set(Variable::q1, [this] { return ?(); });
+      monitor_->set(Variable::ir2, [this]
+                    { return Ir2(); });
+      monitor_->set(Variable::ii2, [this]
+                    { return Ii2(); });
+      // monitor_->set(Variable::im2, [this] { return ?(); });
+      // monitor_->set(Variable::p2, [this] { return ?(); });
+      // monitor_->set(Variable::q2, [this] { return ?(); });
+    }
+
     /**
      * @brief Derived parameters
      *

GridKit/Model/PhasorDynamics/Branch/CMakeLists.txt

@@ -15,6 +15,8 @@ if(GRIDKIT_ENABLE_ENZYME)
       BranchEnzyme.cpp
     HEADERS
       ${_install_headers}
+    INCLUDE_DIRECTORIES
+      PRIVATE ${GRIDKIT_THIRD_PARTY_DIR}/magic-enum/include
     LINK_LIBRARIES
       PRIVATE ClangEnzymeFlags
     COMPILE_OPTIONS
@@ -24,11 +26,14 @@ else()
     SOURCES
       Branch.cpp
     HEADERS
-      ${_install_headers})
+      ${_install_headers}
+    INCLUDE_DIRECTORIES
+      PRIVATE ${GRIDKIT_THIRD_PARTY_DIR}/magic-enum/include)
 endif()
 
 gridkit_add_library(phasor_dynamics_branch_dependency_tracking
-  SOURCES BranchDependencyTracking.cpp)
+  SOURCES BranchDependencyTracking.cpp
+  INCLUDE_DIRECTORIES PRIVATE ${GRIDKIT_THIRD_PARTY_DIR}/magic-enum/include)
 
 # Link to interface target for all components
 target_link_libraries(phasor_dynamics_components

GridKit/Model/PhasorDynamics/Bus/BusData.hpp

@@ -6,15 +6,24 @@
  */
 #pragma once
 
-#include <bitset>
 #include <optional>
+#include <set>
 #include <string>
 #include <type_traits>
 
 namespace GridKit
 {
   namespace PhasorDynamics
   {
+    /// Indices of the variables able to be monitored on this component
+    enum class BusMonitorableVariables : size_t
+    {
+      Vr,
+      Vi,
+      Vm,
+      Va
+    };
+
     /**
      * @brief Contains modeling data for a Bus
      *
@@ -49,20 +58,12 @@ namespace GridKit
       std::optional<RealT> freq_base;   ///< Override for the system-wide base frequency
       std::optional<RealT> va_base;     ///< Override for the system-wide power base
 
-      /// Indices of the variables able to be monitored on this component
-      enum class MonitorableVariables : size_t
-      {
-        VR,
-        VI,
-        VM,
-        VA,
-        MAXIMUM,
-      };
+      /// Alias
+      using MonitorableVariables = BusMonitorableVariables;
 
       /// Set indicating the variables being monitored
-      std::bitset<static_cast<
-          std::underlying_type_t<MonitorableVariables>>(MonitorableVariables::MAXIMUM)>
-          monitored_variables;
+      std::set<MonitorableVariables> monitored_variables;
     };
+
   } // namespace PhasorDynamics
 } // namespace GridKit