Merge branch 'main' into hvdc_ac_emulation_outerloop

Signed-off-by: Sylvestre Prabakaran <sylvestre.prabakaran@rte-france.com>

Author: SylvestreSakti

docs/loadflow/loadflow.md

@@ -3,7 +3,7 @@
 ## Grid modeling
 
 Open Load Flow computes power flows from IIDM grid model in bus/view topology. From the view, a very simple network, composed
-of only buses and branches is created. In the graph vision, we rely on a $\Pi$ model for branches (lines, transformers, dangling lines, etc.):
+of only buses and branches is created. In the graph vision, we rely on a $\Pi$ model for branches (lines, transformers, boundary lines, etc.):
 
 - $R$ and $X$ are respectively the real part (resistance) and the imaginary part (reactance) of the complex impedance ;  
 - $G_1$ and $G_2$ are the real parts (conductance) on respectively side 1 and side 2 of the branch ;
@@ -21,6 +21,15 @@ equal to zero and $1$. In case of a branch with voltage or phase control, the $\
 
 Open Load Flow also supports networks with HVDC lines (High Voltage Direct Current lines). An HVDC line is connected to the rest of the AC network through HVDC converter stations, that can be either LCC (Line-Commutated Converter) or VSC (Voltage-Source Converter).
 
+### DC detailed model
+
+Additionally, Open Load Flow supports AC-DC load flow formulation with detailed model of DC elements.  
+However, it is currently restricted to embedded DC components, meaning that all converters of a given DC component must be connected to the same synchronous component. 
+In other words, a DC component cannot be used to connect two different synchronous components. Consequently, a single connected component should only contain one synchronous component.
+However, the number of DC components within a connected component is not restricted.  
+Yet, it is possible to run a load flow on a network with several synchronous components (with their own embedded DC components) as long
+as they do not belong to the same connected component.
+
 (ac-flow-computing)=
 ## AC flows computing
 
@@ -265,9 +274,9 @@ In such cases the involved areas are not considered in the Area Interchange Cont
 
 In iIDM each area defines the boundary points to be considered in the interchange. iIDM supports two ways of modeling area boundaries:
 - either via an equipment terminal,
-- or via a DanglingLine boundary.
+- or via a BoundaryLine boundary.
 
-In the DanglingLine case, the flow at the boundary side is considered as it should be, for both unpaired DanglingLines and DanglingLines paired in a TieLine.
+In the BoundaryLine case, the flow at the boundary side is considered as it should be, for both unpaired BoundaryLines and BoundaryLines paired in a TieLine.
 
 ### Slack bus mismatch attribution
 Depending on the location of the slack bus(es), the role of distributing the active power mismatch will be attributed based on the following logic:
@@ -331,4 +340,124 @@ Users should notice that default parameters are optimized for the Newton-Raphson
 When the Fast-Decoupled algorithm is used, we recommend these values for some convergence parameters:
 - [`maxNewtonRaphsonIterations`](parameters.md): 75,
 - [`lineSearchStateVectorScalingMaxIteration`](parameters.md): 4,
-- [`lineSearchStateVectorScalingStepFold`](parameters.md): `3/2 = 1.5`.
+- [`lineSearchStateVectorScalingStepFold`](parameters.md): `3/2 = 1.5`.
+
+## AC DC flows computing
+
+AC DC flows computing in OpenLoadFLow is similar to AC flows computing, but with AC and DC equations in the same system.
+The unknowns are voltage magnitude and phase angle for each AC bus, voltage for each DC bus, and active/reactive 
+power for each voltage source converter.   
+Concerning AC side, the equations are the same as in AC flows computing, concerning DC side, the equations induced by DC
+components are the followings:
+
+### DC bus
+
+At least one DC bus must be connected to the ground in each DC network, its potential is therefore set to 0. 
+Therefore, symmetrical configuration are currently not supported.  
+For the others DC buses, each one introduces an equation of current balance: $\sum_{i} I_i = 0$ where $I_i$ are the currents going out of the DC bus.
+These terms are introduced by the DC components connected to the DC bus.
+
+### DC Line
+
+Each DC line adds one term in both of its two connected DC buses current balance:
+
+$\sum_{i} I_i + \frac{V_1 - V_2}{R}= 0$ for dcBus1
+
+$\sum_{i} I_i - \frac{V_1 - V_2}{R}= 0$ for dcBus2
+
+
+### Line Commutated Converter
+
+Line commutated converters are not supported yet by Open Load Flow.
+
+### Voltage source converters
+
+Let consider a network that is composed of one AC network, and one DC network.
+The voltage source converter is the link between AC and DC networks, it is linked to **one** AC bus at one side, and two 
+DC buses at the other side.   
+Please note that converters with a second optional AC terminal are not supported by Open Load Flow.
+
+The converter can control either the power received by the AC network (`P_PCC` control mode) 
+or the voltage between its two DC buses (`V_DC` control mode).
+At least one of the voltage source converters of the DC network must be in `V_DC` mode. Otherwise, an exception will be thrown.
+
+In addition to the control modes `P_PCC` and `V_DC`, the voltage source converter can be set in two modes :
+- Reactive power control mode, in which it imposes the reactive power received from AC to DC, which is 0 by default.
+  In this case, the AC voltage is not fixed.
+- Voltage regulator control mode, in which it imposes the voltage at its AC Bus. In this case the reactive power is not
+  fixed.
+
+**Warning:** At the moment, the active and reactive power control and the AC voltage control are enforced at the converter AC terminal, not at its PCC terminal.
+
+We note $P_{AC}$ the power flow injected by AC network into the converter. 
+So $P_{AC}>0$ if the power flows from AC to DC and $P_{AC}<0$ otherwise.
+
+If the converter is in `P_PCC` control mode, we add an equation to impose $P_{AC}$ :
+
+$P_{AC}$ = $P_{Ref}$
+
+Else the converter is in `V_DC` control mode, and we add an equation to impose the voltage between its two DC buses :
+
+$V_{1} - V_{2} = V_{Ref}$
+
+Similarly, if the converter controls reactive power, we add an equation to impose $Q_{AC}$ :
+
+$Q_{AC}$ = $Q_{Ref}$
+
+Else the converter controls the AC voltage, and we add an equation to impose $V_{AC}$:
+
+$V_{AC}= V_{Ref}$
+
+On the AC bus, the active and reactive power injected into the converter is added to its power balance.  
+On the DC side, we introduce the variable $I_{Conv}$ which is the current flowing in the converter from dcBus1 to dcBus2.
+It is added to the current balances of dcBus1 and dcBus2
+
+$\sum_{i} I_i + I_{Conv} = 0$ for dcBus1
+
+$\sum_{i} I_i - I_{Conv}= 0$ for dcBus2
+
+#### Power Equations
+
+The last equation of converters ensures the conservation of power between AC and DC.
+
+$$P_{DC} + P_{AC} = P_{Loss}$$
+
+with:
+- $P_{AC}$ the power injected by the AC network into the converter
+- $P_{Loss}>=0$ the converter losses depending on AC current. Its computation is detailed below.
+- $P_{DC} = I_{Conv}*(V_1-V_2)$ the power injected by the DC network into the converter.
+
+If the converter acts as rectifier, AC injects power in DC, thus $P_{DC}<0$ and $P_{AC}>0$, so we have :
+
+$$
+-|P_{DC}| + P_{AC} = P_{Loss}
+$$
+$$
+|P_{DC}| = |P_{AC}| - P_{Loss}
+$$
+
+And if the converter acts as inverter, DC injects power in AC, thus $P_{DC}>0$ and $P_{AC}<0$, so we have :
+
+$$
+P_{DC} - |P_{AC}| = P_{Loss}
+$$
+$$
+|P_{AC}| = |P_{DC}| - P_{Loss}
+$$
+
+In both cases, there is a loss of power when passing through the converter.
+
+
+$P_{Loss}$ is defined as :  
+$
+P_{Loss} = IdleLoss + SwitchingLoss * |I_{Conv}| + ResistiveLoss * I_{Conv}^{2}
+$
+
+
+Idle loss, switching loss and resistive loss are loss factors that depend on the converter.
+
+Using the previous equation of power conservation between AC and DC, we have
+$$
+I_{Conv}*(V_1-V_2) + P_{AC} = IdleLoss + SwitchingLoss*|I_{Conv}| + ResistiveLoss*I_{Conv}^{2}
+$$
+

docs/loadflow/parameters.md

@@ -378,16 +378,22 @@ and 100 kV for **minNominalVoltageRealisticVoltageCheck**.
 The default value is 0 kV.
 
 **reactiveRangeCheckMode**  
-Open Load Flow discards voltage control for generators with a too small reactive power range, because in practice a too
-small reactive power ranger means limited to zero voltage control capability.
+Open Load Flow discards voltage control for network elements with a too small reactive power range, because in practice a too
+small reactive power ranger means limited to zero voltage control capability. The involved network element types are:
+- Generators
+- Batteries
+- Voltage Source Converters
+- The optional generation part of a Boundary Line
+- Static VAR compensators
 
 For a given active power output, the reactive power range is defined as $MaxQ - MinQ$ (always a positive value).  
-The *maximum* and *minimum* reactive range of a generator is:
-- for generators without reactive limits: infinity 
-- for generators with reactive limits defined by a pair of [min/max values](inv:powsyblcore:*:*:#min-max-reactive-limits), both minimum and maximum reactive range are equal to $MaxQ - MinQ$ 
-- for generators with reactive limits defined by a [reactive capability curve](inv:powsyblcore:*:*:#reactive-capability-curve), the minimum (resp. maximum) reactive range is obtained by finding the curve point having the minimum (resp. maximum) $MaxQ - MinQ$.
+The *maximum* and *minimum* reactive range of a network element is:
+- for network elements without reactive limits: infinity 
+- for network elements with reactive limits defined by a pair of [min/max values](inv:powsyblcore:*:*:#min-max-reactive-limits), both minimum and maximum reactive range are equal to $MaxQ - MinQ$ 
+- for network elements with reactive limits defined by a [reactive capability curve](inv:powsyblcore:*:*:#reactive-capability-curve), the minimum (resp. maximum) reactive range is obtained by finding the curve point having the minimum (resp. maximum) $MaxQ - MinQ$.
+- In the case of Static VAR compensators, the reactive power range is derived from maximum and minimum susceptance assuming nominal voltage: $(B_{\text{max}} - B_{\text{min}}) \cdot \text{nominalV}^2$
 
-The `reactiveRangeCheckMode` parameter defines how generator reactive power range is to be tested. If the test does not pass,
+The `reactiveRangeCheckMode` parameter defines how network elements reactive power range is to be tested. If the test does not pass,
 meaning the reactive power range is too small, then the voltage control is disabled:
 - `MIN_MAX` mode tests if the minimum reactive range is not `0 MVAr` and if the maximum reactive range is above `1 MVAr`.
 - `MAX` mode tests if the maximum reactive range is above `1 MVAr`.
@@ -451,15 +457,15 @@ Above this voltage level, voltage targets that are, in pu, outside 'minPlausible
 The default value is `20 kV`. It must be greater or equal to `0 kV`.
 
 **reactivePowerDispatchMode**  
-This parameter defines how reactive power is split among generators with controls (voltage or reactive power).
-It tries to divide reactive power among generators in the order described below.
+This parameter defines how reactive power is split among network elements with controls (voltage or reactive power).
+It tries to divide reactive power among network elements in the order described below.
 `reactivePowerDispatchMode` can be one of:
 - `Q_EQUAL_PROPORTION`
-    1. If all concerned generators have pre-defined reactive keys via the [Coordinated Reactive Control extension](inv:powsyblcore:*:*:#coordinated-reactive-control-extension), then it splits `Q` proportional to reactive keys
-    2. If they don't, but they have plausible reactive limits, split proportionally to the maximum reactive power range
+    1. If all concerned network elements are generators having pre-defined reactive keys via the [Coordinated Reactive Control extension](inv:powsyblcore:*:*:#coordinated-reactive-control-extension), then it splits `Q` proportional to reactive keys
+    2. If they don't, but they have plausible reactive limits, split proportionally to the maximum reactive power range (see `reactiveRangeCheckMode` parameter for definition)
     3. If they don't, split `Q` equally
 - `K_EQUAL_PROPORTION`
-    1. If generators have plausible reactive limits, split `Q` proportionally to `k`, where `k` is defined by
+    1. If network elements have plausible reactive limits, split `Q` proportionally to `k`, where `k` is defined by
        $ k = \frac{2 qToDispatch - qmax1 - qmin1 - qmax2 - qmin2 - ...}{qmax1 - qmin1 + qmax2 - qmin2 + ...} $
     2. If they don't, split `Q` equally
 
@@ -542,12 +548,12 @@ Works only when `referenceBusSelectionMode` is set to `GENERATOR_REFERENCE_PRIOR
 When multiple equipment regulate the same bus with different voltage targets,
 this parameter enables configuring priority to resolve inconsistencies by aligning the voltage targets.
 Priority is determined by equipment type order; the voltage target of the equipment type listed first takes precedence over those listed later.
-By default, the order is `["GENERATOR", "TRANSFORMER", "SHUNT"]`.  
+By default, the order is `["VOLTAGE_SOURCE_CONVERTER", "GENERATOR", "TRANSFORMER", "SHUNT"]`.  
 Note that `"GENERATOR"` indistinctively includes generators, batteries, static var compensators, and VSC HVDC converters.
 
 If the user specifies only a sub-list of priorities, this sub-list is completed by the
 order defined by default. Thus, if the user specifies only `["TRANSFORMER"]`,
-it will be completed to `["TRANSFORMER", "GENERATOR", "SHUNT"]`.
+it will be completed to `["TRANSFORMER", "VOLTAGE_SOURCE_CONVERTER", "GENERATOR", "SHUNT"]`.
 
 **transformerVoltageControlUseInitialTapPosition**  
 This parameter is only used if the transformer voltage control is enabled and of mode `AFTER_GENERATOR_VOLTAGE_CONTROL`.
@@ -622,6 +628,33 @@ to fix the network data.
 
 The default value is `false`.
 
+**acDcNetwork**
+
+Defines if the loadflow uses DC detailed equipment and computes an AC DC loadflow 
+
+If `true`, the network supports DC detailed equipments, and the loadflow is computed on the whole connected network, 
+AC and DC sides in the same Jacobian matrix. Currently, the network shall contain only one synchronous component, but the number of 
+embedded DC components is not restricted.
+
+If `false`, the loadflow is the classic one, without DC detailed components.
+
+The default value is `false`.
+
+**Note:** With AC-DC network load flow, the following parameters are restricted:
+- Generic parameters
+  - `dc`: must be set to false.
+  - `voltageInitMode` cannot be set to `DC_VALUES`.
+  - `componentMode` cannot be set to `MAIN_SYNCHRONOUS`.
+- Specific parameters
+  - `voltageInitModeOverride` must be set to `NONE`.
+  - `acSolverType` must be set to `NEWTON_RAPHSON`.
+
+Moreover, network with the following characteristics are not supported:
+- A network containing detailed AC/DC converters with two AC terminals
+- A network containing detailed LCC converters
+
+If any of these cases occurs, an exception describing the problem is thrown.
+
 ## Configuration file example
 See below an extract of a config file that could help:
 

docs/sensitivity/getting_started.md

@@ -47,10 +47,10 @@ Here is a table to summarize supported use cases:
 ## Input function types
 
 ### Branch sensitivity functions : 
-BRANCH_ACTIVE_POWER_#, BRANCH_REACTIVE_POWER_# or BRANCH_CURRENT_# are associated to branch objects (lines, transformers, dangling lines, tie lines). The # index corresponding to the side of the studied branch. 
+BRANCH_ACTIVE_POWER_#, BRANCH_REACTIVE_POWER_# or BRANCH_CURRENT_# are associated to branch objects (lines, transformers, boundary lines, tie lines). The # index corresponding to the side of the studied branch. 
 - If it is a line, a tie line, or a two windings transformer : The side is 1 or 2.
 - If it is a three windings transformer : The side is 1, 2 or 3 corresponding to the studied leg of the transformer.
-- If it is a dangling line : The side is 1 (network side) or 2 (boundary side). Note that if the dangling line is paired, only side 1 (network side) can be specified, and the sensitivity function is computed at the corresponding tie line side.
+- If it is a boundary line : The side is 1 (network side) or 2 (boundary side). Note that if the boundary line is paired, only side 1 (network side) can be specified, and the sensitivity function is computed at the corresponding tie line side.
 
 ### Bus sensitivity functions :
 BUS_VOLTAGE or BUS_REACTIVE_POWER are associated to the bus of the given network element.

pom.xml

@@ -53,7 +53,7 @@
         <slf4jtoys.version>1.6.3</slf4jtoys.version>
         <asciitable.version>0.3.2</asciitable.version>
 
-        <powsybl-core.version>7.1.1</powsybl-core.version>
+        <powsybl-core.version>7.2.0-RC1</powsybl-core.version>
 
         <!--  This is required for later correct replacement of argline -->
         <argLine/>

src/main/java/com/powsybl/openloadflow/FullVoltageInitializer.java

@@ -7,9 +7,11 @@
  */
 package com.powsybl.openloadflow;
 
+import com.powsybl.commons.PowsyblException;
 import com.powsybl.openloadflow.ac.VoltageMagnitudeInitializer;
 import com.powsybl.openloadflow.dc.DcValueVoltageInitializer;
 import com.powsybl.openloadflow.network.LfBus;
+import com.powsybl.openloadflow.network.LfDcBus;
 import com.powsybl.openloadflow.network.LfNetwork;
 import com.powsybl.openloadflow.network.util.VoltageInitializer;
 
@@ -47,4 +49,9 @@ public double getMagnitude(LfBus bus) {
     public double getAngle(LfBus bus) {
         return angleInitializer.getAngle(bus);
     }
+
+    @Override
+    public double getMagnitude(LfDcBus dcBus) {
+        throw new PowsyblException("Full voltage initialization is not yet supported with AcDcNetwork");
+    }
 }