PV node: feature #185

code_generation/data/attribute_classes/input.json

@@ -176,7 +176,7 @@
             "name": "GenericBranchInput",
             "base": "BranchInput",
             "attributes": [
-                {    
+                {
                     "data_type": "double",
                     "names": ["r1","x1","g1","b1"],
                     "description": "positive sequence parameters"
@@ -540,6 +540,28 @@
                 }
             ]
         },
+        {
+            "name": "VoltageRegulatorInput",
+            "base": "RegulatorInput",
+            "is_template": false,
+            "attributes": [
+                {
+                    "data_type": "double",
+                    "names": [
+                        "u_ref"
+                    ],
+                    "description": "reference voltage"
+                },
+                {
+                    "data_type": "double",
+                    "names": [
+                        "q_min",
+                        "q_max"
+                    ],
+                    "description": "reactive power limits"
+                }
+            ]
+        },
         {
             "name": "GenericCurrentSensorInput",
             "base": "SensorInput",
@@ -557,7 +579,7 @@
                 {
                     "data_type": "double",
                     "names": [
-                        "i_sigma", 
+                        "i_sigma",
                         "i_angle_sigma"
                     ],
                     "description": "sigma of error margin of current (angle) measurement"

code_generation/data/attribute_classes/output.json

@@ -288,6 +288,25 @@
                 }
             ]
         },
+        {
+            "name": "VoltageRegulatorOutput",
+            "base": "BaseOutput",
+            "is_template": true,
+            "attributes": [
+                {
+                    "data_type": "IntS",
+                    "names": "limit_violated",
+                    "description": "indicates whether voltage limits are violated"
+                },
+                {
+                    "data_type": "RealValue<sym>",
+                    "names": [
+                        "q"
+                    ],
+                    "description": "additional reactive power injected by the voltage regulator"
+                }
+            ]
+        },
         {
             "name": "RegulatorShortCircuitOutput",
             "base": "BaseOutput",

code_generation/data/attribute_classes/update.json

@@ -244,6 +244,25 @@
                 }
             ]
         },
+        {
+            "name": "VoltageRegulatorUpdate",
+            "base": "RegulatorUpdate",
+            "attributes": [
+                {
+                    "data_type": "double",
+                    "names": "u_ref",
+                    "description": "reference voltage"
+                },
+                {
+                    "data_type": "double",
+                    "names": [
+                        "q_min",
+                        "q_max"
+                    ],
+                    "description": "reactive power limits"
+                }
+            ]
+        },
         {
             "name": "CurrentSensorUpdate",
             "base": "BaseUpdate",
@@ -252,7 +271,7 @@
                 {
                     "data_type": "double",
                     "names": [
-                        "i_sigma", 
+                        "i_sigma",
                         "i_angle_sigma"
                     ],
                     "description": "sigma of error margin of current (angle) measurement"

code_generation/data/dataset_class_maps/dataset_definitions.json

@@ -40,6 +40,10 @@
                     "names": ["sym_load", "sym_gen", "asym_load", "asym_gen"],
                     "class_name": "LoadGenInput"
                 },
+                {
+                    "names": ["voltage_regulator"],
+                    "class_name": "VoltageRegulatorInput"
+                },
                 {
                     "names": ["shunt"],
                     "class_name": "ShuntInput"
@@ -90,6 +94,10 @@
                     "names": ["sym_load", "sym_gen", "asym_load", "asym_gen", "shunt", "source"],
                     "class_name": "ApplianceOutput"
                 },
+                {
+                    "names": ["voltage_regulator"],
+                    "class_name": "VoltageRegulatorOutput"
+                },
                 {
                     "names": ["sym_voltage_sensor", "asym_voltage_sensor"],
                     "class_name": "VoltageSensorOutput"
@@ -144,6 +152,10 @@
                     "names": ["sym_load", "sym_gen", "asym_load", "asym_gen"],
                     "class_name": "LoadGenUpdate"
                 },
+                {
+                    "names": ["voltage_regulator"],
+                    "class_name": "VoltageRegulatorUpdate"
+                },
                 {
                     "names": ["shunt"],
                     "class_name": "ApplianceUpdate"

docs/user_manual/components.md

@@ -62,7 +62,7 @@ Physically a node can be a busbar, a joint, or other similar component.
 | `q`       | `RealValueOutput` | volt-ampere-reactive (var) | reactive power injection                                                                        |
 
 ```{note}
-The `p` and `q` output of injection follows the `generator` reference direction as mentioned in  
+The `p` and `q` output of injection follows the `generator` reference direction as mentioned in
 {hoverxreftooltip}`user_manual/data-model:Reference Direction`
 ```
 
@@ -256,7 +256,7 @@ $$
 
 where $z_{\text{base,transformer}} = 1 / y_{\text{base,transformer}} = {u_{\text{2}}}^2 / s_{\text{n}}$.
 
-### Generic Branch  
+### Generic Branch
 
 * type name: `generic_branch`
 
@@ -992,7 +992,7 @@ per method on how the variances are taken into account for both the global and l
 individual phases.
 
 ```{note}
-The combination of `i_measured=0` and `i_angle_measured=nπ/2` renders the current sensor invalid for PGM. 
+The combination of `i_measured=0` and `i_angle_measured=nπ/2` renders the current sensor invalid for PGM.
 See [State estimate sensor transformations](calculations.md#state-estimate-sensor-transformations).
 ```
 
@@ -1245,3 +1245,78 @@ node_1 --- transformer_4 --- node_2 --- line_5 --- node_3
 source_6     |                                    load_7
       transformer_tap_regulator_8
 ```
+
+### Voltage Regulator
+
+* type name: `voltage_regulator`
+* base: {hoverxreftooltip}`user_manual/components:regulator`
+
+`voltage_regulator` defines a regulator for voltage-controlled generators in the grid.
+A voltage regulator adjusts the reactive power output of a generator to maintain the voltage at its connection node at a specified setpoint.
+
+The voltage regulator changes the reactive power output of the generator it regulates to achieve the reference voltage `u_ref` at the generator's node.
+If `q_min` and `q_max` are provided, the reactive power is constrained within this range (i.e., `q_min <= q <= q_max` or `q_min >= q >= q_max`).
+If these limits are not provided, the reactive power can take any value needed to maintain the voltage setpoint.
+
+```{warning}
+Voltage regulation is only supported by the [Newton-Raphson](#newton-raphson-power-flow) method as an experimental feature.
+```
+
+```{note}
+The `regulated_object` must reference a generator (`sym_gen` or `asym_gen`) or a load (`sym_load` or `asym_load`).
+Each generator or load can have at most one voltage regulator.
+When multiple voltage-regulated generators are connected to the same node, they should all specify the same `u_ref` value to avoid conflicting voltage setpoints.
+```
+
+```{warning}
+Reactive power limit checking is not yet fully implemented. When `q_min` and `q_max` are specified, the intended behavior is that if the required reactive power to maintain `u_ref` exceeds these limits, the voltage regulator should operate at the limit and the voltage may deviate from `u_ref`.
+```
+
+#### Input
+
+| name     | data type | unit                       | description                                         |           required           |  update  | valid values |
+| -------- | --------- | -------------------------- | --------------------------------------------------- | :--------------------------: | :------: | :----------: |
+| `u_ref`  | `double`  | -                          | reference voltage in per-unit at the generator node | &#10024; only for power flow | &#10004; |    `> 0`     |
+| `q_min`  | `double`  | volt-ampere-reactive (var) | minimum reactive power limit of the generator       | &#10060;                     | &#10004; |              |
+| `q_max`  | `double`  | volt-ampere-reactive (var) | maximum reactive power limit of the generator       | &#10060;                     | &#10004; |              |
+
+#### Steady state output
+
+| name              | data type         | unit                       | description                                                          |
+| ----------------- | ----------------- | -------------------------- | -------------------------------------------------------------------- |
+| `q`               | `RealValueOutput` | volt-ampere-reactive (var) | reactive power provided by the voltage regulator                     |
+| `limit_violated`  | `int8_t`          | -                          | reactive power limit violation indicator (not yet fully implemented) |
+
+#### Short circuit output
+
+A `voltage_regulator` has no short circuit output.
+
+#### Electric Model
+
+The voltage regulator controls the generator to behave as a **PV node** in power flow calculations:
+
+$$
+   \begin{eqnarray}
+      & P_{\text{gen}} = P_{\text{specified}} \\
+      & |U_{\text{node}}| = U_{\text{ref}} \\
+      & Q_{\text{gen}} = \text{calculated to satisfy } U_{\text{ref}}
+   \end{eqnarray}
+$$
+
+When `q_min` and `q_max` are provided, the reactive power should be constrained:
+
+$$
+   Q_{\text{min}} \leq Q_{\text{gen}} \leq Q_{\text{max}}
+$$
+
+When fully implemented, if the reactive power constraints are violated, the generator will operate at the limit and the node becomes a PQ node:
+
+$$
+   \begin{eqnarray}
+      & P_{\text{gen}} = P_{\text{specified}} \\
+      & Q_{\text{gen}} = Q_{\text{min}} \text{ or } Q_{\text{max}} \\
+      & |U_{\text{node}}| = \text{calculated from power flow}
+   \end{eqnarray}
+$$
+
+In this case, `limit_violated` will indicate which limit was exceeded, and the actual voltage at the node may differ from `u_ref`.

power_grid_model_c/power_grid_model/include/power_grid_model/all_components.hpp

@@ -24,14 +24,15 @@
 #include "component/three_winding_transformer.hpp"
 #include "component/transformer.hpp"
 #include "component/transformer_tap_regulator.hpp"
+#include "component/voltage_regulator.hpp"
 #include "component/voltage_sensor.hpp"
 
 namespace power_grid_model {
 
 using AllComponents =
     ComponentList<Node, Line, AsymLine, Link, GenericBranch, Transformer, ThreeWindingTransformer, Shunt, Source,
                   SymGenerator, AsymGenerator, SymLoad, AsymLoad, SymPowerSensor, AsymPowerSensor, SymVoltageSensor,
-                  AsymVoltageSensor, SymCurrentSensor, AsymCurrentSensor, Fault, TransformerTapRegulator>;
+                  AsymVoltageSensor, SymCurrentSensor, AsymCurrentSensor, Fault, TransformerTapRegulator, VoltageRegulator>;
 
 using AllExtraRetrievableTypes =
     ExtraRetrievableTypes<Base, Node, Branch, Branch3, Appliance, GenericLoadGen, GenericLoad, GenericGenerator,

power_grid_model_c/power_grid_model/include/power_grid_model/auxiliary/input.hpp

@@ -491,6 +491,23 @@ struct TransformerTapRegulatorInput {
     operator RegulatorInput const&() const { return reinterpret_cast<RegulatorInput const&>(*this); }
 };
 
+struct VoltageRegulatorInput {
+    ID id{na_IntID};  // ID of the object
+    ID regulated_object{na_IntID};  // ID of the regulated object
+    IntS status{na_IntS};  // regulator enabled
+    double u_ref{nan};  // reference voltage
+    double q_min{nan};  // reactive power limits
+    double q_max{nan};  // reactive power limits
+
+    // implicit conversions to BaseInput
+    operator BaseInput&() { return reinterpret_cast<BaseInput&>(*this); }
+    operator BaseInput const&() const { return reinterpret_cast<BaseInput const&>(*this); }
+
+    // implicit conversions to RegulatorInput
+    operator RegulatorInput&() { return reinterpret_cast<RegulatorInput&>(*this); }
+    operator RegulatorInput const&() const { return reinterpret_cast<RegulatorInput const&>(*this); }
+};
+
 struct GenericCurrentSensorInput {
     ID id{na_IntID};  // ID of the object
     ID measured_object{na_IntID};  // ID of the measured object

power_grid_model_c/power_grid_model/include/power_grid_model/auxiliary/meta_gen/input.hpp

@@ -440,6 +440,20 @@ struct get_attributes_list<TransformerTapRegulatorInput> {
     };
 };
 
+template<>
+struct get_attributes_list<VoltageRegulatorInput> {
+    static constexpr std::array<MetaAttribute, 6> value{
+            // all attributes including base class
+
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorInput::id>(offsetof(VoltageRegulatorInput, id), "id"),
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorInput::regulated_object>(offsetof(VoltageRegulatorInput, regulated_object), "regulated_object"),
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorInput::status>(offsetof(VoltageRegulatorInput, status), "status"),
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorInput::u_ref>(offsetof(VoltageRegulatorInput, u_ref), "u_ref"),
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorInput::q_min>(offsetof(VoltageRegulatorInput, q_min), "q_min"),
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorInput::q_max>(offsetof(VoltageRegulatorInput, q_max), "q_max"),
+    };
+};
+
 template<>
 struct get_attributes_list<GenericCurrentSensorInput> {
     static constexpr std::array<MetaAttribute, 6> value{

power_grid_model_c/power_grid_model/include/power_grid_model/auxiliary/meta_gen/output.hpp

@@ -237,6 +237,20 @@ struct get_attributes_list<TransformerTapRegulatorOutput> {
     };
 };
 
+template <symmetry_tag sym_type>
+struct get_attributes_list<VoltageRegulatorOutput<sym_type>> {
+    using sym = sym_type;
+
+    static constexpr std::array<MetaAttribute, 4> value{
+            // all attributes including base class
+
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorOutput<sym>::id>(offsetof(VoltageRegulatorOutput<sym>, id), "id"),
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorOutput<sym>::energized>(offsetof(VoltageRegulatorOutput<sym>, energized), "energized"),
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorOutput<sym>::limit_violated>(offsetof(VoltageRegulatorOutput<sym>, limit_violated), "limit_violated"),
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorOutput<sym>::q>(offsetof(VoltageRegulatorOutput<sym>, q), "q"),
+    };
+};
+
 template<>
 struct get_attributes_list<RegulatorShortCircuitOutput> {
     static constexpr std::array<MetaAttribute, 2> value{

power_grid_model_c/power_grid_model/include/power_grid_model/auxiliary/meta_gen/update.hpp

@@ -197,6 +197,19 @@ struct get_attributes_list<TransformerTapRegulatorUpdate> {
     };
 };
 
+template<>
+struct get_attributes_list<VoltageRegulatorUpdate> {
+    static constexpr std::array<MetaAttribute, 5> value{
+            // all attributes including base class
+
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorUpdate::id>(offsetof(VoltageRegulatorUpdate, id), "id"),
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorUpdate::status>(offsetof(VoltageRegulatorUpdate, status), "status"),
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorUpdate::u_ref>(offsetof(VoltageRegulatorUpdate, u_ref), "u_ref"),
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorUpdate::q_min>(offsetof(VoltageRegulatorUpdate, q_min), "q_min"),
+            meta_data_gen::get_meta_attribute<&VoltageRegulatorUpdate::q_max>(offsetof(VoltageRegulatorUpdate, q_max), "q_max"),
+    };
+};
+
 template <symmetry_tag sym_type>
 struct get_attributes_list<CurrentSensorUpdate<sym_type>> {
     using sym = sym_type;

power_grid_model_c/power_grid_model/include/power_grid_model/auxiliary/output.hpp

@@ -236,6 +236,23 @@ struct TransformerTapRegulatorOutput {
     operator BaseOutput const&() const { return reinterpret_cast<BaseOutput const&>(*this); }
 };
 
+template <symmetry_tag sym_type>
+struct VoltageRegulatorOutput {
+    using sym = sym_type;
+
+    ID id{na_IntID};  // ID of the object
+    IntS energized{na_IntS};  // whether the object is energized
+    IntS limit_violated{na_IntS};  // indicates whether voltage limits are violated
+    RealValue<sym> q{nan};  // additional reactive power injected by the voltage regulator
+
+    // implicit conversions to BaseOutput
+    operator BaseOutput&() { return reinterpret_cast<BaseOutput&>(*this); }
+    operator BaseOutput const&() const { return reinterpret_cast<BaseOutput const&>(*this); }
+};
+
+using SymVoltageRegulatorOutput = VoltageRegulatorOutput<symmetric_t>;
+using AsymVoltageRegulatorOutput = VoltageRegulatorOutput<asymmetric_t>;
+
 struct RegulatorShortCircuitOutput {
     ID id{na_IntID};  // ID of the object
     IntS energized{na_IntS};  // whether the object is energized

power_grid_model_c/power_grid_model/include/power_grid_model/auxiliary/static_asserts/input.hpp

@@ -536,6 +536,21 @@ static_assert(offsetof(TransformerTapRegulatorInput, id) == offsetof(RegulatorIn
 static_assert(offsetof(TransformerTapRegulatorInput, regulated_object) == offsetof(RegulatorInput, regulated_object));
 static_assert(offsetof(TransformerTapRegulatorInput, status) == offsetof(RegulatorInput, status));
 
+// static asserts for VoltageRegulatorInput
+static_assert(std::is_standard_layout_v<VoltageRegulatorInput>);
+// static asserts for conversion of VoltageRegulatorInput to BaseInput
+static_assert(std::alignment_of_v<VoltageRegulatorInput> >= std::alignment_of_v<RegulatorInput>);
+static_assert(std::same_as<decltype(VoltageRegulatorInput::id), decltype(BaseInput::id)>);
+static_assert(offsetof(VoltageRegulatorInput, id) == offsetof(BaseInput, id));
+// static asserts for conversion of VoltageRegulatorInput to RegulatorInput
+static_assert(std::alignment_of_v<VoltageRegulatorInput> >= std::alignment_of_v<RegulatorInput>);
+static_assert(std::same_as<decltype(VoltageRegulatorInput::id), decltype(RegulatorInput::id)>);
+static_assert(std::same_as<decltype(VoltageRegulatorInput::regulated_object), decltype(RegulatorInput::regulated_object)>);
+static_assert(std::same_as<decltype(VoltageRegulatorInput::status), decltype(RegulatorInput::status)>);
+static_assert(offsetof(VoltageRegulatorInput, id) == offsetof(RegulatorInput, id));
+static_assert(offsetof(VoltageRegulatorInput, regulated_object) == offsetof(RegulatorInput, regulated_object));
+static_assert(offsetof(VoltageRegulatorInput, status) == offsetof(RegulatorInput, status));
+
 // static asserts for GenericCurrentSensorInput
 static_assert(std::is_standard_layout_v<GenericCurrentSensorInput>);
 // static asserts for conversion of GenericCurrentSensorInput to BaseInput