Skip to content

Commit

Permalink
To have same behavior than before change on extensions: create defaul…
Browse files Browse the repository at this point in the history
…t values in extension if exist in rao-parameters and vive-versa

Signed-off-by: Pauline Jean-Marie <[email protected]>
  • Loading branch information
Pauline Jean-Marie committed Nov 29, 2024
1 parent 57f28f5 commit b4859b0
Show file tree
Hide file tree
Showing 10 changed files with 142 additions and 85 deletions.
138 changes: 78 additions & 60 deletions docs/parameters.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,68 @@ optimisation of specific CNECs in specific conditions.
This parameter has no effect on the preventive RAO.
This parameter should be set to true for CORE CC.

### Loop-flow optional parameter
Adding a LoopFlowParameters to RaoParameters will activate [loop-flow constraints](/castor/special-features/loop-flows.md).
(The RAO will monitor the loop-flows on CNECs that have a LoopFlowThreshold extension.)
The following parameters tune some of these constraints, the one which are not implementation specific.
See also: [Modelling loop-flows and their virtual cost](/castor/linear-problem/max-loop-flow-filler.md)

#### acceptable-increase
- **Expected value**: numeric values, in MEGAWATT unit
- **Default value**: 0.0 MW
- **Usage**: the increase of the initial loop-flow that is allowed by the optimisation. That is to say, the optimisation
bounds the loop-flow on CNECs by:
*LFcnec ≤ max(MaxLFcnec , InitLFcnec + acceptableAugmentation)*
With *LFcnec* the loop-flow on the CNEC after optimisation, *MaxLFcnec* is the CNEC loop-flow threshold, *InitLFcnec*
the initial loop-flow on the cnec, and *acceptableAugmentation* the so-called "loop-flow-acceptable-augmentation"
coefficient.
If this constraint cannot be respected and the loop-flow exceeds the aforementioned threshold, the objective function
associated to this situation will be penalized (see also [violation-cost](#violation-cost))

#### countries
- **Expected value**: array of country codes "XX"
- **Default value**: all countries encountered
- **Usage**: list of countries for which loop-flows should be limited accordingly to the specified constraints. If not
present, all countries encountered in the input files will be considered. Note that a cross-border line will have its
loop-flows monitored if at least one of its two sides is in a country from this list.
Example of this parameter : [ "BE", "NL" ] if you want to monitor loop-flows in and out of Belgium and the
Netherlands.

### MNEC optional parameter
Adding a MnecParameters to RaoParameters will activate [MNEC constraints](/castor/linear-problem/mnec-filler.md).
(The RAO will only monitor CNECs that are only ["monitored"](/input-data/crac/json.md#cnecs)).
The following parameters tune some of these constraints, the one which are not implementation specific.
See also: [Modelling MNECs and their virtual cost](/castor/linear-problem/mnec-filler.md)

#### acceptable-margin-decrease
- **Expected value**: numeric values, in MEGAWATT unit
- **Default value**: 50 MW (required by CORE CC methodology)
- **Usage**: the decrease of the initial margin that is allowed by the optimisation on MNECs.
In other words, it defines the bounds for the margins on the MNECs by
*Mcnec ≥ max(0, m0cnec − acceptableDiminution)*
With *Mcnec* the margin on the cnec after optimisation, *m0cnec* the initial margin on the cnec, and
*acceptableDiminution* the so-called "acceptable-margin-decrease" coefficient.
For the CORE CC calculation, the ACER methodology fixes this coefficient at 50 MW.
For CSE CC calculation, setting this parameter to -99999 allows the MNEC constraints to consider
the thresholds in the CRAC only.

### Relative margins optioanl parameter
Adding a RelativeMarginsParameters is mandatory when [objective function is relative](#type).
The following parameters tune some constraints, the one which are not implementation specific.
See also: [Modelling the maximum minimum relative margin objective function](/castor/linear-problem/max-min-relative-margin-filler.md)

#### ptdf-boundaries
- **Expected value**: array of zone-to-zone PTDF computation definition, expressed as an equation.
Zones are defined by their 2-character code or their 16-character EICode, inside **{ }** characters.
Zones are seperated by + or -.
All combinations are allowed: country codes, EIC, a mix.
- **Default value**: empty array
- **Usage**: contains the boundaries on which the PTDF absolute sums should be computed (and added to the denominator of
the relative RAM).
For example, in the SWE case, it should be equal to [ "{FR}-{ES}", "{ES}-{PT}" ].
For CORE, we should use all the CORE region boundaries (all countries seperated by a - sign) plus Alegro's special
equation: "{BE}-{22Y201903144---9}-{DE}+{22Y201903145---4}"

## Extensions
The following extensions can be added to RaoParameters:
- to configure implementation specific parameters
Expand Down Expand Up @@ -405,25 +467,13 @@ These parameters (multi-threading) allow you to run a RAO making the most out of
*Note that the more available cpus is configured, the more RAM is required by the RAO, and that the performance
of the RAO might significantly decrease on a machine with limited memory resources.*

### Loop-flow extension
Adding a LoopFlowParameters extension to RaoParameters will activate [loop-flow constraints](/castor/special-features/loop-flows.md).
#### Loop-flow optional parameter
Adding a LoopFlowParameters to OpenRaoSearchTreeParameters will activate [loop-flow constraints](/castor/special-features/loop-flows.md).
(The RAO will monitor the loop-flows on CNECs that have a LoopFlowThreshold extension.)
The following parameters tune these constraints.
The following parameters tune some of these constraints, the one which are implementation specific.
See also: [Modelling loop-flows and their virtual cost](/castor/linear-problem/max-loop-flow-filler.md)

#### acceptable-increase
- **Expected value**: numeric values, in MEGAWATT unit
- **Default value**: 0.0 MW
- **Usage**: the increase of the initial loop-flow that is allowed by the optimisation. That is to say, the optimisation
bounds the loop-flow on CNECs by:
*LFcnec ≤ max(MaxLFcnec , InitLFcnec + acceptableAugmentation)*
With *LFcnec* the loop-flow on the CNEC after optimisation, *MaxLFcnec* is the CNEC loop-flow threshold, *InitLFcnec*
the initial loop-flow on the cnec, and *acceptableAugmentation* the so-called "loop-flow-acceptable-augmentation"
coefficient.
If this constraint cannot be respected and the loop-flow exceeds the aforementioned threshold, the objective function
associated to this situation will be penalized (see also [violation-cost](#violation-cost))

#### ptdf-approximation
##### ptdf-approximation
- **Expected value**: one of the following:
- "FIXED_PTDF"
- "UPDATE_PTDF_WITH_TOPO"
Expand All @@ -439,7 +489,7 @@ See also: [Modelling loop-flows and their virtual cost](/castor/linear-problem/m
each new combination of PST taps (i.e. for each iteration of the linear optimisation).
*Note that this option is only relevant in AC-loadflow mode, as the UPDATE_PTDF_WITH_TOPO already maximizes accuracy in DC.*

#### constraint-adjustment-coefficient
##### constraint-adjustment-coefficient
- **Expected value**: numeric values, in MEGAWATT unit
- **Default value**: 0.0 MW
- **Usage**: this parameter acts as a margin which tightens, in the linear optimisation problem of RAO, the bounds of the
Expand All @@ -450,41 +500,20 @@ See also: [Modelling loop-flows and their virtual cost](/castor/linear-problem/m
therefore increase the probability that the loop-flow constraints which are respected in the linear optimisation
problem, remain respected once the loop-flows are re-computed without the linear approximations.

#### violation-cost
##### violation-cost
- **Expected value**: numeric values, unit = unit of the objective function per MEGAWATT
- **Default value**: 10.0
- **Usage**: this parameter is the cost of each excess of loop-flow. That is to say, if the loop-flows on one or several
CNECs exceed the loop-flow threshold, a penalty will be added in the objective function of the RAO equal to:
*violation-cost x sum{cnec} excess-loop-flow(cnec)*

#### countries
- **Expected value**: array of country codes "XX"
- **Default value**: all countries encountered
- **Usage**: list of countries for which loop-flows should be limited accordingly to the specified constraints. If not
present, all countries encountered in the input files will be considered. Note that a cross-border line will have its
loop-flows monitored if at least one of its two sides is in a country from this list.
Example of this parameter : [ "BE", "NL" ] if you want to monitor loop-flows in and out of Belgium and the
Netherlands.

### MNEC extension
Adding a MnecParameters extension to RaoParameters will activate [MNEC constraints](/castor/linear-problem/mnec-filler.md).
#### MNEC optional parameter
Adding a MnecParameters to OpenRaoSearchTreeParameters will activate [MNEC constraints](/castor/linear-problem/mnec-filler.md).
(The RAO will only monitor CNECs that are only ["monitored"](/input-data/crac/json.md#cnecs)).
The following parameters tune these constraints.
The following parameters tune some of these constraints, the one which are implementation specific.
See also: [Modelling MNECs and their virtual cost](/castor/linear-problem/mnec-filler.md)

#### acceptable-margin-decrease
- **Expected value**: numeric values, in MEGAWATT unit
- **Default value**: 50 MW (required by CORE CC methodology)
- **Usage**: the decrease of the initial margin that is allowed by the optimisation on MNECs.
In other words, it defines the bounds for the margins on the MNECs by
*Mcnec ≥ max(0, m0cnec − acceptableDiminution)*
With *Mcnec* the margin on the cnec after optimisation, *m0cnec* the initial margin on the cnec, and
*acceptableDiminution* the so-called "acceptable-margin-decrease" coefficient.
For the CORE CC calculation, the ACER methodology fixes this coefficient at 50 MW.
For CSE CC calculation, setting this parameter to -99999 allows the MNEC constraints to consider
the thresholds in the CRAC only.

#### violation-cost
##### violation-cost
- **Expected value**: numeric values, no unit (it applies as a multiplier for the constraint violation inside the
objective function)
- **Default value**: 10.0 (same as [loop-flow violation cost](#violation-cost))
Expand All @@ -494,7 +523,7 @@ See also: [Modelling MNECs and their virtual cost](/castor/linear-problem/mnec-f
MNECs' constraints are respected. The penalty injected in the objective function is equal to the violation (difference
between actual margin and least acceptable margin) multiplied by this parameter.

#### constraint-adjustment-coefficient
##### constraint-adjustment-coefficient
- **Expected value**: numeric values, in MEGAWATT unit
- **Default value**: 0.0
- **Usage**: this coefficient is here to mitigate the approximation made by the linear optimisation (approximation = use
Expand All @@ -504,23 +533,12 @@ See also: [Modelling MNECs and their virtual cost](/castor/linear-problem/mnec-f
It tightens the MNEC constraint, in order to take some margin for that constraint to stay respected once the
approximations are removed (i.e. taps have been rounded and real flow calculated)

### Relative margins extension
Adding a RelativeMarginsParameters extension is mandatory when [objective function is relative](#type).
#### Relative margins optional parameter
Adding a RelativeMarginsParameters is mandatory when [objective function is relative](#type).
The following parameters tune the constraints which are implementation specific.
See also: [Modelling the maximum minimum relative margin objective function](/castor/linear-problem/max-min-relative-margin-filler.md)

#### ptdf-boundaries
- **Expected value**: array of zone-to-zone PTDF computation definition, expressed as an equation.
Zones are defined by their 2-character code or their 16-character EICode, inside **{ }** characters.
Zones are seperated by + or -.
All combinations are allowed: country codes, EIC, a mix.
- **Default value**: empty array
- **Usage**: contains the boundaries on which the PTDF absolute sums should be computed (and added to the denominator of
the relative RAM).
For example, in the SWE case, it should be equal to [ "{FR}-{ES}", "{ES}-{PT}" ].
For CORE, we should use all the CORE region boundaries (all countries seperated by a - sign) plus Alegro's special
equation: "{BE}-{22Y201903144---9}-{DE}+{22Y201903145---4}"

#### ptdf-approximation
##### ptdf-approximation
- **Expected value**: one of the following:
- "FIXED_PTDF"
- "UPDATE_PTDF_WITH_TOPO"
Expand All @@ -536,7 +554,7 @@ Zones are seperated by + or -.
each new combination of PST taps (i.e. for each iteration of the linear optimisation).
*Note that this option is only relevant in AC-loadflow mode, as the UPDATE_PTDF_WITH_TOPO already maximizes accuracy in DC.*

#### ptdf-sum-lower-bound
##### ptdf-sum-lower-bound
- **Expected value**: numeric value, no unit (homogeneous to PTDFs)
- **Default value**: 0.01
- **Usage**: PTDF absolute sums are used as a denominator in the objective function. In order to prevent the objective
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
import java.util.List;

import static com.powsybl.openrao.raoapi.RaoParametersCommons.*;
import static com.powsybl.openrao.raoapi.parameters.RaoParameters.addOptionalExtensionsDefaultValuesIfExist;

/**
* @author Baptiste Seguinot {@literal <baptiste.seguinot at rte-france.com>}
Expand Down Expand Up @@ -84,6 +85,7 @@ public RaoParameters deserialize(JsonParser parser, DeserializationContext deser
}
}
extensions.forEach(extension -> parameters.addExtension((Class) extension.getClass(), extension));
addOptionalExtensionsDefaultValuesIfExist(parameters);
return parameters;
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,7 @@ public static RaoParameters load(PlatformConfig platformConfig) {
RaoParameters parameters = new RaoParameters();
load(parameters, platformConfig);
parameters.loadExtensions(platformConfig);
addOptionalExtensionsDefaultValuesIfExist(parameters);
return parameters;
}

Expand All @@ -145,7 +146,47 @@ private void loadExtensions(PlatformConfig platformConfig) {
}
}

public boolean hasLoopFlowParameters() {
return this.getLoopFlowParameters().isPresent() || this.hasExtension(OpenRaoSearchTreeParameters.class) && this.getExtension(OpenRaoSearchTreeParameters.class).getLoopFlowParameters().isPresent();
public static void addOptionalExtensionsDefaultValuesIfExist(RaoParameters parameters) {
OpenRaoSearchTreeParameters extension = parameters.getExtension(OpenRaoSearchTreeParameters.class);
boolean hasExtension = !Objects.isNull(extension);
if (parameters.getMnecParameters().isPresent()) {
if (!hasExtension) {
parameters.addExtension(OpenRaoSearchTreeParameters.class, new OpenRaoSearchTreeParameters());
}
extension = parameters.getExtension(OpenRaoSearchTreeParameters.class);
if (extension.getMnecParameters().isEmpty()) {
extension.setMnecParameters(new com.powsybl.openrao.raoapi.parameters.extensions.MnecParameters());
}
} else {
if (hasExtension && extension.getMnecParameters().isPresent()) {
parameters.setMnecParameters(new com.powsybl.openrao.raoapi.parameters.MnecParameters());
}
}
if (parameters.getRelativeMarginsParameters().isPresent()) {
if (!hasExtension) {
parameters.addExtension(OpenRaoSearchTreeParameters.class, new OpenRaoSearchTreeParameters());
}
extension = parameters.getExtension(OpenRaoSearchTreeParameters.class);
if (extension.getRelativeMarginsParameters().isEmpty()) {
extension.setRelativeMarginsParameters(new com.powsybl.openrao.raoapi.parameters.extensions.RelativeMarginsParameters());
}
} else {
if (hasExtension && extension.getRelativeMarginsParameters().isPresent()) {
parameters.setRelativeMarginsParameters(new com.powsybl.openrao.raoapi.parameters.RelativeMarginsParameters());
}
}
if (parameters.getLoopFlowParameters().isPresent()) {
if (!hasExtension) {
parameters.addExtension(OpenRaoSearchTreeParameters.class, new OpenRaoSearchTreeParameters());
}
extension = parameters.getExtension(OpenRaoSearchTreeParameters.class);
if (extension.getLoopFlowParameters().isEmpty()) {
extension.setLoopFlowParameters(new com.powsybl.openrao.raoapi.parameters.extensions.LoopFlowParameters());
}
} else {
if (hasExtension && extension.getLoopFlowParameters().isPresent()) {
parameters.setLoopFlowParameters(new com.powsybl.openrao.raoapi.parameters.LoopFlowParameters());
}
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -222,11 +222,15 @@ void testConfigWithPartialExtensions() throws IOException {
assertTrue(parameters.getMnecParameters().isEmpty());
assertTrue(searchTreeParameters.getMnecParameters().isEmpty());

assertTrue(parameters.getRelativeMarginsParameters().isEmpty());
assertTrue(searchTreeParameters.getRelativeMarginsParameters().isPresent());
assertEquals(PtdfApproximation.UPDATE_PTDF_WITH_TOPO_AND_PST, searchTreeParameters.getRelativeMarginsParameters().get().getPtdfApproximation());
assertEquals(0.02, searchTreeParameters.getRelativeMarginsParameters().get().getPtdfSumLowerBound(), DOUBLE_TOLERANCE);

// If RelativeMarginsParameters is present on extension it should be created on rao-parameters,
// if it exists on rao-parameters it should be created on extension.
// The same rule exist for MnecParameters and LoopFlowParameters
assertTrue(parameters.getRelativeMarginsParameters().isPresent());

// Compare to json
roundTripTest(parameters, JsonRaoParameters::write, JsonRaoParameters::read, "/RaoParameters_config_withPartialExtensions.json");
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@
"not-optimized-cnecs" : {
"do-not-optimize-curative-cnecs-for-tsos-without-cras" : false
},
"relative-margins-parameters" : {
"ptdf-boundaries" : [ ]
},
"loop-flow-parameters" : {
"acceptable-increase" : 0.0,
"countries" : [ "ES", "FR", "PT" ]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ public PrePerimeterSensitivityAnalysis(Set<FlowCnec> flowCnecs,
public PrePerimeterResult runInitialSensitivityAnalysis(Network network, Crac crac) {
SensitivityComputer.SensitivityComputerBuilder sensitivityComputerBuilder = buildSensiBuilder()
.withOutageInstant(crac.getOutageInstant());
if (raoParameters.hasLoopFlowParameters()) {
if (raoParameters.getLoopFlowParameters().isPresent()) {
sensitivityComputerBuilder.withCommercialFlowsResults(toolProvider.getLoopFlowComputation(), toolProvider.getLoopFlowCnecs(flowCnecs));
}
if (raoParameters.getObjectiveFunctionParameters().getType().relativePositiveMargins()) {
Expand Down Expand Up @@ -86,7 +86,7 @@ public PrePerimeterResult runBasedOnInitialResults(Network network,
}
});
}
if (raoParameters.getObjectiveFunctionParameters().getType().relativePositiveMargins()) { // TODO if null
if (raoParameters.getObjectiveFunctionParameters().getType().relativePositiveMargins()) {
if (searchTreeParameters.getRelativeMarginsParameters().orElseThrow().getPtdfApproximation().shouldUpdatePtdfWithTopologicalChange()) {
sensitivityComputerBuilder.withPtdfsResults(toolProvider.getAbsolutePtdfSumsComputation(), flowCnecs);
} else {
Expand Down
Loading

0 comments on commit b4859b0

Please sign in to comment.