Add magnetizing reactance support to TwoWindingsTransformerFortescue

docs/grid_model/extensions.md

@@ -319,7 +319,8 @@ This extension models the homopolar two-winding transformer data to be used for
 |-----------------|-----------------------|------|----------|----------------------------------|--------------------------------------------------------------------------------------------------------|
 | rz              | double                | Ω    | no       | -                                | The zero-sequence resistance of the two-winding transformer                                            |
 | xz              | double                | Ω    | no       | -                                | The zero-sequence reactance of the two-winding transformer                                             |
-| freeFluxes      | boolean               | -    | no       | true                             | If set to true, then the magnetizing impedance is considered as infinite                               | 
+| freeFluxes      | boolean               | -    | no       | true                             | If set to true, then the magnetizing impedance is considered as infinite                               |
+| xm              | double                | Ω    | no       | Double.NaN                       | If the fluxes are not free, the magnetizing impedance of the two-winding transformer                   |
 | connectionType1 | WindingConnectionType | -    | no       | WindingConnectionType.DELTA      | The connection type of the winding 1                                                                   | 
 | connectionType2 | WindingConnectionType | -    | no       | WindingConnectionType.Y_GROUNDED | The connection type of the winding 2                                                                   | 
 | groundingR1     | double                | Ω    | no       | 0                                | If the winding on side 1 is connected to the earth, the resistance part of the impedance to the ground | 

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

@@ -44,6 +44,13 @@ default String getName() {
 
     void setFreeFluxes(boolean freeFluxes);
 
+    /**
+     * The magnetizing reactance of the two-winding transformer, if not considered as infinite.
+     */
+    double getXm();
+
+    void setXm(double xm);
+
     /**
      * Get the winding connection type of transformer side 1, see {@link WindingConnectionType}).
      */

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

@@ -22,6 +22,8 @@ public interface TwoWindingsTransformerFortescueAdder extends ExtensionAdder<Two
 
     TwoWindingsTransformerFortescueAdder withFreeFluxes(boolean freeFluxes);
 
+    TwoWindingsTransformerFortescueAdder withXm(double xm);
+
     TwoWindingsTransformerFortescueAdder withConnectionType1(WindingConnectionType connectionType1);
 
     TwoWindingsTransformerFortescueAdder withConnectionType2(WindingConnectionType connectionType2);

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

@@ -26,6 +26,7 @@ public class TwoWindingsTransformerFortescueAdderImpl extends AbstractExtensionA
     private double rz = Double.NaN;
     private double xz = Double.NaN;
     private boolean freeFluxes = DEFAULT_FREE_FLUXES;
+    private double xm = Double.NaN;
     private WindingConnectionType connectionType1 = DEFAULT_LEG1_CONNECTION_TYPE;
     private WindingConnectionType connectionType2 = DEFAULT_LEG2_CONNECTION_TYPE;
     private double groundingR1 = DEFAULT_GROUNDING_R;
@@ -44,7 +45,7 @@ public Class<? super TwoWindingsTransformerFortescue> getExtensionClass() {
 
     @Override
     protected TwoWindingsTransformerFortescueImpl createExtension(TwoWindingsTransformer twt) {
-        return new TwoWindingsTransformerFortescueImpl(twt, rz, xz, freeFluxes, connectionType1, connectionType2, groundingR1, groundingX1, groundingR2, groundingX2);
+        return new TwoWindingsTransformerFortescueImpl(twt, rz, xz, freeFluxes, xm, connectionType1, connectionType2, groundingR1, groundingX1, groundingR2, groundingX2);
     }
 
     @Override
@@ -65,6 +66,12 @@ public TwoWindingsTransformerFortescueAdderImpl withFreeFluxes(boolean freeFluxe
         return this;
     }
 
+    @Override
+    public TwoWindingsTransformerFortescueAdderImpl withXm(double xm) {
+        this.xm = xm;
+        return this;
+    }
+
     @Override
     public TwoWindingsTransformerFortescueAdderImpl withConnectionType1(WindingConnectionType connectionType1) {
         this.connectionType1 = Objects.requireNonNull(connectionType1);

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

@@ -23,20 +23,22 @@ public class TwoWindingsTransformerFortescueImpl extends AbstractExtension<TwoWi
     private double rz;
     private double xz;
     private boolean freeFluxes;
+    private double xm;
     private WindingConnectionType connectionType1;
     private WindingConnectionType connectionType2;
     private double groundingR1;
     private double groundingX1;
     private double groundingR2;
     private double groundingX2;
 
-    public TwoWindingsTransformerFortescueImpl(TwoWindingsTransformer twt, double rz, double xz, boolean freeFluxes,
+    public TwoWindingsTransformerFortescueImpl(TwoWindingsTransformer twt, double rz, double xz, boolean freeFluxes, double xm,
                                                WindingConnectionType connectionType1, WindingConnectionType connectionType2,
                                                double groundingR1, double groundingX1, double groundingR2, double groundingX2) {
         super(twt);
         this.rz = rz;
         this.xz = xz;
         this.freeFluxes = freeFluxes;
+        this.xm = xm;
         this.connectionType1 = Objects.requireNonNull(connectionType1);
         this.connectionType2 = Objects.requireNonNull(connectionType2);
         this.groundingR1 = groundingR1;
@@ -70,6 +72,16 @@ public boolean isFreeFluxes() {
         return freeFluxes;
     }
 
+    @Override
+    public double getXm() {
+        return xm;
+    }
+
+    @Override
+    public void setXm(double xm) {
+        this.xm = xm;
+    }
+
     @Override
     public void setFreeFluxes(boolean freeFluxes) {
         this.freeFluxes = freeFluxes;

iidm/iidm-serde/src/main/java/com/powsybl/iidm/serde/extensions/TwoWindingsTransformerFortescueSerDe.java

@@ -8,32 +8,53 @@
 package com.powsybl.iidm.serde.extensions;
 
 import com.google.auto.service.AutoService;
-import com.powsybl.commons.extensions.AbstractExtensionSerDe;
 import com.powsybl.commons.extensions.ExtensionSerDe;
 import com.powsybl.commons.io.DeserializerContext;
 import com.powsybl.commons.io.SerializerContext;
 import com.powsybl.iidm.network.TwoWindingsTransformer;
 import com.powsybl.iidm.network.extensions.TwoWindingsTransformerFortescue;
 import com.powsybl.iidm.network.extensions.TwoWindingsTransformerFortescueAdder;
 import com.powsybl.iidm.network.extensions.WindingConnectionType;
+import com.powsybl.iidm.serde.IidmVersion;
 
 /**
  * @author Geoffroy Jamgotchian {@literal <geoffroy.jamgotchian at rte-france.com>}
  */
 @AutoService(ExtensionSerDe.class)
-public class TwoWindingsTransformerFortescueSerDe extends AbstractExtensionSerDe<TwoWindingsTransformer, TwoWindingsTransformerFortescue> {
+public class TwoWindingsTransformerFortescueSerDe extends AbstractVersionableNetworkExtensionSerDe<TwoWindingsTransformer, TwoWindingsTransformerFortescue, TwoWindingsTransformerFortescueSerDe.Version> {
+
+    public enum Version implements SerDeVersion<Version> {
+        V_1_0("/xsd/twoWindingsTransformerFortescue_V1_0.xsd", "http://www.powsybl.org/schema/iidm/ext/two_windings_transformer_fortescue/1_0",
+            new VersionNumbers(1, 0), IidmVersion.V_1_0, IidmVersion.V_1_16),
+        V_1_1("/xsd/twoWindingsTransformerFortescue_V1_1.xsd", "http://www.powsybl.org/schema/iidm/ext/two_windings_transformer_fortescue/1_1",
+            new VersionNumbers(1, 1), IidmVersion.V_1_0, null);
+
+        private final VersionInfo versionInfo;
+
+        Version(String xsdResourcePath, String namespaceUri, VersionNumbers versionNumbers, IidmVersion minIidmVersionIncluded, IidmVersion maxIidmVersionExcluded) {
+            this.versionInfo = new VersionInfo(xsdResourcePath, namespaceUri, "t2f", versionNumbers,
+                minIidmVersionIncluded, maxIidmVersionExcluded, TwoWindingsTransformerFortescue.NAME);
+        }
+
+        @Override
+        public VersionInfo getVersionInfo() {
+            return versionInfo;
+        }
+    }
 
     public TwoWindingsTransformerFortescueSerDe() {
-        super("twoWindingsTransformerFortescue", "network", TwoWindingsTransformerFortescue.class,
-                "twoWindingsTransformerFortescue_V1_0.xsd", "http://www.powsybl.org/schema/iidm/ext/two_windings_transformer_fortescue/1_0",
-                "t2f");
+        super(TwoWindingsTransformerFortescue.NAME, TwoWindingsTransformerFortescue.class, Version.values());
     }
 
     @Override
     public void write(TwoWindingsTransformerFortescue twtFortescue, SerializerContext context) {
         context.getWriter().writeDoubleAttribute("rz", twtFortescue.getRz(), Double.NaN);
         context.getWriter().writeDoubleAttribute("xz", twtFortescue.getXz(), Double.NaN);
         context.getWriter().writeBooleanAttribute("freeFluxes", twtFortescue.isFreeFluxes());
+        Version extVersion = getExtensionVersionToExport(context);
+        if (extVersion.isGreaterThan(Version.V_1_0)) {
+            context.getWriter().writeDoubleAttribute("xm", twtFortescue.getXm(), Double.NaN);
+        }
         context.getWriter().writeEnumAttribute("connectionType1", twtFortescue.getConnectionType1());
         context.getWriter().writeEnumAttribute("connectionType2", twtFortescue.getConnectionType2());
         context.getWriter().writeDoubleAttribute("groundingR1", twtFortescue.getGroundingR1(), 0);
@@ -47,6 +68,11 @@ public TwoWindingsTransformerFortescue read(TwoWindingsTransformer twt, Deserial
         double rz = context.getReader().readDoubleAttribute("rz");
         double xz = context.getReader().readDoubleAttribute("xz");
         boolean freeFluxes = context.getReader().readBooleanAttribute("freeFluxes");
+        double xm = Double.NaN;
+        Version extVersion = getExtensionVersionImported(context);
+        if (extVersion.isGreaterThan(Version.V_1_0)) {
+            xm = context.getReader().readDoubleAttribute("xm");
+        }
         WindingConnectionType connectionType1 = context.getReader().readEnumAttribute("connectionType1", WindingConnectionType.class);
         WindingConnectionType connectionType2 = context.getReader().readEnumAttribute("connectionType2", WindingConnectionType.class);
         double groundingR1 = context.getReader().readDoubleAttribute("groundingR1", 0);
@@ -58,6 +84,7 @@ public TwoWindingsTransformerFortescue read(TwoWindingsTransformer twt, Deserial
                 .withRz(rz)
                 .withXz(xz)
                 .withFreeFluxes(freeFluxes)
+                .withXm(xm)
                 .withConnectionType1(connectionType1)
                 .withConnectionType2(connectionType2)
                 .withGroundingR1(groundingR1)

iidm/iidm-serde/src/main/resources/xsd/twoWindingsTransformerFortescue_V1_1.xsd

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    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
+
+-->
+<xs:schema version="1.0"
+           xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           xmlns:t2f="http://www.powsybl.org/schema/iidm/ext/two_windings_transformer_fortescue/1_1"
+           targetNamespace="http://www.powsybl.org/schema/iidm/ext/two_windings_transformer_fortescue/1_1"
+           elementFormDefault="qualified">
+    <xs:simpleType name="WindingConnectionType">
+        <xs:restriction base="xs:string">
+            <xs:enumeration value="Y"/>
+            <xs:enumeration value="Y_GROUNDED"/>
+            <xs:enumeration value="DELTA"/>
+        </xs:restriction>
+    </xs:simpleType>
+    <xs:element name="twoWindingsTransformerFortescue">
+        <xs:complexType>
+            <xs:attribute name="rz" type="xs:double"/>
+            <xs:attribute name="xz" type="xs:double"/>
+            <xs:attribute name="freeFluxes" use="required" type="xs:boolean"/>
+            <xs:attribute name="xm" type="xs:double"/>
+            <xs:attribute name="connectionType1" use="required" type="t2f:WindingConnectionType"/>
+            <xs:attribute name="connectionType2" use="required" type="t2f:WindingConnectionType"/>
+            <xs:attribute name="groundingR1" type="xs:double"/>
+            <xs:attribute name="groundingX1" type="xs:double"/>
+            <xs:attribute name="groundingR2" type="xs:double"/>
+            <xs:attribute name="groundingX2" type="xs:double"/>
+        </xs:complexType>
+    </xs:element>
+</xs:schema>

iidm/iidm-serde/src/test/java/com/powsybl/iidm/serde/extensions/TwoWindingsTransformerFortescueXmlSerDeTest.java

@@ -14,12 +14,17 @@
 import com.powsybl.iidm.network.extensions.WindingConnectionType;
 import com.powsybl.iidm.network.test.EurostagTutorialExample1Factory;
 import com.powsybl.iidm.serde.AbstractIidmSerDeTest;
+import com.powsybl.iidm.serde.ExportOptions;
+import com.powsybl.iidm.serde.IidmVersion;
 import org.junit.jupiter.api.Test;
 
 import java.io.IOException;
 import java.time.ZonedDateTime;
 
-import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 /**
  * @author Geoffroy Jamgotchian {@literal <geoffroy.jamgotchian at rte-france.com>}
@@ -61,4 +66,67 @@ void testXmlSerializer() throws IOException {
         assertEquals(fortescue.getGroundingR2(), fortescue2.getGroundingR2(), 0);
         assertEquals(fortescue.getGroundingX2(), fortescue2.getGroundingX2(), 0);
     }
+
+    @Test
+    void testXmlSerializerWithMagnetizingReactance() throws IOException {
+        Network network = EurostagTutorialExample1Factory.create();
+        network.setCaseDate(ZonedDateTime.parse("2016-12-07T11:18:52.881+01:00"));
+        var twt = network.getTwoWindingsTransformer("NGEN_NHV1");
+        assertNotNull(twt);
+        TwoWindingsTransformerFortescue fortescue = twt.newExtension(TwoWindingsTransformerFortescueAdder.class)
+            .withRz(0.1d)
+            .withXz(2d)
+            .withFreeFluxes(false)
+            .withXm(0.5d)
+            .withConnectionType1(WindingConnectionType.Y_GROUNDED)
+            .withConnectionType2(WindingConnectionType.DELTA)
+            .withGroundingR1(0.02d)
+            .withGroundingX1(0.3d)
+            .withGroundingR2(0.04d)
+            .withGroundingX2(0.95d)
+            .add();
+
+        Network network2 = allFormatsRoundTripTest(network, "/fortescue/twoWindingsTransformerFortescueWithMagnetizingReactanceRef.xml");
+
+        TwoWindingsTransformer twt2 = network2.getTwoWindingsTransformer("NGEN_NHV1");
+        assertNotNull(twt2);
+        TwoWindingsTransformerFortescue fortescue2 = twt2.getExtension(TwoWindingsTransformerFortescue.class);
+        assertNotNull(fortescue2);
+
+        assertEquals(fortescue.isFreeFluxes(), fortescue2.isFreeFluxes());
+        assertEquals(fortescue.getXm(), fortescue2.getXm());
+    }
+
+    @Test
+    void testV10() throws IOException {
+        Network network = EurostagTutorialExample1Factory.create();
+        network.setCaseDate(ZonedDateTime.parse("2016-12-07T11:18:52.881+01:00"));
+        var twt = network.getTwoWindingsTransformer("NGEN_NHV1");
+        assertNotNull(twt);
+        TwoWindingsTransformerFortescue fortescue = twt.newExtension(TwoWindingsTransformerFortescueAdder.class)
+            .withRz(0.1d)
+            .withXz(2d)
+            .withFreeFluxes(false)
+            .withXm(0.5d)
+            .withConnectionType1(WindingConnectionType.Y_GROUNDED)
+            .withConnectionType2(WindingConnectionType.DELTA)
+            .withGroundingR1(0.02d)
+            .withGroundingX1(0.3d)
+            .withGroundingR2(0.04d)
+            .withGroundingX2(0.95d)
+            .add();
+
+        Network network2 = allFormatsRoundTripTest(network, "/fortescue/twoWindingsTransformerFortescueRef_V1_0.xml",
+            new ExportOptions()
+                .addExtensionVersion(TwoWindingsTransformerFortescue.NAME, "1.0")
+                .setVersion(IidmVersion.V_1_15.toString(".")));
+
+        TwoWindingsTransformer twt2 = network2.getTwoWindingsTransformer("NGEN_NHV1");
+        assertNotNull(twt2);
+        TwoWindingsTransformerFortescue fortescue2 = twt2.getExtension(TwoWindingsTransformerFortescue.class);
+        assertNotNull(fortescue2);
+
+        assertEquals(fortescue.isFreeFluxes(), fortescue2.isFreeFluxes());
+        assertTrue(Double.isNaN(fortescue2.getXm()));
+    }
 }

iidm/iidm-serde/src/test/resources/V1_16/europeanLvTestFeederRef.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_16" xmlns:lf="http://www.powsybl.org/schema/iidm/ext/line_fortescue/1_0" xmlns:las="http://www.powsybl.org/schema/iidm/ext/load_asymmetrical/1_0" xmlns:gf="http://www.powsybl.org/schema/iidm/ext/generator_fortescue/1_0" xmlns:slt="http://www.powsybl.org/schema/iidm/ext/slack_terminal/1_5" xmlns:t2f="http://www.powsybl.org/schema/iidm/ext/two_windings_transformer_fortescue/1_0" id="EuropeanLvTestFeeder" caseDate="2023-04-11T23:59:00.000+01:00" forecastDistance="0" sourceFormat="csv" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
+<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_16" xmlns:lf="http://www.powsybl.org/schema/iidm/ext/line_fortescue/1_0" xmlns:las="http://www.powsybl.org/schema/iidm/ext/load_asymmetrical/1_0" xmlns:gf="http://www.powsybl.org/schema/iidm/ext/generator_fortescue/1_0" xmlns:slt="http://www.powsybl.org/schema/iidm/ext/slack_terminal/1_5" xmlns:t2f="http://www.powsybl.org/schema/iidm/ext/two_windings_transformer_fortescue/1_1" id="EuropeanLvTestFeeder" caseDate="2023-04-11T23:59:00.000+01:00" forecastDistance="0" sourceFormat="csv" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
     <iidm:substation id="Substation-1">
         <iidm:voltageLevel id="SourceVoltageLevel" nominalV="11.0" topologyKind="BUS_BREAKER">
             <iidm:busBreakerTopology>

iidm/iidm-serde/src/test/resources/fortescue/twoWindingsTransformerFortescueRef.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_16" xmlns:t2f="http://www.powsybl.org/schema/iidm/ext/two_windings_transformer_fortescue/1_0" id="sim1" caseDate="2016-12-07T11:18:52.881+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
+<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_16" xmlns:t2f="http://www.powsybl.org/schema/iidm/ext/two_windings_transformer_fortescue/1_1" id="sim1" caseDate="2016-12-07T11:18:52.881+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
     <iidm:substation id="P1" country="FR" tso="RTE" geographicalTags="A">
         <iidm:voltageLevel id="VLGEN" nominalV="24.0" topologyKind="BUS_BREAKER">
             <iidm:busBreakerTopology>