#216 Implement shunt regulation model

sources/Algo/include/Algo.h

@@ -905,23 +905,42 @@ class DynModelAlgorithm : public NodeAlgorithm {
   const inputs::DynamicDataBaseManager& manager_;  ///< dynamic database config manager
 };
 
+/// @brief Shunts definition for a voltage level
+struct VLShuntsDefinition {
+  /// @brief Hash for shunts definition
+  struct ShuntHash {
+    /**
+     * @brief Retrieve the hash value
+     *
+     * @param shunt the shunt to hash
+     * @return the hash value
+     */
+    size_t operator()(const inputs::Shunt& shunt) const noexcept;
+  };
+  using ShuntsSet = std::unordered_set<inputs::Shunt, ShuntHash>;  ///< Alias for set of shunts
+
+  ShuntsSet shunts;                     ///< Set of shunts for current voltage level
+  bool dynamicModelAssociated = false;  ///< determines if the current voltage level is associated with a dynamic model
+};
+
 /**
- * @brief Shunt counter definition
+ * @brief Shunt definitions
  */
-struct ShuntCounterDefinitions {
-  std::unordered_map<inputs::VoltageLevel::VoltageLevelId, unsigned int> nbShunts;  ///< Number of shunts by voltage level
+struct ShuntDefinitions {
+  std::unordered_map<inputs::VoltageLevel::VoltageLevelId, VLShuntsDefinition> shunts;  ///< Shunt definitions by voltage level
 };
 
 /**
  * @brief Counter of shunts by voltage levels
  */
-class ShuntCounterAlgorithm : public NodeAlgorithm {
+class ShuntDefinitionAlgorithm : public NodeAlgorithm {
  public:
   /**
    * @brief Constructor
    * @param shuntCounterDefs the counter definitions to update
+   * @param manager dynamic data base manager
    */
-  explicit ShuntCounterAlgorithm(ShuntCounterDefinitions& shuntCounterDefs);
+  ShuntDefinitionAlgorithm(ShuntDefinitions& shuntCounterDefs, const inputs::DynamicDataBaseManager& manager);
 
   /**
    * @brief Performs the algorithm
@@ -933,7 +952,8 @@ class ShuntCounterAlgorithm : public NodeAlgorithm {
   void operator()(const NodePtr& node);
 
  private:
-  ShuntCounterDefinitions& shuntCounterDefs_;  ///< the counter definitions to update
+  ShuntDefinitions& shuntDefs_;                                                            ///< the counter definitions to update
+  std::unordered_set<inputs::VoltageLevel::VoltageLevelId> voltageLevelsWithAssociation_;  ///< dynamic data base manager
 };
 
 /**

sources/Algo/src/Algo.cpp

@@ -705,12 +705,23 @@ DynModelAlgorithm::MacroConnectHash::operator()(const MacroConnect& connect) con
 
 /////////////////////////////////////////////////////////////////////////////////
 
-ShuntCounterAlgorithm::ShuntCounterAlgorithm(ShuntCounterDefinitions& defs) : shuntCounterDefs_(defs) {}
+ShuntDefinitionAlgorithm::ShuntDefinitionAlgorithm(ShuntDefinitions& defs, const inputs::DynamicDataBaseManager& manager) : shuntDefs_(defs) {
+  const auto& multiAssociations = manager.assemblingDocument().multipleAssociations();
+  std::transform(multiAssociations.begin(), multiAssociations.end(), std::inserter(voltageLevelsWithAssociation_, voltageLevelsWithAssociation_.begin()),
+                 [](const inputs::AssemblingXmlDocument::MultipleAssociation& association) { return association.shunt.voltageLevel; });
+}
 
 void
-ShuntCounterAlgorithm::operator()(const NodePtr& node) {
+ShuntDefinitionAlgorithm::operator()(const NodePtr& node) {
   auto vl = node->voltageLevel.lock();
-  shuntCounterDefs_.nbShunts[vl->id] += node->shunts.size();
+  auto& map = shuntDefs_.shunts[vl->id];
+  std::copy(node->shunts.begin(), node->shunts.end(), std::inserter(map.shunts, map.shunts.end()));
+  map.dynamicModelAssociated |= (voltageLevelsWithAssociation_.count(vl->id) > 0);
+}
+
+size_t
+VLShuntsDefinition::ShuntHash::operator()(const inputs::Shunt& shunt) const noexcept {
+  return std::hash<inputs::Shunt::ShuntId>{}(shunt.id);
 }
 
 //////////////////////////////////////////////////////////////////////////////////

sources/Context.cpp

@@ -75,7 +75,7 @@ Context::Context(const ContextDef& def, const inputs::Configuration& config) :
 
   networkManager_.onNode(algo::MainConnexComponentAlgorithm(mainConnexNodes_));
   networkManager_.onNode(algo::DynModelAlgorithm(dynamicModels_, dynamicDataBaseManager_));
-  networkManager_.onNode(algo::ShuntCounterAlgorithm(counters_));
+  networkManager_.onNode(algo::ShuntDefinitionAlgorithm(shuntDefinitions_, dynamicDataBaseManager_));
   networkManager_.onNode(algo::LinesByIdAlgorithm(linesById_));
 }
 
@@ -175,7 +175,7 @@ Context::exportOutputs() {
   file::path dydOutput(config_.outputDir());
   dydOutput.append(basename_ + ".dyd");
   outputs::Dyd dydWriter(outputs::Dyd::DydDefinition(basename_, dydOutput.generic_string(), generators_, loads_, slackNode_, hvdcLineDefinitions_,
-                                                     busesWithDynamicModel_, dynamicDataBaseManager_, dynamicModels_, svarcsDefinitions_));
+                                                     busesWithDynamicModel_, dynamicDataBaseManager_, dynamicModels_, svarcsDefinitions_, shuntDefinitions_));
   dydWriter.write();
 
   // Par
@@ -191,7 +191,7 @@ Context::exportOutputs() {
   file::path parOutput(config_.outputDir());
   parOutput.append(basename_ + ".par");
   outputs::Par parWriter(outputs::Par::ParDefinition(basename_, config_.outputDir(), parOutput, generators_, hvdcLineDefinitions_,
-                                                     config_.getActivePowerCompensation(), busesWithDynamicModel_, dynamicDataBaseManager_, counters_,
+                                                     config_.getActivePowerCompensation(), busesWithDynamicModel_, dynamicDataBaseManager_, shuntDefinitions_,
                                                      dynamicModels_, linesById_, svarcsDefinitions_));
   parWriter.write();
 

sources/Context.h

@@ -170,7 +170,7 @@ class Context {
   algo::HVDCLineDefinitions hvdcLineDefinitions_;                        ///< hvdc definitions
   algo::GeneratorDefinitionAlgorithm::BusGenMap busesWithDynamicModel_;  ///< map of bus ids to a generator that regulates them
   algo::DynamicModelDefinitions dynamicModels_;                          ///< model definitions
-  algo::ShuntCounterDefinitions counters_;                               ///< shunt counters definitions
+  algo::ShuntDefinitions shuntDefinitions_;                              ///< shunt counters definitions
   algo::LinesByIdDefinitions linesById_;                                 ///< Lines by ids definition
   algo::StaticVarCompensatorDefinitions svarcsDefinitions_;              ///< Static var compensators definitions to use
   boost::optional<algo::ValidContingencies> validContingencies_;         ///< contingencies accepted for simulation in a Security Analyasis

sources/Inputs/include/Node.h

@@ -141,15 +141,41 @@ class Tfo {
 /// @brief Topological shunt
 struct Shunt {
   using ShuntId = std::string;  ///< alias for shunt id
+  using BusId = std::string;    ///< Alias for bus id regulated by the shunt
 
   /**
-   * @brief Constructor
+   * @brief Construct a new Shunt
    *
    * @param id the shunt id
+   * @param busId the regulated bus of the shunt
+   * @param targetV the target V of the shunt
+   * @param voltageRegulationOn whether voltage regulation is enabled for the shunt
+   * @param bs the vector of the B values for the shunt
    */
-  explicit Shunt(const ShuntId& id) : id(id) {}
+  Shunt(const ShuntId& id, const BusId& busId, double targetV, bool voltageRegulationOn, const std::vector<double>& bs) :
+      id(id),
+      busId(busId),
+      targetV(targetV),
+      voltageRegulationOn(voltageRegulationOn),
+      bSections(bs) {}
 
-  const ShuntId id;  ///< Shunt id
+  /**
+   * @brief Equality operator
+   *
+   * comparing the ids
+   *
+   * @param other the shunt to compare to
+   * @return @b true if the shunts are equal, @b false if not
+   */
+  bool operator==(const Shunt& other) const {
+    return id == other.id;
+  }
+
+  const ShuntId id;                     ///< Shunt id
+  const BusId busId;                    ///< the regulated bus of the shunt
+  const double targetV;                 ///< the target V of the shunt
+  const bool voltageRegulationOn;       ///< whether voltage regulation is enabled for the shunt
+  const std::vector<double> bSections;  ///< the vector of the B values for the shunt
 };
 
 /// @brief Topological dangling line

sources/Inputs/src/NetworkManager.cpp

@@ -75,8 +75,13 @@ NetworkManager::buildTree() {
     const auto& shunts = networkVL->getShuntCompensators();
     std::unordered_map<Node::NodeId, std::vector<Shunt>> shuntsMap;
     for (const auto& shunt : shunts) {
+      std::size_t nbSections = shunt->getMaximumSection() + 1;  // We add the first section at 0
+      std::vector<double> bs(nbSections);
+      unsigned int i = 0;
+      std::generate(bs.begin(), bs.end(), [&shunt, &i]() { return shunt->getB(i++); });
       // We take into account even disconnected shunts as dynamic models may aim to connect them
-      (shuntsMap[shunt->getBusInterface()->getID()]).push_back(std::move(Shunt(shunt->getID())));
+      (shuntsMap[shunt->getBusInterface()->getID()])
+          .push_back(std::move(Shunt(shunt->getID(), shunt->getBusInterface()->getID(), shunt->getTargetV(), shunt->isVoltageRegulationOn(), bs)));
     }
 
     auto vl = std::make_shared<VoltageLevel>(networkVL->getID());

sources/Outputs/include/Constants.h

@@ -18,15 +18,22 @@
 #pragma once
 
 #include "Algo.h"
+#include "Node.h"
 
+#include <functional>
 #include <limits>
 #include <string>
+#include <unordered_map>
+#include <vector>
 
 namespace dfl {
 namespace outputs {
 /// @brief Namespace for constant variables common to all writers
 namespace constants {
 
+/// @brief Alias for map of references to shunts by regulated bus id
+using RefShuntsByIdMap = std::unordered_map<inputs::Shunt::BusId, std::vector<std::reference_wrapper<const inputs::Shunt>>>;
+
 /**
  * @brief Return a hash number from a string as input
  * @param str The string that will serve as input for the hash function
@@ -59,6 +66,25 @@ computeQmax(double powerFactor, double pMax) {
  */
 std::string diagramFilename(const std::string& id);
 
+/**
+ * @brief Retrieve the shunt regulation id
+ *
+ * @param busId the bus id to which the shunt is connected
+ * @return the computed shunt regulation id
+ */
+static inline std::string
+computeShuntRegulationId(const std::string& busId) {
+  return "ShuntRegulation_" + busId;
+}
+
+/**
+ * @brief Compute the list of shunts, sorting by regulated bus id
+ *
+ * @param shuntDefinitions the shund definitions to use
+ * @return the sorted list of shunts
+ */
+RefShuntsByIdMap computeFilteredShuntsByIds(const algo::ShuntDefinitions& shuntDefinitions);
+
 const std::string networkModelName{"NETWORK"};                                    ///< Name of the model corresponding to network
 const std::string loadParId{"GenericRestorativeLoad"};                            ///< PAR id common to all loads
 const std::string diagramDirectorySuffix{"_Diagram"};                             ///< Suffix for the diagram directory

sources/Outputs/include/Dyd.h

@@ -104,12 +104,13 @@ class Dyd {
      * @param dynamicDataBaseManager the database manager to use
      * @param models the list of dynamic models to use
      * @param svarcsDefinitions the SVarC definitions to use
+     * @param shuntsDefinitions the shuntsDefinitions to use
      */
     DydDefinition(const std::string& base, const std::string& filepath, const std::vector<algo::GeneratorDefinition>& gens,
                   const std::vector<algo::LoadDefinition>& loaddefs, const std::shared_ptr<inputs::Node>& slacknode,
                   const algo::HVDCLineDefinitions& hvdcDefinitions, const algo::GeneratorDefinitionAlgorithm::BusGenMap& busesWithDynamicModel,
                   const inputs::DynamicDataBaseManager& dynamicDataBaseManager, const algo::DynamicModelDefinitions& models,
-                  const algo::StaticVarCompensatorDefinitions& svarcsDefinitions) :
+                  const algo::StaticVarCompensatorDefinitions& svarcsDefinitions, const algo::ShuntDefinitions& shuntsDefinitions) :
         basename(base),
         filename(filepath),
         generators(gens),
@@ -119,7 +120,8 @@ class Dyd {
         busesWithDynamicModel(busesWithDynamicModel),
         dynamicDataBaseManager(dynamicDataBaseManager),
         dynamicModelsDefinitions(models),
-        svarcsDefinitions(svarcsDefinitions) {}
+        svarcsDefinitions(svarcsDefinitions),
+        shuntsDefinitions(shuntsDefinitions) {}
 
     std::string basename;                                                        ///< basename for file
     std::string filename;                                                        ///< filepath for file to write
@@ -131,6 +133,7 @@ class Dyd {
     const inputs::DynamicDataBaseManager& dynamicDataBaseManager;                ///< dynamic database manager
     const algo::DynamicModelDefinitions& dynamicModelsDefinitions;               ///< the list of dynamic models to export
     const algo::StaticVarCompensatorDefinitions& svarcsDefinitions;              ///< the SVarC definitions to use
+    const algo::ShuntDefinitions& shuntsDefinitions;                             ///< the shuntsDefinitions to use
   };
 
   /**
@@ -186,6 +189,15 @@ class Dyd {
    */
   static boost::shared_ptr<dynamicdata::BlackBoxModel> writeHvdcLine(const algo::HVDCDefinition& hvdcLine, const std::string& basename);
 
+  /**
+   * @brief Write the black box model for shunt regulation
+   *
+   * @param busId the bus id to use
+   * @param basename the basename of the writer
+   * @return the model of the shunt regulation
+   */
+  static boost::shared_ptr<dynamicdata::BlackBoxModel> writeShuntRegulation(const inputs::Shunt::BusId& busId, const std::string& basename);
+
   /**
    * @brief Create constant models
    *

sources/Outputs/include/Par.h

@@ -55,7 +55,7 @@ class Par {
      * @param activePowerCompensation the type of active power compensation
      * @param busesWithDynamicModel map of bus ids to a generator that regulates them
      * @param dynamicDataBaseManager dynamic database manager to use
-     * @param counters the counters definitions to use
+     * @param shunts the shunts definitions to use
      * @param models list of dynamic models definitions
      * @param linesById the lines to use
      * @param svarcsDefinitions the SVarC definitions to use
@@ -64,7 +64,7 @@ class Par {
                   const std::vector<algo::GeneratorDefinition>& gens, const algo::HVDCLineDefinitions& hvdcDefinitions,
                   inputs::Configuration::ActivePowerCompensation activePowerCompensation,
                   const algo::GeneratorDefinitionAlgorithm::BusGenMap& busesWithDynamicModel, const inputs::DynamicDataBaseManager& dynamicDataBaseManager,
-                  const algo::ShuntCounterDefinitions& counters, const algo::DynamicModelDefinitions& models, const algo::LinesByIdDefinitions& linesById,
+                  const algo::ShuntDefinitions& shunts, const algo::DynamicModelDefinitions& models, const algo::LinesByIdDefinitions& linesById,
                   const algo::StaticVarCompensatorDefinitions& svarcsDefinitions) :
         basename(base),
         dirname(dir),
@@ -74,7 +74,7 @@ class Par {
         activePowerCompensation(activePowerCompensation),
         busesWithDynamicModel(busesWithDynamicModel),
         dynamicDataBaseManager(dynamicDataBaseManager),
-        shuntCounters(counters),
+        shuntsDefinitions(shunts),
         dynamicModelsDefinitions(models),
         linesByIdDefinitions(linesById),
         svarcsDefinitions(svarcsDefinitions) {}
@@ -87,7 +87,7 @@ class Par {
     dfl::inputs::Configuration::ActivePowerCompensation activePowerCompensation;  ///< the type of active power compensation
     const algo::GeneratorDefinitionAlgorithm::BusGenMap& busesWithDynamicModel;   ///< map of bus ids to a generator that regulates them
     const inputs::DynamicDataBaseManager& dynamicDataBaseManager;                 ///< dynamic database manager
-    const algo::ShuntCounterDefinitions& shuntCounters;                           ///< Shunt counters to use
+    const algo::ShuntDefinitions& shuntsDefinitions;                              ///< Shunt shunts to use
     const algo::DynamicModelDefinitions& dynamicModelsDefinitions;                ///< list of defined dynamic models
     const algo::LinesByIdDefinitions& linesByIdDefinitions;                       ///< lines by id to use
     const algo::StaticVarCompensatorDefinitions& svarcsDefinitions;               ///< the SVarC definitions to use
@@ -165,6 +165,16 @@ class Par {
   static boost::shared_ptr<parameters::ParametersSet> writeHdvcLine(const algo::HVDCDefinition& hvdcLine, const std::string& basename,
                                                                     const boost::filesystem::path& dirname);
 
+  /**
+   * @brief Write the parameters for a shunt regulation set
+   *
+   * @param busId the bus id of the shunt regulation
+   * @param shunts the list of the shunts for the bus
+   * @return the parameter set of the shunt regulation
+   */
+  static boost::shared_ptr<parameters::ParametersSet> writeShuntRegulation(const inputs::Shunt::BusId& busId,
+                                                                           const std::vector<std::reference_wrapper<const dfl::inputs::Shunt>>& shunts);
+
   /**
    * @brief Write remote voltage regulators parameter set
    *
@@ -180,17 +190,15 @@ class Par {
    *
    * @param set the configuration set to write
    * @param assemblingDoc the corresponding assembling document handler
-   * @param counters the counters to use
+   * @param shunts the shunts to use
    * @param models the models definitions to use
    * @param linesById lines by id to use
    *
    * @returns the parameter set to add
    */
-  static boost::shared_ptr<parameters::ParametersSet> writeDynamicModelParameterSet(const inputs::SettingXmlDocument::Set& set,
-                                                                                    const inputs::AssemblingXmlDocument& assemblingDoc,
-                                                                                    const algo::ShuntCounterDefinitions& counters,
-                                                                                    const algo::DynamicModelDefinitions& models,
-                                                                                    const algo::LinesByIdDefinitions& linesById);
+  static boost::shared_ptr<parameters::ParametersSet>
+  writeDynamicModelParameterSet(const inputs::SettingXmlDocument::Set& set, const inputs::AssemblingXmlDocument& assemblingDoc,
+                                const algo::ShuntDefinitions& shunts, const algo::DynamicModelDefinitions& models, const algo::LinesByIdDefinitions& linesById);
 
   /**
    * @brief Retrieves the first component connected through the dynamic model to a transformer

sources/Outputs/src/Constants.cpp

@@ -32,6 +32,27 @@ diagramFilename(const std::string& id) {
   return idCpy + "_Diagram.txt";
 }
 
+RefShuntsByIdMap
+computeFilteredShuntsByIds(const algo::ShuntDefinitions& shuntDefinitions) {
+  RefShuntsByIdMap ret;
+
+  for (const auto& shuntDefPair : shuntDefinitions.shunts) {
+    const auto& shuntDef = shuntDefPair.second;
+    if (shuntDef.dynamicModelAssociated) {
+      continue;
+    }
+    for (const auto& shunt : shuntDef.shunts) {
+      if (!shunt.voltageRegulationOn) {
+        continue;
+      }
+      // Only the shunts with no dynamic model associated and voltage regulation on are added
+      ret[shunt.busId].push_back(std::ref(shunt));
+    }
+  }
+
+  return ret;
+}
+
 }  // namespace constants
 }  // namespace outputs
 }  // namespace dfl