Add LineCouplings extension

docs/grid_model/extensions.md

@@ -328,6 +328,44 @@ Side 1 and side 2 correspond respectively to terminal1 and terminal2 of the line
 
 This extension is provided in the `com.powsybl:powsybl-iidm-extensions` module.
 
+(line-couplings-extension)=
+## Line Couplings
+
+This extension models the mutual coupling between two lines. It is attached to the `Network` object and contains a list of mutual couplings.
+
+The attributes of a `MutualCoupling` are:
+
+| Attribute    | Type        | Unit | Required | Default value | Description                                                   |
+|--------------|-------------|------|----------|---------------|---------------------------------------------------------------|
+| line1        | Line        | -    | yes      | -             | The first coupled line                                        |
+| line2        | Line        | -    | yes      | -             | The second coupled line                                       |
+| r            | double      | Ω    | yes      | -             | The mutual coupling resistance                                |
+| x            | double      | Ω    | yes      | -             | The mutual coupling reactance                                 |
+| line1Segment | LineSegment | -    | no       | 0..1          | The starting and ending positions on the first line (0 to 1)  |
+| line2Segment | LineSegment | -    | no       | 0..1          | The starting and ending positions on the second line (0 to 1) |
+
+The position of the mutual coupling is expressed as a ratio between 0 and 1, through a `LineSegment` object.
+A `LineSegment` has a start and an end position, with the constraint that: 0 ≤ start ≤ end ≤ 1
+Mutual coupling is symmetric: a coupling between line1 and line2 is equivalent to a coupling between line2 and line1.
+Mutual couplings are considered symmetric. Therefore, the extension cannot contain both (line1, line2) and (line2, line1).
+
+Example of code to add a mutual coupling:
+
+```java
+Line line1 = network.getLine("L1");
+Line line2 = network.getLine("L2");
+network.newExtension(LineCouplingsAdder.class).add();
+network.getExtension(LineCouplings.class)
+    .newMutualCoupling()
+    .withLine1(line1)
+    .withLine2(line2)
+    .withR(0.1)
+    .withX(0.4)
+    .add();
+```
+
+This extension is provided in the `com.powsybl:powsybl-iidm-extensions` module.
+
 (two-winding-transformer-fortescue)=
 ## Two-winding Transformer Fortescue
 

docs/grid_model/network_subnetwork.md

@@ -40,6 +40,7 @@ In the PowSyBl grid model, the Network contains [substations](#substation), whic
 The `SourceFormat` attribute is a required attribute that indicates the origin of the network model automatically set by the [importers](../grid_exchange_formats/index.md). If the case date and the forecast distance cannot be found in the case file, the network is considered as a snapshot: the case date is set to the current date, and the forecast distance is set to `0`.
 
 **Available extensions**
+- [Line Couplings](extensions.md#line-couplings)
 
 (substation)=
 ## Substation

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

@@ -0,0 +1,75 @@
+/**
+ * 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.iidm.network.extensions;
+
+import com.powsybl.commons.PowsyblException;
+import com.powsybl.commons.extensions.Extension;
+import com.powsybl.iidm.network.Line;
+import com.powsybl.iidm.network.Network;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * This extension stores the mutual couplings on the network.
+ *
+ * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
+ */
+public interface LineCouplings extends Extension<Network> {
+
+    String NAME = "lineCouplings";
+
+    @Override
+    default String getName() {
+        return NAME;
+    }
+
+    /**
+     * Gets all mutual couplings in the network.
+     * @return a list of mutual couplings
+     */
+    List<MutualCoupling> getMutualCouplings();
+
+    /**
+     * Adds a mutual coupling.
+     * @param mutualCoupling the mutual coupling to add
+     * @return the current line couplings extension
+     * @throws PowsyblException if the coupling is invalid or already exists
+     */
+    LineCouplings add(MutualCoupling mutualCoupling);
+
+    /**
+     * Creates a new mutual coupling adder.
+     * @return a mutual coupling adder
+     */
+    MutualCouplingAdder newMutualCoupling();
+
+    /**
+     * Finds a mutual coupling between two lines.
+     * The order of the lines does not matter.
+     * @param line1 the first line
+     * @param line2 the second line
+     * @return the mutual coupling if found, or empty if not
+     */
+    Optional<MutualCoupling> findMutualCoupling(Line line1, Line line2);
+
+    /**
+     * Removes a mutual coupling.
+     * @param mutualCoupling the mutual coupling to remove
+     * @return true if the mutual coupling was removed, false otherwise
+     */
+    boolean removeMutualCoupling(MutualCoupling mutualCoupling);
+
+    /**
+     * Removes a mutual coupling between two lines.
+     * @param line1 the first line
+     * @param line2 the second line
+     * @return true if the mutual coupling was removed, false otherwise
+     */
+    boolean removeMutualCoupling(Line line1, Line line2);
+}

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

@@ -0,0 +1,22 @@
+/**
+ * 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.iidm.network.extensions;
+
+import com.powsybl.commons.extensions.ExtensionAdder;
+import com.powsybl.iidm.network.Network;
+
+/**
+ * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
+ */
+public interface LineCouplingsAdder extends ExtensionAdder<Network, LineCouplings> {
+
+    @Override
+    default Class<LineCouplings> getExtensionClass() {
+        return LineCouplings.class;
+    }
+}

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

@@ -0,0 +1,39 @@
+/**
+ * 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.iidm.network.extensions;
+
+import com.powsybl.commons.PowsyblException;
+
+/**
+ * Represents a line segment defined by its start and end positions.
+ * The positions must satisfy the following conditions:
+ * - The start and end positions must be valid double values.
+ * - The start position must be greater than or equal to 0.
+ * - The end position must be less than or equal to 1.
+ * - The start position must be less than or equal to the end position.
+ *
+ * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
+ */
+public record LineSegment(double start, double end) {
+
+    public static final LineSegment FULL_LINE = new LineSegment(0, 1);
+
+    /**
+     * Constructs a LineSegment using the specified start and end positions.
+     * The line segment is valid only if the following conditions are met:
+     * - The start and end positions are valid double values.
+     * - The start position is greater than or equal to 0.
+     * - The end position is less than or equal to 1.
+     * - The start position is less than or equal to the end position.
+     */
+    public LineSegment {
+        if (Double.isNaN(start) || Double.isNaN(end) || start < 0 || end > 1 || start > end) {
+            throw new PowsyblException("Invalid line segment: start: " + start + ", end: " + end + ".");
+        }
+    }
+}

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

@@ -0,0 +1,83 @@
+/**
+ * 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.iidm.network.extensions;
+
+import com.powsybl.iidm.network.Line;
+
+/**
+ * This extension models electrical coupling between pairs of lines.
+ *
+ * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
+ */
+public interface MutualCoupling {
+
+    /**
+     * Gets the first line.
+     * @return the first line
+     */
+    Line getLine1();
+
+    /**
+     * Gets the second line.
+     * @return the second line
+     */
+    Line getLine2();
+
+    /**
+     * Gets the mutual coupling resistance.
+     * @return the resistance in ohms
+     */
+    double getR();
+
+    /**
+     * Sets the mutual coupling resistance.
+     * @param r the resistance in ohms
+     */
+    void setR(double r);
+
+    /**
+     * Gets the mutual coupling reactance.
+     * @return the reactance in ohms
+     */
+    double getX();
+
+    /**
+     * Sets the mutual coupling reactance.
+     * @param x the reactance in ohms
+     */
+    void setX(double x);
+
+    /**
+     * Gets the starting and ending position of the mutual coupling on the first line.
+     * The positions are a proportion of the line length and are between 0 and 1.
+     * @return the starting position
+     */
+    LineSegment getLine1Segment();
+
+    /**
+     * Gets the starting and ending position of the mutual coupling on the second line.
+     * The positions are a proportion of the line length and are between 0 and 1.
+     * @return the starting position
+     */
+    LineSegment getLine2Segment();
+
+    /**
+     * Sets the starting and ending position of the mutual coupling on the second line.
+     * The positions are a proportion of the line length and are between 0 and 1.
+     * @param line1Segment the segment on line 1
+     */
+    void setLine1Segment(LineSegment line1Segment);
+
+    /**
+     * Sets the starting and ending position of the mutual coupling on the second line.
+     * The positions are a proportion of the line length and are between 0 and 1.
+     * @param line2Segment the segment on line 2
+     */
+    void setLine2Segment(LineSegment line2Segment);
+
+}

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

@@ -0,0 +1,68 @@
+/**
+ * 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.iidm.network.extensions;
+
+import com.powsybl.iidm.network.Line;
+
+/**
+ * This interface is a builder to add a mutual coupling between two lines.
+ *
+ * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
+ */
+public interface MutualCouplingAdder {
+
+    /**
+     * Sets the first line.
+     * @param line1 the first line
+     * @return the current mutual coupling adder
+     */
+    MutualCouplingAdder withLine1(Line line1);
+
+    /**
+     * Sets the second line.
+     * @param line2 the second line
+     * @return the current mutual coupling adder
+     */
+    MutualCouplingAdder withLine2(Line line2);
+
+    /**
+     * Sets the mutual coupling resistance.
+     * @param r the resistance in ohms
+     * @return the current mutual coupling adder
+     */
+    MutualCouplingAdder withR(double r);
+
+    /**
+     * Sets the mutual coupling reactance.
+     * @param x the reactance in ohms
+     * @return the current mutual coupling adder
+     */
+    MutualCouplingAdder withX(double x);
+
+    /**
+     * Sets the position of the mutual coupling on the first line.
+     * The positions are a proportion of the line length and are between 0 and 1.
+     * @param segment the segment of the line
+     * @return the current mutual coupling adder
+     */
+    MutualCouplingAdder withLine1Segment(LineSegment segment);
+
+    /**
+     * Sets the position of the mutual coupling on the second line.
+     * The positions are a proportion of the line length and are between 0 and 1.
+     * @param segment the segment of the line
+     * @return the current mutual coupling adder
+     */
+    MutualCouplingAdder withLine2Segment(LineSegment segment);
+
+    /**
+     * Adds the mutual coupling.
+     * @return the added mutual coupling
+     */
+    MutualCoupling add();
+}

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

@@ -0,0 +1,28 @@
+/**
+ * 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.iidm.network.impl.extensions;
+
+import com.powsybl.commons.extensions.AbstractExtensionAdder;
+import com.powsybl.iidm.network.Network;
+import com.powsybl.iidm.network.extensions.LineCouplingsAdder;
+import com.powsybl.iidm.network.extensions.LineCouplings;
+
+/**
+ * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
+ */
+public class LineCouplingsAdderImpl extends AbstractExtensionAdder<Network, LineCouplings> implements LineCouplingsAdder {
+
+    public LineCouplingsAdderImpl(Network network) {
+        super(network);
+    }
+
+    @Override
+    protected LineCouplingsImpl createExtension(Network network) {
+        return new LineCouplingsImpl();
+    }
+}