Add ReferenceVoltageVariationAdder

Lisrte · Lisrte · commit 79d1302d954b · 2026-01-05T16:36:44.000+01:00
Signed-off-by: lisrte &lt;laurent.issertial_externe@rte-france.com&gt;
diff --git a/cpp/pypowsybl-cpp/bindings.cpp b/cpp/pypowsybl-cpp/bindings.cpp
@@ -193,7 +193,8 @@ void dynamicSimulationBindings(py::module_& m) {
             .value("DISCONNECT", EventMappingType::DISCONNECT)
             .value("NODE_FAULT", EventMappingType::NODE_FAULT)
             .value("ACTIVE_POWER_VARIATION", EventMappingType::ACTIVE_POWER_VARIATION)
-            .value("REACTIVE_POWER_VARIATION", EventMappingType::REACTIVE_POWER_VARIATION);
+            .value("REACTIVE_POWER_VARIATION", EventMappingType::REACTIVE_POWER_VARIATION)
+            .value("REFERENCE_VOLTAGE_VARIATION", EventMappingType::REFERENCE_VOLTAGE_VARIATION);
 
     py::enum_<OutputVariableType>(m, "OutputVariableType")
              .value("CURVE", OutputVariableType::CURVE)
diff --git a/cpp/pypowsybl-java/powsybl-api.h b/cpp/pypowsybl-java/powsybl-api.h
@@ -393,6 +393,7 @@ typedef enum {
     NODE_FAULT,
     ACTIVE_POWER_VARIATION,
     REACTIVE_POWER_VARIATION,
+    REFERENCE_VOLTAGE_VARIATION,
 } EventMappingType;
 
 typedef enum {
diff --git a/docs/reference/dynamic.rst b/docs/reference/dynamic.rst
@@ -53,6 +53,7 @@ EventMapping
     EventMapping.add_disconnection
     EventMapping.add_active_power_variation
     EventMapping.add_reactive_power_variation
+    EventMapping.add_reference_voltage_variation
     EventMapping.add_node_fault
 
 OutputVariableMapping
diff --git a/java/pypowsybl/src/main/java/com/powsybl/dataframe/dynamic/adders/DynamicModelDataframeConstants.java b/java/pypowsybl/src/main/java/com/powsybl/dataframe/dynamic/adders/DynamicModelDataframeConstants.java
@@ -32,6 +32,7 @@ public final class DynamicModelDataframeConstants {
     public static final String DISCONNECT_ONLY = "disconnect_only";
     public static final String DELTA_P = "delta_p";
     public static final String DELTA_Q = "delta_q";
+    public static final String DELTA_U = "delta_u";
     public static final String FAULT_TIME = "fault_time";
     public static final String X_PU = "x_pu";
     public static final String R_PU = "r_pu";
diff --git a/java/pypowsybl/src/main/java/com/powsybl/dataframe/dynamic/adders/EventMappingHandler.java b/java/pypowsybl/src/main/java/com/powsybl/dataframe/dynamic/adders/EventMappingHandler.java
@@ -24,7 +24,8 @@ public final class EventMappingHandler {
             Map.entry(EventMappingType.DISCONNECT, new DisconnectAdder()),
             Map.entry(EventMappingType.NODE_FAULT, new NodeFaultAdder()),
             Map.entry(EventMappingType.ACTIVE_POWER_VARIATION, new ActivePowerVariationAdder()),
-            Map.entry(EventMappingType.REACTIVE_POWER_VARIATION, new ReactivePowerVariationAdder())
+            Map.entry(EventMappingType.REACTIVE_POWER_VARIATION, new ReactivePowerVariationAdder()),
+            Map.entry(EventMappingType.REFERENCE_VOLTAGE_VARIATION, new ReferenceVoltageVariationAdder())
     );
 
     public static void addElements(EventMappingType type, PythonEventModelsSupplier modelMapping, UpdatingDataframe dataframe) {
diff --git a/java/pypowsybl/src/main/java/com/powsybl/dataframe/dynamic/adders/NodeFaultAdder.java b/java/pypowsybl/src/main/java/com/powsybl/dataframe/dynamic/adders/NodeFaultAdder.java
@@ -10,9 +10,7 @@
 import com.powsybl.commons.report.ReportNode;
 import com.powsybl.dataframe.SeriesMetadata;
 import com.powsybl.dataframe.dynamic.PersistentDoubleSeries;
-import com.powsybl.dataframe.dynamic.PersistentStringSeries;
 import com.powsybl.dataframe.update.DoubleSeries;
-import com.powsybl.dataframe.update.StringSeries;
 import com.powsybl.dataframe.update.UpdatingDataframe;
 import com.powsybl.dynawo.models.events.NodeFaultEventBuilder;
 import com.powsybl.iidm.network.Network;
diff --git a/java/pypowsybl/src/main/java/com/powsybl/dataframe/dynamic/adders/ReactivePowerVariationAdder.java b/java/pypowsybl/src/main/java/com/powsybl/dataframe/dynamic/adders/ReactivePowerVariationAdder.java
@@ -37,7 +37,6 @@ public List<SeriesMetadata> getMetadata() {
 
     private static class ReactivePowerVariationSeries extends AbstractEventModelSeries<EventReactivePowerVariationBuilder> {
 
-
         private final DoubleSeries deltaQs;
 
         ReactivePowerVariationSeries(UpdatingDataframe dataframe) {
diff --git a/java/pypowsybl/src/main/java/com/powsybl/dataframe/dynamic/adders/ReferenceVoltageVariationAdder.java b/java/pypowsybl/src/main/java/com/powsybl/dataframe/dynamic/adders/ReferenceVoltageVariationAdder.java
@@ -0,0 +1,64 @@
+/**
+ * Copyright (c) 2026, RTE (http://www.rte-france.com/)
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+package com.powsybl.dataframe.dynamic.adders;
+
+import com.powsybl.commons.report.ReportNode;
+import com.powsybl.dataframe.SeriesMetadata;
+import com.powsybl.dataframe.dynamic.PersistentDoubleSeries;
+import com.powsybl.dataframe.update.DoubleSeries;
+import com.powsybl.dataframe.update.UpdatingDataframe;
+import com.powsybl.dynawo.models.events.EventReferenceVoltageVariationBuilder;
+import com.powsybl.iidm.network.Network;
+
+import java.util.List;
+
+import static com.powsybl.dataframe.dynamic.adders.DynamicModelDataframeConstants.*;
+import static com.powsybl.dataframe.network.adders.SeriesUtils.applyIfPresent;
+
+/**
+ * @author Laurent Issertial {@literal <laurent.issertial at rte-france.com>}
+ */
+public class ReferenceVoltageVariationAdder extends AbstractEventModelAdder {
+
+    protected static final List<SeriesMetadata> METADATA = List.of(
+            SeriesMetadata.stringIndex(STATIC_ID),
+            SeriesMetadata.doubles(START_TIME),
+            SeriesMetadata.doubles(DELTA_U));
+
+    @Override
+    public List<SeriesMetadata> getMetadata() {
+        return METADATA;
+    }
+
+    private static class ReferenceVoltageVariationSeries extends AbstractEventModelSeries<EventReferenceVoltageVariationBuilder> {
+
+        private final DoubleSeries deltaUs;
+
+        ReferenceVoltageVariationSeries(UpdatingDataframe dataframe) {
+            super(dataframe);
+            this.deltaUs = PersistentDoubleSeries.copyOf(dataframe, DELTA_U);
+        }
+
+        @Override
+        protected void applyOnBuilder(int row, EventReferenceVoltageVariationBuilder builder) {
+            applyIfPresent(staticIds, row, builder::staticId);
+            applyIfPresent(startTimes, row, builder::startTime);
+            applyIfPresent(deltaUs, row, builder::deltaU);
+        }
+
+        @Override
+        protected EventReferenceVoltageVariationBuilder createBuilder(Network network, ReportNode reportNode) {
+            return EventReferenceVoltageVariationBuilder.of(network, reportNode);
+        }
+    }
+
+    @Override
+    protected EventModelSeries createEventModelSeries(UpdatingDataframe dataframe) {
+        return new ReferenceVoltageVariationSeries(dataframe);
+    }
+}
diff --git a/java/pypowsybl/src/main/java/com/powsybl/python/commons/PyPowsyblApiHeader.java b/java/pypowsybl/src/main/java/com/powsybl/python/commons/PyPowsyblApiHeader.java
@@ -1226,7 +1226,8 @@ public enum EventMappingType {
         DISCONNECT,
         NODE_FAULT,
         ACTIVE_POWER_VARIATION,
-        REACTIVE_POWER_VARIATION;
+        REACTIVE_POWER_VARIATION,
+        REFERENCE_VOLTAGE_VARIATION;
 
         @CEnumValue
         public native int getCValue();
diff --git a/java/pypowsybl/src/test/java/com/powsybl/dataframe/dynamic/adders/EventModelsAdderTest.java b/java/pypowsybl/src/test/java/com/powsybl/dataframe/dynamic/adders/EventModelsAdderTest.java
@@ -73,6 +73,11 @@ static Stream<Arguments> eventProvider() {
                             df.addSeries(STATIC_ID, false, new TestStringSeries("GEN"));
                             df.addSeries(DELTA_Q, false, new TestDoubleSeries(1.4));
                         }),
+                Arguments.of(REFERENCE_VOLTAGE_VARIATION,
+                        (Consumer<DefaultUpdatingDataframe>) df -> {
+                            df.addSeries(STATIC_ID, false, new TestStringSeries("GEN"));
+                            df.addSeries(DELTA_U, false, new TestDoubleSeries(1.5));
+                        }),
                 Arguments.of(NODE_FAULT,
                         (Consumer<DefaultUpdatingDataframe>) df -> {
                             df.addSeries(STATIC_ID, false, new TestStringSeries("NLOAD"));
diff --git a/pypowsybl/_pypowsybl.pyi b/pypowsybl/_pypowsybl.pyi
@@ -661,6 +661,7 @@ class EventMappingType:
     NODE_FAULT: ClassVar[EventMappingType] = ...
     ACTIVE_POWER_VARIATION: ClassVar[EventMappingType] = ...
     REACTIVE_POWER_VARIATION: ClassVar[EventMappingType] = ...
+    REFERENCE_VOLTAGE_VARIATION: ClassVar[EventMappingType] = ...
 
 class OutputVariableType:
     __members__: ClassVar[Dict[str, OutputVariableType]] = ...  # read-only
diff --git a/pypowsybl/dynamic/impl/event_mapping.py b/pypowsybl/dynamic/impl/event_mapping.py
@@ -102,6 +102,33 @@ def add_reactive_power_variation(self, df: Optional[DataFrame] = None, **kwargs:
         """
         self._add_all_event_mappings(EventMappingType.REACTIVE_POWER_VARIATION, df, **kwargs)
 
+    def add_reference_voltage_variation(self, df: Optional[DataFrame] = None, **kwargs: ArrayLike) -> None:
+        """ Creates a reference voltage variation event on synchronized and synchronous generator
+
+        Args:
+            df: Attributes as a dataframe.
+            kwargs: Attributes as keyword arguments.
+
+        Notes:
+
+            Data may be provided as a dataframe or as keyword arguments.
+            In the latter case, all arguments must have the same length.
+
+            Valid attributes are:
+
+            - **static_id**: id of the generator affected by the event
+            - **start_time**: timestep at which the event happens
+            - **delta_u**: reference voltage variation
+
+        Examples:
+            Using keyword arguments:
+
+            .. code-block:: python
+
+                event_mapping.add_reference_voltage_variation(static_id='GEN', start_time=14, delta_u=2)
+        """
+        self._add_all_event_mappings(EventMappingType.REFERENCE_VOLTAGE_VARIATION, df, **kwargs)
+
     def add_node_fault(self, df: Optional[DataFrame] = None, **kwargs: ArrayLike) -> None:
         """ Creates a bus node fault event
 
diff --git a/tests/test_dynamic.py b/tests/test_dynamic.py
@@ -123,6 +123,7 @@ def test_add_event():
     event_mapping.add_disconnection(static_id='LINE', start_time=3.3, disconnect_only='TWO')
     event_mapping.add_active_power_variation(static_id='LOAD', start_time=14, delta_p=2)
     event_mapping.add_reactive_power_variation(static_id='LOAD', start_time=15, delta_q=3)
+    event_mapping.add_reference_voltage_variation(static_id='GEN', start_time=16, delta_u=4)
     event_mapping.add_node_fault(static_id='BUS', start_time=12, fault_time=2, r_pu=0.1, x_pu=0.2)
 
 
