BatteryShortCircuit extension

Signed-off-by: Coline PILOQUET <coline.piloquet@rte-france.com>

docs/grid_model/extensions.md

@@ -148,6 +148,30 @@ generator.newExtension(GeneratorShortCircuitAdder.class)
  .add();
 ```
 
+## 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
 
 This extension models the maximum and minimum short-circuit current admissible for any identifiable.

docs/simulation/shortcircuit/outputs.md

@@ -41,8 +41,8 @@ In `FortescueFaultResult`, they are:
 **The status of the computation**
 
 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.
+- `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 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/AbstractShortCircuit.java

@@ -0,0 +1,49 @@
+/**
+ * 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 <coline.piloquet@rte-france.fr>}
+ */
+public interface AbstractShortCircuit<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)
+ */
+ AbstractShortCircuit<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)
+ */
+ AbstractShortCircuit<T> 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
+ */
+ AbstractShortCircuit<T> setStepUpTransformerX(double setUpTransformerX);
+
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2021, 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 <coline.piloquet@rte-france.fr>}
+ */
+public interface AbstractShortCircuitAdder<T extends Extendable<T>, C extends AbstractShortCircuit<T>> extends ExtensionAdder<T, C> {
+
+ @Override
+ default Class<C> getExtensionClass() {
+ throw new PowsyblException("Not yet implemented");
+ }
+
+ AbstractShortCircuitAdder<T, C> withDirectTransX(double directTransX);
+
+ AbstractShortCircuitAdder<T, C> withDirectSubtransX(double direcSubtransX);
+
+ AbstractShortCircuitAdder<T, C> withStepUpTransformerX(double stepUpTransformerX);
+}

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

@@ -0,0 +1,23 @@
+/**
+ * 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 <coline.piloquet@rte-france.fr>}
+ */
+public interface BatteryShortCircuit extends AbstractShortCircuit<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 <coline.piloquet@rte-france.fr>}
+ */
+public interface BatteryShortCircuitAdder extends AbstractShortCircuitAdder<Battery, BatteryShortCircuit> {
+
+ @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 <coline.piloquet@rte-france.fr>}
  */
-public interface GeneratorShortCircuit extends Extension<Generator> {
+public interface GeneratorShortCircuit extends AbstractShortCircuit<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 <coline.piloquet@rte-france.fr>}
  */
-public interface GeneratorShortCircuitAdder extends ExtensionAdder<Generator, GeneratorShortCircuit> {
+public interface GeneratorShortCircuitAdder extends AbstractShortCircuitAdder<Generator, GeneratorShortCircuit> {
 
  @Override
  default Class<GeneratorShortCircuit> getExtensionClass() {
  return GeneratorShortCircuit.class;
  }
-
- GeneratorShortCircuitAdder withDirectTransX(double directTransX);
-
- GeneratorShortCircuitAdder withDirectSubtransX(double direcSubtransX);
-
- GeneratorShortCircuitAdder withStepUpTransformerX(double stepUpTransformerX);
 }

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

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) 2021, 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.AbstractExtension;
+import com.powsybl.commons.extensions.Extendable;
+import com.powsybl.iidm.network.extensions.AbstractShortCircuit;
+
+/**
+ *
+ * @author Coline Piloquet {@literal <coline.piloquet@rte-france.fr>}
+ */
+public abstract class AbstractShortCircuitImpl<T extends Extendable<T>> extends AbstractExtension<T>
+ implements AbstractShortCircuit<T> {
+
+ private double directSubtransX; // X''d
+ private double directTransX; // X'd
+ private double stepUpTransformerX; // Reactance of the step-up transformer
+
+ protected AbstractShortCircuitImpl(T extendable, double directSubtransX, double directTransX,
+ double stepUpTransformerX) {
+ super(extendable);
+ this.directSubtransX = directSubtransX;
+ this.directTransX = directTransX;
+ this.stepUpTransformerX = stepUpTransformerX;
+ }
+
+ @Override
+ public double getDirectSubtransX() {
+ return directSubtransX;
+ }
+
+ @Override
+ public AbstractShortCircuitImpl<T> setDirectSubtransX(double directSubtransX) {
+ this.directSubtransX = directSubtransX;
+ return this;
+ }
+
+ @Override
+ public double getDirectTransX() {
+ return directTransX;
+ }
+
+ @Override
+ public AbstractShortCircuitImpl<T> setDirectTransX(double directTransX) {
+ if (Double.isNaN(directTransX)) {
+ throw new PowsyblException("Undefined directTransX");
+ }
+ this.directTransX = directTransX;
+ return this;
+ }
+
+ @Override
+ public double getStepUpTransformerX() {
+ return stepUpTransformerX;
+ }
+
+ @Override
+ public AbstractShortCircuitImpl<T> setStepUpTransformerX(double stepUpTransformerX) {
+ this.stepUpTransformerX = stepUpTransformerX;
+ return this;
+ }
+}