Add BusSignalVoltageOut and BusSignalVoltageIn bus models

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## v.03
 
+- Added `BusSignalVoltageOut` bus model with voltage signal outlets and current signal inlets.
+- Added `BusSignalVoltageIn` bus model with voltage signal inlets and current signal outlets.
 
 ## v0.2
 

GridKit/Model/PhasorDynamics/Bus/BusData.hpp

@@ -63,6 +63,8 @@ namespace GridKit
         INVALID,
         DEFAULT,
         SLACK,
+        SIGNAL_VOLTAGE_OUT, ///< Bus with voltage signal outputs and current signal inputs
+        SIGNAL_VOLTAGE_IN,  ///< Bus with voltage signal inputs and current signal outputs
       };
 
       BusType bus_type{BusType::INVALID}; ///< The kind of bus this data is for

GridKit/Model/PhasorDynamics/Bus/BusSignalVoltageIn/BusSignalVoltageIn.cpp

@@ -0,0 +1,17 @@
+/**
+ * @file BusSignalVoltageIn.cpp
+ * @author Slaven Peles (peless@ornl.gov)
+ */
+
+#include "BusSignalVoltageInImpl.hpp"
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    // Available template instantiations
+    template class BusSignalVoltageIn<double, long int>;
+    template class BusSignalVoltageIn<double, size_t>;
+
+  } // namespace PhasorDynamics
+} // namespace GridKit

GridKit/Model/PhasorDynamics/Bus/BusSignalVoltageIn/BusSignalVoltageIn.hpp

@@ -0,0 +1,175 @@
+/**
+ * @file BusSignalVoltageIn.hpp
+ * @author Slaven Peles (peless@ornl.gov)
+ * @brief Declaration of a bus whose voltage is set by input signals.
+ */
+
+#pragma once
+
+#include <stdexcept>
+#include <utility>
+
+#include <GridKit/Constants.hpp>
+#include <GridKit/Model/PhasorDynamics/Bus/BusSignalVoltageIn/BusSignalVoltageInData.hpp>
+#include <GridKit/Model/PhasorDynamics/BusBase.hpp>
+#include <GridKit/Model/PhasorDynamics/SignalPorts.hpp>
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    /*!
+     * @brief Bus whose voltage is set by input signals.
+     *
+     * This is the mirror image of @ref BusSignalVoltageOut. The bus voltage
+     * components _Vr_ and _Vi_ are read directly from signal inlets
+     * `vr` and `vi` whenever Vr() or Vi() is called; the bus stores no
+     * voltage of its own and never modifies it. Both voltage inlets are
+     * mandatory: verify() logs an error and throws for an inlet that is not
+     * connected to a linked signal, and reading the voltage through an
+     * unlinked inlet throws. No default voltage is ever used. The bus has
+     * no unknowns and no equations (size() == 0, like @ref BusInfinite).
+     * Components attached to the bus add their current injections to Ir()
+     * and Ii(); the resulting sums are published on signal outlets `ir`
+     * and `ii`.
+     *
+     * @note Signal ports have to be connected before allocate() is called, since
+     *       the output signals are linked there.
+     *
+     * @warning The current sums are complete only after all attached
+     *          components have evaluated their residuals. A consumer of the
+     *          `ir` and `ii` signals must be evaluated after them.
+     */
+    template <typename scalar_type, typename index_type>
+    class BusSignalVoltageIn : public BusBase<scalar_type, index_type>
+    {
+      using BusBase<scalar_type, index_type>::bus_id_;
+      using BusBase<scalar_type, index_type>::size_;
+      using BusBase<scalar_type, index_type>::nnz_;
+      using BusBase<scalar_type, index_type>::variable_indices_;
+      using BusBase<scalar_type, index_type>::residual_indices_;
+      using BusBase<scalar_type, index_type>::coo_jac_;
+      using BusBase<scalar_type, index_type>::monitor_;
+      using BusBase<scalar_type, index_type>::allocated_;
+
+    public:
+      using ScalarT      = scalar_type;
+      using IdxT         = index_type;
+      using RealT        = typename BusBase<ScalarT, IdxT>::RealT;
+      using CooMatrixT   = typename BusBase<ScalarT, IdxT>::CooMatrixT;
+      using MonitorT     = typename BusBase<ScalarT, IdxT>::MonitorT;
+      using ModelDataT   = BusData<RealT, IdxT>;
+      using BusTypeT     = typename BusData<RealT, IdxT>::BusType;
+      using SignalDataT  = BusSignalVoltageInData<RealT, IdxT>;
+      using SignalPortsT = SignalPorts<ScalarT, SignalDataT>;
+
+      BusSignalVoltageIn();
+      /// Initial voltage arguments are ignored; the voltage comes from signals.
+      BusSignalVoltageIn(ScalarT Vr, ScalarT Vi);
+      /// Initial voltage in `data` is ignored; the voltage comes from signals.
+      BusSignalVoltageIn(const ModelDataT& data);
+      virtual ~BusSignalVoltageIn();
+
+      virtual int setBusID(IdxT) override final;
+      virtual int allocate() override final;
+      virtual int verify() const override final;
+      virtual int tagDifferentiable() override final;
+      virtual int setAbsoluteTolerance(RealT rel_tol) override final;
+      virtual int initialize() override final;
+      virtual int evaluateResidual() override final;
+      virtual int evaluateJacobian() override final;
+
+      virtual BusTypeT BusType() const override final
+      {
+        return BusTypeT::SIGNAL_VOLTAGE_IN;
+      }
+
+      /**
+       * @brief Bus voltage, real component, read from the `vr` inlet.
+       *
+       * The BusBase interface requires a mutable reference, but the voltage
+       * is owned by the signal source. Callers must not write through it.
+       */
+      virtual ScalarT& Vr() override final
+      {
+        return const_cast<ScalarT&>(std::as_const(*this).Vr());
+      }
+
+      virtual const ScalarT& Vr() const override final
+      {
+        return readVoltage<BusSignalVoltageInInputs::vr>("vr");
+      }
+
+      /**
+       * @brief Bus voltage, imaginary component, read from the `vi` inlet.
+       *
+       * See Vr() for the note on the mutable overload.
+       */
+      virtual ScalarT& Vi() override final
+      {
+        return const_cast<ScalarT&>(std::as_const(*this).Vi());
+      }
+
+      virtual const ScalarT& Vi() const override final
+      {
+        return readVoltage<BusSignalVoltageInInputs::vi>("vi");
+      }
+
+      virtual ScalarT& Ir() override final
+      {
+        return Ir_;
+      }
+
+      virtual const ScalarT& Ir() const override final
+      {
+        return Ir_;
+      }
+
+      virtual ScalarT& Ii() override final
+      {
+        return Ii_;
+      }
+
+      virtual const ScalarT& Ii() const override final
+      {
+        return Ii_;
+      }
+
+      SignalPortsT& getPorts()
+      {
+        return ports_;
+      }
+
+      const SignalPortsT& getPorts() const
+      {
+        return ports_;
+      }
+
+    private:
+      /// Read a voltage inlet, throwing if it has no linked signal.
+      template <BusSignalVoltageInInputs input>
+      const ScalarT& readVoltage(const char* name) const
+      {
+        const auto& port = ports_.in.template port<input>();
+        if (!port.linked())
+        {
+          Log::error() << "BusSignalVoltageIn: voltage inlet " << name
+                       << " read without a linked signal\n";
+          throw std::runtime_error("BusSignalVoltageIn: voltage inlet has no linked signal");
+        }
+        return port.readSignal();
+      }
+
+      ScalarT Ir_{0.0};
+      ScalarT Ii_{0.0};
+
+      /// Current sums are not system variables; the output signals carry no valid index.
+      IdxT ir_index_{INVALID_INDEX<IdxT>};
+      IdxT ii_index_{INVALID_INDEX<IdxT>};
+
+      /// Signal ports (inlets and outlets)
+      SignalPortsT ports_;
+    };
+
+  } // namespace PhasorDynamics
+} // namespace GridKit

GridKit/Model/PhasorDynamics/Bus/BusSignalVoltageIn/BusSignalVoltageInData.hpp

@@ -0,0 +1,57 @@
+/**
+ * @file BusSignalVoltageInData.hpp
+ * @author Slaven Peles (peless@ornl.gov)
+ * @brief Signal port definitions for BusSignalVoltageIn.
+ *
+ * BusSignalVoltageIn is constructed from BusData like other buses. This header adds
+ * the port enumerations and a ComponentData alias that satisfies the
+ * ModelData concept, so the generic SignalPorts container can be reused for
+ * the bus's signal ports and connected from component-style data.
+ */
+#pragma once
+
+#include <cstddef>
+
+#include <GridKit/Model/PhasorDynamics/Bus/BusData.hpp>
+#include <GridKit/Model/PhasorDynamics/ComponentData.hpp>
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    /// BusSignalVoltageIn has no bus terminals of its own; it is a bus.
+    enum class BusSignalVoltageInBuses : size_t
+    {
+    };
+
+    /// Signal inlets of a bus with voltage signal inlets and current signal outlets (see BusSignalVoltageIn)
+    enum class BusSignalVoltageInInputs : size_t
+    {
+      vr, ///< Bus voltage, real component
+      vi, ///< Bus voltage, imaginary component
+    };
+
+    /// Signal outlets of a bus with voltage signal inlets and current signal outlets (see BusSignalVoltageIn)
+    enum class BusSignalVoltageInOutputs : size_t
+    {
+      ir, ///< Sum of real current injections from attached components
+      ii, ///< Sum of imaginary current injections from attached components
+    };
+
+    /**
+     * @brief Component-style data for BusSignalVoltageIn signal ports
+     *
+     * Reuses the bus parameter and monitorable-variable enumerations from
+     * BusData. Only the signal maps are used by the bus.
+     */
+    template <typename real_type, typename index_type>
+    using BusSignalVoltageInData =
+        ComponentData<real_type,
+                      index_type,
+                      BusParameters,
+                      BusSignalVoltageInBuses,
+                      BusSignalVoltageInInputs,
+                      BusSignalVoltageInOutputs,
+                      BusMonitorableVariables>;
+  } // namespace PhasorDynamics
+} // namespace GridKit

GridKit/Model/PhasorDynamics/Bus/BusSignalVoltageIn/BusSignalVoltageInDependencyTracking.cpp

@@ -0,0 +1,17 @@
+/**
+ * @file BusSignalVoltageInDependencyTracking.cpp
+ * @author Slaven Peles (peless@ornl.gov)
+ */
+
+#include "BusSignalVoltageInImpl.hpp"
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    // Available template instantiations
+    template class BusSignalVoltageIn<DependencyTracking::Variable, long int>;
+    template class BusSignalVoltageIn<DependencyTracking::Variable, size_t>;
+
+  } // namespace PhasorDynamics
+} // namespace GridKit