Equation model vectorization #1275

geofjamg · 2025-09-02T07:23:55Z

Please check if the PR fulfills these requirements

The commit message follows our guidelines
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)
A PR or issue has been opened in all impacted repositories (if any)

Does this PR already have an issue describing the problem?

No

What kind of change does this PR introduce?

Feature

What is the current behavior ?

Each equation is stored separately (in Equation objects) with its specific EquationTerm. Data (V, phi, Pi model characteristics...) is stored directly in the EquationTermobjects and the term is evaluated through eval() and der() implementations.

Figure 1 : Simplified view of an equation system implemented with the old behaviour

What is the new behavior (if this is a feature change)?

In addition to existing scalar equation model, we added an array equation model that allow a more compact model and improve evaluation of equations and its derivatives. For closed branch terms, for bus active target and bus reactive target equations, the vectorized view is implemented. All equations of the same type are stored in one unique EquationArray object that contains one unique EquationTermArray for each type of terms. Data (V, phi, Pi model characteristics...) is stored in an AcNetworkVector object, and all terms are evaluated once with the eval() and der() methods of the EquationTermArray.
Previous single equations still remain for other types (Equation are renamed SingleEquation and EquationTerm are renamed SingleEquationTerm). EquationArray can also include specif SingleEquationTerm objects for specific equations (e.g. open branch terms or AC emulation)

Figure 2 : Simplified view of the same equation system implemented with the new behaviour

Does this PR introduce a breaking change or deprecate an API?

Yes
No

If yes, please check if the following requirements are fulfilled

The Breaking Change or Deprecated label has been added
The migration steps are described in the following section

What changes might users need to make in their application due to this PR? (migration steps)

Other information:

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

# Conflicts: # src/main/java/com/powsybl/openloadflow/ac/equations/AcEquationSystemCreator.java

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

…rk_vector

# Conflicts: # src/main/java/com/powsybl/openloadflow/network/LfNetwork.java

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

# Conflicts: # src/main/java/com/powsybl/openloadflow/ac/equations/AcEquationSystemCreator.java # src/main/java/com/powsybl/openloadflow/ac/equations/asym/AsymmetricalAcEquationSystemCreator.java

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

# Conflicts: # src/main/java/com/powsybl/openloadflow/ac/equations/AcEquationSystemCreator.java

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

# Conflicts: # src/main/java/com/powsybl/openloadflow/ac/AcLoadFlowParameters.java # src/test/java/com/powsybl/openloadflow/OpenLoadFlowProviderTest.java

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

src/main/java/com/powsybl/openloadflow/equations/SingleEquation.java

src/test/java/com/powsybl/openloadflow/equations/EquationArrayTest.java

src/main/java/com/powsybl/openloadflow/network/LfShunt.java

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

src/main/java/com/powsybl/openloadflow/equations/Variable.java

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

vidaldid-rte · 2025-11-27T16:40:47Z

src/main/java/com/powsybl/openloadflow/equations/EquationArray.java

+                    singleTermsByEquationElementNum.computeIfAbsent(elementNum, k -> new AdditionalSingleTermsByEquation())
+                            .addSingleTerm(singleEquationTerm, this);
+                    hasSingleEquationTerms[elementNum] = true;
+                }


else throw something ? (to avoid silent errors)

vidaldid-rte · 2025-11-27T16:42:24Z

src/main/java/com/powsybl/openloadflow/ac/equations/ClosedBranchAcFlowEquationTerm.java

+/**
+ * @author Sylvestre Prabakaran {@literal <sylvestre.prabakaran at rte-france.com>}
+ */
+public interface ClosedBranchAcFlowEquationTerm extends EquationTerm<AcVariableType, AcEquationType> {


extends SingleEquationTerm

Is this compulsory ? We could imagine an EquationTermArrayElement (that is not a SingleEquationTerm) that implements this interface

vidaldid-rte · 2025-11-27T17:11:43Z

...loadflow/ac/equations/fastdecoupled/AbstractClosedBranchAcFlowFastDecoupledEquationTerm.java

+    protected final Variable<AcVariableType> v2Var;
+    protected final Variable<AcVariableType> a1Var;
+    protected final Variable<AcVariableType> r1Var;
+


For transformers with tap changers this may become wrong if the tap changes (especially for r1 and a1).
This object works only if its lifecycle is short and it is not used longer than an ACSolver solve.

This is the case since this term is built only during one step of derivative calculation. Comment added to clarify that.

vidaldid-rte · 2025-11-28T15:16:05Z

src/main/java/com/powsybl/openloadflow/equations/EquationVector.java

        Stopwatch stopwatch = Stopwatch.createStarted();

-        var equations = equationSystem.getIndex().getSortedEquationsToSolve();
+        var equations = equationSystem.getIndex().getSortedSingleEquationsToSolve();


This variable is no longer needed .

equationSystem.getIndex().getSortedEquationsToSolve() can be in the loop (after ). Would make the code cleaner and more symetric.:

vidaldid-rte · 2025-11-28T15:19:45Z

src/main/java/com/powsybl/openloadflow/equations/EquationVector.java

+            array[equation.getColumn()] = equation.evalLhs();
+        }
+        for (EquationArray<V, E> equationArray : equationSystem.getEquationArrays()) {
+            equationArray.eval(array);


maybe a simple fix to split in two iterations as discussed
One on the array terms
One on the single terms of equations array that add (their sum) to the array cell (in a way that minimizes the number of small objetc to load - ideally only the active single terms)
So that the flow on array terms remains linear and fast.

To be studied when improving this PR for the next release, but as discussed, it may not be needed since there are only 4 equation arrays.

vidaldid-rte · 2025-11-28T15:32:46Z

src/main/java/com/powsybl/openloadflow/equations/EquationTermArray.java

@@ -0,0 +1,326 @@
+/**
+ * Copyright (c) 2023, RTE (http://www.rte-france.com)


Is 2023 really the latest modification date for this class ? shouldn't if be 2023-2025

vidaldid-rte · 2025-11-28T15:38:42Z

src/main/java/com/powsybl/openloadflow/equations/EquationTerm.java

@@ -1,9 +1,8 @@
 /**
- * Copyright (c) 2019, RTE (http://www.rte-france.com)
+ * Copyright (c) 2025, RTE (http://www.rte-france.com)


Coyright is usually creationYear-lastModificatinYear. Should be 2019-2025

vidaldid-rte · 2025-11-28T15:39:45Z

src/main/java/com/powsybl/openloadflow/equations/EquationTerm.java

 * 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


Why was SPDX removed ?

vidaldid-rte · 2025-11-28T16:24:48Z

src/main/java/com/powsybl/openloadflow/equations/EquationDerivativeElement.java

+ * 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/.
+ */


No SPDX ?
Has the rule changed since this 2024 campaign ? #1019

Signed-off-by: PRABAKARAN Sylvestre <[email protected]>

sonarqubecloud · 2025-12-01T10:37:49Z

Quality Gate passed

Issues
13 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

geofjamg and others added 30 commits July 3, 2023 21:27

Wip

924c075

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Merge branch 'main' into ac_network_vector

00c1e16

Merge branch 'ac_network_vector' into equation_array

3124cec

Wip

61b067c

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Merge branch 'main' into ac_network_vector

8a94343

Merge branch 'ac_network_vector' into equation_array

21f225b

Wip

ee69eb3

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Merge branch 'main' into ac_network_vector

6bb671a

Wip

52e69b4

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Merge branch 'main' into ac_network_vector

3f026a1

Merge branch 'main' into ac_network_vector

e892d15

# Conflicts: # src/main/java/com/powsybl/openloadflow/ac/equations/AcEquationSystemCreator.java

Wip

f95fead

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Merge remote-tracking branch 'origin/ac_network_vector' into ac_netwo…

a99a618

…rk_vector

Merge branch 'ac_network_vector' into equation_array

f9b6376

# Conflicts: # src/main/java/com/powsybl/openloadflow/network/LfNetwork.java

Wip

a526b4a

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Wip

edaa711

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Wip

f11a971

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Wip

13cc74c

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Wip

727b2bd

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Wip

9d94ff0

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Wip

e905fdf

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Wip

212bde9

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Wip

b2b466e

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Merge branch 'main' into ac_network_vector

88ae320

# Conflicts: # src/main/java/com/powsybl/openloadflow/ac/equations/AcEquationSystemCreator.java # src/main/java/com/powsybl/openloadflow/ac/equations/asym/AsymmetricalAcEquationSystemCreator.java

Wip

5e06ec6

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Wip

378b6de

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Wip

8344582

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Wip

6ed47b6

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Merge branch 'main' into ac_network_vector

fbd0b50

# Conflicts: # src/main/java/com/powsybl/openloadflow/ac/equations/AcEquationSystemCreator.java

Wip

88f6e7a

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

SylvestreSakti and others added 12 commits November 25, 2025 17:37

Merge branch 'main' into equation_array

e2af0e0

Fix copyright

7f53c86

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Remove useless changes

9222d46

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Use MutableInt instead of int[]

ea554bf

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Remove useless comparators

052cf5b

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Merge branch 'main' into equation_array

f23cee6

# Conflicts: # src/main/java/com/powsybl/openloadflow/ac/AcLoadFlowParameters.java # src/test/java/com/powsybl/openloadflow/OpenLoadFlowProviderTest.java

Fix merge

925c677

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Clean

fa57903

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Revert in AcEquationSystemCreator

f490524

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Add LfElementContainer

ac33fb5

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Hide compress method

362a87e

Signed-off-by: Geoffroy Jamgotchian <[email protected]>

Clean unused dummy vectors

ee8a8ad

Signed-off-by: Geoffroy Jamgotchian <[email protected]>