BatteryShortCircuit extension (#3062)

* BatteryShortCircuit extension
* Add test
* Add some javadoc
* Support for BatteryShortCircuit extension legacy version

Signed-off-by: Coline PILOQUET <[email protected]>
Co-authored-by: Olivier Perrin <[email protected]>

Author: colinepiloquet

docs/grid_model/extensions.md

@@ -162,6 +162,31 @@ generator.newExtension(GeneratorShortCircuitAdder.class)
     .add();
 ```
 
+(battery-short-circuit)=
+## Battery short-circuit
+
+This extension models the battery data used for short-circuit calculations.
+Depending on the type of short-circuit study to be performed, either the transient or the sub-transient reactance should
+be filled. The step-up transformer reactance should be filled if the battery has a transformer that is not directly 
+modeled on the network.
+
+| Attribute              | Type   | Unit | Required | Default value | Description                                   |
+|------------------------|--------|------|----------|---------------|-----------------------------------------------|
+| directTransX (X'd)     | double | Ω    | yes      | -             | Direct transient reactance of the battery     |
+| directSubtransX (X''d) | double | Ω    | no       | -             | Direct sub-transient reactance of the battery |
+| stepUpTransformerX     | double | Ω    | no       | -             | Reactance of the step-up transformer          |
+
+This extension is provided in the  `com.powsybl:powsybl-iidm-extensions` module.
+
+To add this extension to a battery, the code to be used is:
+```java
+battery.newExtension(BatteryShortCircuitAdder.class)
+    .withDirectTransX(20)
+    .withDirectSubtransX(14)
+    .withStepUpTransformerX(10)
+    .add();
+```
+
 (identifiable-short-circuit-extension)=
 ## Identifiable short-circuit
 

docs/simulation/shortcircuit/outputs.md

@@ -42,7 +42,7 @@ In `FortescueFaultResult`, they are:
 
 This status can be:
 - `SUCCESS`: the computation went as planned, and the results are full considering the parameters.
-- `NO_SHORT_CIRCUIT_DATA`: this status should be returned if no short-circuit data are available in the network, i.e., the sub-transient or transient reactance of generators and the minimum and maximum admissible short-circuit currents.
+- `NO_SHORT_CIRCUIT_DATA`: this status should be returned if no short-circuit data are available in the network, i.e., the sub-transient or transient reactance of generators or batteries and the minimum and maximum admissible short-circuit currents.
 - `SOLVER_FAILURE`: the computation failed because of an error linked to the solver.
 - `FAILURE`: the computation failed for any other reason.
 

docs/simulation/shortcircuit/parameters.md

@@ -42,12 +42,13 @@ The default value is `true`.
 **study-type**
 
 This property indicates the type of short-circuit study. It can be:
-- `SUB_TRANSIENT`: it is the first stage of the short circuit, right when the fault happens. In this case, it is the sub-transient reactance of generators that is used.
-  This reactance can either be stored in the network or calculated from the transient reactance of generators with a coefficient defined by the parameter `sub-transient-coefficient`.
-- `TRANSIENT`: the second stage of the short circuit, before the system stabilizes. The transient reactance of generators will be used.
+- `SUB_TRANSIENT`: it is the first stage of the short circuit, right when the fault happens. In this case, it is the sub-transient reactance of generators and batteries that is used.
+  This reactance can either be stored in the network or calculated from the transient reactance of generators or batteries with a coefficient defined by the parameter `sub-transient-coefficient`.
+- `TRANSIENT`: the second stage of the short circuit, before the system stabilizes. The transient reactance of generators and batteries will be used.
 - `STEADY_STATE`: the last stage, once all transient effects are gone.
 
-The default value is `TRANSIENT`. The transient and sub-transient reactance of the generators are stored in the [short-circuit generator extension.](../../grid_model/extensions.md#generator-short-circuit)
+The default value is `TRANSIENT`. The transient and sub-transient reactances of the generators are stored in the [short-circuit generator extension.](../../grid_model/extensions.md#generator-short-circuit)
+and the ones of batteries are stored in the  [short-circuit battery extension.](../../grid_model/extensions.md#battery-short-circuit)
 
 **sub-transient-coefficient**
 
@@ -75,11 +76,11 @@ The voltage drop is calculated as the ratio between the initial voltage magnitud
 
 **with-loads**
 
-This property indicates whether loads should be taken into account during the calculation. If `true`, the loads are modelled as an equivalent reactance, and the equivalent reactance at the fault point will be lowered. If `false`, then they will be ignored.
+This property indicates whether loads should be taken into account during the calculation. If `true`, the loads are modeled as an equivalent reactance, and the equivalent reactance at the fault point will be lowered. If `false`, then they will be ignored.
 
 **with-shunt-compensators**
 
-This property indicates if shunt compensators should be taken into account during the computation. If `true`, the shunt compensators will be modelled as an equivalent reactance.
+This property indicates if shunt compensators should be taken into account during the computation. If `true`, the shunt compensators will be modeled as an equivalent reactance.
 If `false`, then the shunt compensators will be ignored.
 
 **with-vsc-converter-stations**

iidm/iidm-extensions/src/main/java/com/powsybl/iidm/network/extensions/BatteryShortCircuit.java

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) 2024, 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.iidm.network.extensions;
+
+import com.powsybl.iidm.network.Battery;
+
+/**
+ * The short-circuit reactances for batteries.
+ * @author Coline Piloquet {@literal <[email protected]>}
+ */
+public interface BatteryShortCircuit extends ShortCircuitExtension<Battery> {
+
+    String NAME = "batteryShortCircuit";
+
+    @Override
+    default String getName() {
+        return NAME;
+    }
+}

iidm/iidm-extensions/src/main/java/com/powsybl/iidm/network/extensions/BatteryShortCircuitAdder.java

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) 2024, 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.iidm.network.extensions;
+
+import com.powsybl.iidm.network.Battery;
+
+/**
+ * @author Coline Piloquet {@literal <[email protected]>}
+ */
+public interface BatteryShortCircuitAdder extends ShortCircuitExtensionAdder<Battery, BatteryShortCircuit, BatteryShortCircuitAdder> {
+
+    @Override
+    default Class<BatteryShortCircuit> getExtensionClass() {
+        return BatteryShortCircuit.class;
+    }
+}

iidm/iidm-extensions/src/main/java/com/powsybl/iidm/network/extensions/GeneratorShortCircuit.java

@@ -7,50 +7,18 @@
  */
 package com.powsybl.iidm.network.extensions;
 
-import com.powsybl.commons.extensions.Extension;
 import com.powsybl.iidm.network.Generator;
 
 /**
  *
  * @author Coline Piloquet {@literal <[email protected]>}
  */
-public interface GeneratorShortCircuit extends Extension<Generator> {
+public interface GeneratorShortCircuit extends ShortCircuitExtension<Generator> {
 
     String NAME = "generatorShortCircuit";
 
     @Override
     default String getName() {
         return NAME;
     }
-
-    /**
-     * Get the direct-axis sub-transient reactance (also known as X''d)
-     */
-    double getDirectSubtransX();
-
-    /**
-     * Set the direct-axis sub-transient reactance (also known as X''d)
-     */
-    GeneratorShortCircuit setDirectSubtransX(double directSubtransX);
-
-    /**
-     * Get the direct-axis transient reactance (also known as X'd)
-     */
-    double getDirectTransX();
-
-    /**
-     * Set the direct-axis transient reactance (also known as X'd)
-     */
-    GeneratorShortCircuit setDirectTransX(double directTransX);
-
-    /**
-     * Get the step-up transformer reactance if the generator has a non-modeled step-up transformer.
-     */
-    double getStepUpTransformerX();
-
-    /**
-     * Set the step-up transformer reactance
-     */
-    GeneratorShortCircuit setStepUpTransformerX(double setUpTransformerX);
-
 }

iidm/iidm-extensions/src/main/java/com/powsybl/iidm/network/extensions/GeneratorShortCircuitAdder.java

@@ -7,23 +7,16 @@
  */
 package com.powsybl.iidm.network.extensions;
 
-import com.powsybl.commons.extensions.ExtensionAdder;
 import com.powsybl.iidm.network.Generator;
 
 /**
  *
  * @author Coline Piloquet {@literal <[email protected]>}
  */
-public interface GeneratorShortCircuitAdder extends ExtensionAdder<Generator, GeneratorShortCircuit> {
+public interface GeneratorShortCircuitAdder extends ShortCircuitExtensionAdder<Generator, GeneratorShortCircuit, GeneratorShortCircuitAdder> {
 
     @Override
     default Class<GeneratorShortCircuit> getExtensionClass() {
         return GeneratorShortCircuit.class;
     }
-
-    GeneratorShortCircuitAdder withDirectTransX(double directTransX);
-
-    GeneratorShortCircuitAdder withDirectSubtransX(double direcSubtransX);
-
-    GeneratorShortCircuitAdder withStepUpTransformerX(double stepUpTransformerX);
 }

iidm/iidm-extensions/src/main/java/com/powsybl/iidm/network/extensions/ShortCircuitExtension.java

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) 2024, 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.iidm.network.extensions;
+
+import com.powsybl.commons.extensions.Extendable;
+import com.powsybl.commons.extensions.Extension;
+
+/**
+ * @author Coline Piloquet {@literal <[email protected]>}
+ */
+public interface ShortCircuitExtension<T extends Extendable<T>> extends Extension<T> {
+
+    /**
+     * Get the direct-axis sub-transient reactance (also known as X''d)
+     */
+    double getDirectSubtransX();
+
+    /**
+     * Set the direct-axis sub-transient reactance (also known as X''d)
+     */
+    ShortCircuitExtension<T> setDirectSubtransX(double directSubtransX);
+
+    /**
+     * Get the direct-axis transient reactance (also known as X'd)
+     */
+    double getDirectTransX();
+
+    /**
+     * Set the direct-axis transient reactance (also known as X'd)
+     */
+    ShortCircuitExtension<T> setDirectTransX(double directTransX);
+
+    /**
+     * Get the step-up transformer reactance if the generator or battery has a non-modeled step-up transformer.
+     */
+    double getStepUpTransformerX();
+
+    /**
+     * Set the step-up transformer reactance
+     */
+    ShortCircuitExtension<T> setStepUpTransformerX(double setUpTransformerX);
+
+}

iidm/iidm-extensions/src/main/java/com/powsybl/iidm/network/extensions/ShortCircuitExtensionAdder.java

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2024, 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.iidm.network.extensions;
+
+import com.powsybl.commons.PowsyblException;
+import com.powsybl.commons.extensions.Extendable;
+import com.powsybl.commons.extensions.ExtensionAdder;
+
+/**
+ *
+ * @author Coline Piloquet {@literal <[email protected]>}
+ */
+public interface ShortCircuitExtensionAdder<T extends Extendable<T>,
+        C extends ShortCircuitExtension<T>,
+        A extends ShortCircuitExtensionAdder<T, C, ?>> extends ExtensionAdder<T, C> {
+
+    @Override
+    default Class<C> getExtensionClass() {
+        throw new PowsyblException("Not yet implemented");
+    }
+
+    A withDirectTransX(double directTransX);
+
+    A withDirectSubtransX(double direcSubtransX);
+
+    A withStepUpTransformerX(double stepUpTransformerX);
+}

iidm/iidm-impl/src/main/java/com/powsybl/iidm/network/impl/extensions/AbstractShortCircuitExtensionAdderImpl.java

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) 2024, 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.iidm.network.impl.extensions;
+
+import com.powsybl.commons.PowsyblException;
+import com.powsybl.commons.extensions.AbstractExtensionAdder;
+import com.powsybl.commons.extensions.Extendable;
+import com.powsybl.iidm.network.extensions.ShortCircuitExtension;
+import com.powsybl.iidm.network.extensions.ShortCircuitExtensionAdder;
+
+/**
+ *
+ * @author Coline Piloquet {@literal <[email protected]>}
+ */
+public abstract class AbstractShortCircuitExtensionAdderImpl<T extends Extendable<T>,
+            C extends ShortCircuitExtension<T>,
+            A extends ShortCircuitExtensionAdder<T, C, ?>>
+        extends AbstractExtensionAdder<T, C>
+        implements ShortCircuitExtensionAdder<T, C, A> {
+
+    double directTransX = 0;
+    double directSubtransX = Double.NaN;
+    double stepUpTransformerX = Double.NaN;
+
+    protected AbstractShortCircuitExtensionAdderImpl(T extendable) {
+        super(extendable);
+    }
+
+    protected abstract A self();
+
+    @Override
+    protected C createExtension(T extendable) {
+        throw new PowsyblException("Not implemented");
+    }
+
+    @Override
+    public A withDirectTransX(double directTransX) {
+        this.directTransX = directTransX;
+        return self();
+    }
+
+    @Override
+    public A withDirectSubtransX(double directSubtransX) {
+        this.directSubtransX = directSubtransX;
+        return self();
+    }
+
+    @Override
+    public A withStepUpTransformerX(double stepUpTransformerX) {
+        this.stepUpTransformerX = stepUpTransformerX;
+        return self();
+    }
+
+    @Override
+    public C add() {
+        if (Double.isNaN(directTransX)) {
+            throw new PowsyblException("Undefined directTransX");
+        }
+        return super.add();
+    }
+}