Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Loads Margin calculation #420

Draft
wants to merge 55 commits into
base: main
Choose a base branch
from
Draft
Changes from all commits
Commits
Show all changes
55 commits
Select commit Hold shift + click to select a range
c884e56
Add model documentation in models.json
Lisrte Jun 19, 2024
93e86f0
Add event models documentation
Lisrte Jun 20, 2024
52843cf
Move ModelConfigsHandler::eventBuilderConfigs in ModelConfigLoader
Lisrte Jun 20, 2024
e83f775
Merge branch 'main' into models_documentation
Lisrte Jul 1, 2024
efde11b
Rename lib to modelName
Lisrte Jul 4, 2024
2cbd3dd
Remove ModelInfos.java interface
Lisrte Jul 4, 2024
61724d4
Merge branch 'refs/heads/main' into models_documentation
Lisrte Jul 4, 2024
2aa8922
Fix merge
Lisrte Jul 4, 2024
8610109
Rename remaining lib to model
Lisrte Jul 4, 2024
019319b
Rename tag to modelName/name
Lisrte Jul 5, 2024
df3274d
Rename dynawaltz to dynawo
Lisrte Jul 5, 2024
eb5d3b6
Update documentation
Lisrte Jul 8, 2024
248b80a
Update documentation 2
Lisrte Jul 8, 2024
91b6b42
Fix code smells
Lisrte Jul 8, 2024
302bc63
Handle load variation area in margin calculation
Lisrte Jul 11, 2024
1720373
Phase 2 in DynawoSimulationContext
Lisrte Jul 12, 2024
fa97b48
Add MarginCalculationParameters and LoadVariationAreaXmlTest
Lisrte Jul 16, 2024
8dd3058
Add LoadIncreaseResult with XML parsing
Lisrte Sep 4, 2024
aee669c
Add provider, handler, multiple jobs
Lisrte Sep 4, 2024
e0caacb
Add LoadsVariationSupplier, fix todo
Lisrte Sep 6, 2024
1b5879a
Merge main
Lisrte Dec 19, 2024
c1960c1
Fix merge
Lisrte Dec 19, 2024
dcdebd5
Remove unused class
Lisrte Dec 19, 2024
1e8faf2
Remove duplicate code
Lisrte Dec 19, 2024
d073157
Remove LoadsVariation::VariationMode
Lisrte Jan 6, 2025
bda6a0b
Fix maven.yml
Lisrte Jan 7, 2025
4cb15fe
Add test coverage
Lisrte Jan 7, 2025
a0f15c4
Phase2 MC predicate
Lisrte Jan 8, 2025
82237be
Handle MC dynawo parameters
Lisrte Jan 13, 2025
e1f78d5
Fix tests
Lisrte Jan 15, 2025
0adfded
Add itools support and MC API
Lisrte Jan 16, 2025
79b092b
Fix checkstyle
Lisrte Jan 20, 2025
162ef76
Fix code smells
Lisrte Jan 21, 2025
e070d6f
Fix job and dyd xml
Lisrte Jan 24, 2025
4ebb33a
Merge branch 'main' into margin_calculation
Lisrte Jan 27, 2025
b4649cb
Fix tests
Lisrte Jan 27, 2025
9a7f40e
Mutualize contingency and aggregated results handing in dynawo-contin…
Lisrte Jan 27, 2025
4b7dd70
Fix MarginCalculationParametersTest
Lisrte Jan 27, 2025
22dc802
Fix distribution pom
Lisrte Jan 27, 2025
e64bed4
Fix distribution pom and report
Lisrte Jan 27, 2025
b92ab19
Add test coverage
Lisrte Jan 30, 2025
6c32ba4
Fix tests
Lisrte Jan 31, 2025
4400c51
Fix tests
Lisrte Jan 31, 2025
d571ccc
Fix tests with isEqualToIgnoringNewLines
Lisrte Jan 31, 2025
ff1ecdd
Fix tests with isEqualToIgnoringNewLines
Lisrte Jan 31, 2025
f1951b6
Fix tests with isEqualToIgnoringNewLines
Lisrte Jan 31, 2025
3d551c5
Fix tests with config, rename test folder
Lisrte Jan 31, 2025
45b03de
Use Builder for simulation context classes
Lisrte Feb 3, 2025
c37056e
Add AbstractContextBuilder
Lisrte Feb 4, 2025
520b893
Fix todo
Lisrte Feb 5, 2025
5eaf283
Add documentation
Lisrte Feb 6, 2025
9913bff
Add LoadVariationModels
Lisrte Feb 10, 2025
9ec0978
Add SimulationModels in DynawoSimulationContext
Lisrte Feb 10, 2025
fb32000
Put macro connection building into the context builders
Lisrte Feb 12, 2025
25a0538
Fix todo
Lisrte Feb 13, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 16 additions & 4 deletions .github/workflows/maven.yml
Original file line number Diff line number Diff line change
@@ -18,25 +18,37 @@ jobs:

steps:
- name: Checkout sources
uses: actions/checkout@v1
uses: actions/checkout@v4
with:
path: main

- name: Checkout powsybl-core branch
uses: actions/checkout@v4
with:
repository: powsybl/powsybl-core
ref: refs/heads/scalable_access
path: powsybl-core

- name: Set up JDK 17
uses: actions/setup-java@v1
with:
java-version: 17

- name: Build and install powsybl-core with Maven
run: mvn --batch-mode -DskipTests=true --file ./powsybl-core/pom.xml install

- name: Build with Maven
if: matrix.os == 'ubuntu-latest'
run: mvn --batch-mode -Pintegration-tests,jacoco install
run: mvn --batch-mode -Pintegration-tests,jacoco --file ./main/pom.xml install

- name: Build with Maven
if: matrix.os != 'ubuntu-latest'
run: mvn --batch-mode install
run: mvn --batch-mode --file ./main/pom.xml install

- name: Run SonarCloud analysis
if: matrix.os == 'ubuntu-latest'
run: >
mvn --batch-mode -DskipTests sonar:sonar
mvn --batch-mode -DskipTests --file ./main/pom.xml sonar:sonar
-Dsonar.host.url=https://sonarcloud.io
-Dsonar.organization=powsybl-ci-github
-Dsonar.projectKey=com.powsybl:powsybl-dynawo
Original file line number Diff line number Diff line change
@@ -41,8 +41,6 @@ private DynawoConstants() {

public static final String OUTPUT_IIDM_FILENAME = "outputIIDM.xml";

public static final String AGGREGATED_RESULTS = "aggregatedResults.xml";

public static final String FINAL_STATE_FOLDER = "finalState";

public static final String TIMELINE_FOLDER = "timeLine";
22 changes: 21 additions & 1 deletion distribution/pom.xml
Original file line number Diff line number Diff line change
@@ -28,27 +28,47 @@
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>powsybl-dynawo-commons</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>powsybl-dynawo-contingencies</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>powsybl-dynaflow</artifactId>

<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>powsybl-dynawo-simulation</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>powsybl-dynawo-dsl</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>powsybl-dynawo-algorithms-commons</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>powsybl-dynawo-security-analysis</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>powsybl-dynawo-margin-calculation</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>powsybl-dynawo-integration-tests</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>

12 changes: 12 additions & 0 deletions docs/iTools/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# iTools Commands

This section introduce iTools commands specific to Powsybl-Dynawo.
General information about iTools and its commands can be found [here](inv:powsyblcore:*:*#user/itools/index).

```{toctree}
---
maxdepth: 1
---
margin-calculation.md
```

91 changes: 91 additions & 0 deletions docs/iTools/margin-calculation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# iTools margin-calculation

The `margin-calculation` command loads a network, apply dynamic models, contingencies, loads variations and run a [margin calculation](../margin_calculation/index.md).
In the end, the results and the modified network can be exported to files.

## Usage
```
usage: itools [OPTIONS] margin-calculation --case-file <FILE>
--contingencies-file <FILE> --dynamic-models-file <FILE> [--help] [-I
<property=value>] [--import-parameters <IMPORT_PARAMETERS>]
--load-variations-file <FILE> [--output-file <FILE>] [--output-log-file
<FILE>] [--parameters-file <FILE>]

Available options are:
--config-name <CONFIG_NAME> Override configuration file name

Available arguments are:
--case-file <FILE> the case path
--contingencies-file <FILE> contingencies description as a
Groovy file
--dynamic-models-file <FILE> dynamic models description as a
Groovy file: defines the dynamic
models to be associated to chosen
equipments of the network
--help display the help and quit
-I <property=value> use value for given importer
parameter
--import-parameters <IMPORT_PARAMETERS> the importer configuration file
--load-variations-file <FILE> load variations description as a
JSON file
--output-file <FILE> margin calculation results output
path
--output-log-file <FILE> margin calculation logs output
path
--parameters-file <FILE> margin calculation parameters as a
JSON file

```

### Required options

`--case-file`
This option defines the path of the case file on which the simulation is run. The [supported formats](inv:powsyblcore:*:*#grid_exchange_formats/index.md) depend on the execution class path.

`--dynamic-models-file`
This option defines the path of the mapping file used to associate dynamic models to static equipments of the network or add dynamic automation systems. At the moment, only groovy scripts are supported. The [dynamic models DSL](inv:powsyblcore:*:*#simulation/dynamic/index.md#dynamic-models-mapping) depends on the simulator used.

`--contingencies-file`
This option defines the path of the contingency files. This file is a groovy script that respects the [contingency DSL](inv:powsyblcore:*:*#simulation/security/contingency-dsl.md) syntax.

`--load-variations-file`
This option defines the path of the load variations files. This file is a JSON that respects the [load variations](../margin_calculation/load_variations_supplier.md) syntax.

### Optional options

`--import-parameters`
This option defines the path of the importer's configuration file. It's possible to overload one or many parameters using the `-I property=value` syntax. The list of supported properties depends on the [input format](inv:powsyblcore:*:*#grid_exchange_formats/index.md).

`--output-file`
This option defines the path where to export the [results](#results) of the simulation.

`--parameters-file`
This option defines the path of the [parameters](#parameters) file of the simulation. If this option is not used, the simulation is run with the default parameters.

## Parameters
The available parameters are described [here](../margin_calculation/configuration).

## Results
The expected results are described [here](../margin_calculation/index#outputs)

## Examples
The following example shows how to run a margin calculation, using the default configuration:
```
$> itools margin-calculation --case-file /network.xiidm --dynamic-models-file /dynamicModels.groovy --contingencies-file /contingencies.groovy --load-variations-file /loadsVariations.json
Loading network '/network.xiidm'
Margin Calculation Tool
Margin calculation results:
+------------+------------------------+---------------------+----------------------+-----------------+------------------------+------------------------------+--------------------------------+
| Load level | Status | Failed criteria | Failed criteria time | Scenarios | Scenarios Status | Scenarios failed criteria | Scenarios failed criteria time |
+------------+------------------------+---------------------+----------------------+-----------------+------------------------+------------------------------+--------------------------------+
| 100.000 | CRITERIA_NON_RESPECTED | Failed criteria (2) | | | | | |
| | | total load power | 10.0000 | | | | |
| | | total load power | 20.0000 | | | | |
| 50.0000 | DIVERGENCE | | | Scenarios (2) | | | |
| | | | | Disconnect line | CRITERIA_NON_RESPECTED | Scenario failed criteria (2) | |
| | | | | | | Safety risk | 10.0000 |
| | | | | | | Safety risk | 20.0000 |
| | | | | Disconnect gen | CONVERGENCE | | |
| 25.0000 | CONVERGENCE | | | | | | |
+------------+------------------------+---------------------+----------------------+-----------------+------------------------+------------------------------+--------------------------------+
```
5 changes: 4 additions & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
@@ -3,12 +3,15 @@ Powsybl-dynawo is an interface between PowSyBl and [Dynaωo](https://dynawo.gith
- [LoadFlow API from powsybl-core](inv:powsyblcore:*:*#simulation/loadflow/index),
- [SecurityAnalysis API from powsybl-core](inv:powsyblcore:*:*#simulation/security/index),
- [DynamicSimulation API from powsybl-core](inv:powsyblcore:*:*#simulation/dynamic/index),
- [DynamicSecurityAnalysis API from powsybl-core](inv:powsyblcore:*:*#simulation/dynamic_security/index).
- [DynamicSecurityAnalysis API from powsybl-core](inv:powsyblcore:*:*#simulation/dynamic_security/index)
- [MarginCalculation API specific to powsybl-dynawo](margin_calculation/index.md).

```{toctree}
:hidden:
load_flow/index.md
security_analysis/index.md
dynamic_simulation/index.md
dynamic_security_analysis/index.md
margin_calculation/index.md
iTools/index.md
```
88 changes: 88 additions & 0 deletions docs/margin_calculation/configuration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# Configuration

The margin calculation reuse the `dynawo-simulation-default-parameters` [module](../dynamic_simulation/configuration.md#default-parameters).

## Default parameters
The `margin-calculation-default-parameters` module defines the default values for all parameters of a margin calculation run with Dynawo.

### Optional parameters

**startTime**
`startTime` defines when the simulation begins, in seconds.
The default value of this property is `0`.

**stopTime**
`stopTime` defines when the simulation stops, in seconds.
The default value of this property is `200`.

**loadIncrease.startTime**
`loadIncrease.startTime` defines when the load variation start, in seconds.
This property value should be between start time and margin calculation start time.
The default value of this property is `10`.

**loadIncrease.stopTime**
`loadIncrease.stopTime` defines when the load variation stop, in seconds.
This property value should be between load increase start time and margin calculation start time.
The default value of this property is `50`.

**margin-calculation-start-time**
`margin-calculation-start-time` defines when the margin calculation start, in seconds.
This property value should be between start and stop time.
The default value of this property is `100`.

**contingencies-start-time**
`contingencies-start-time` defines when the contingencies start, in seconds.
This property value should be between margin calculation start time and stop time.
The default value of this property is `120`.

**calculationType**
`calculationType` defines which maximum load variation is calculated.
The available `com.powsybl.dynawo.margincalculation.MarginCalculationParameters.CalculationType` values are:
- `GLOBAL_MARGIN`: search for the maximum load variation for all events
- `LOCAL_MARGIN`: search for the maximum load variation for each event

The default value of this property is `GLOBAL_MARGIN`.

**accuracy**
`accuracy` defines the maximum difference between the result obtained and the exact margin, in percent.
The default value of this property is `2`.

**load-models-rule**
`load-models-rule` defines which loads will be set with the default dynamic model in the first step of the simulation.
The available `com.powsybl.dynawo.margincalculation.MarginCalculationParameters.LoadModelsRule` values are:
- `ALL_LOADS`: all loads will use the default model
- `TARGETED_LOADS`: only loads affected by a load variation will use the default model

The default value of this property is `ALL_LOADS`.


### Examples

**YAML configuration:**
```yaml
margin-calculation-default-parameters:
startTime: 0
loadIncrease.startTime: 10
loadIncrease.stopTime: 50
margin-calculation-start-time: 100
contingencies-start-time: 120
stopTime: 200
calculationType: GLOBAL_MARGIN
accuracy: 2
load-models-rule: ALL_LOADS
```

**XML configuration:**
```xml
<margin-calculation-default-parameters>
<startTime>0</startTime>
<loadIncrease.startTime>10</loadIncrease.startTime>
<loadIncrease.stopTime>50</loadIncrease.stopTime>
<margin-calculation-start-time>100</margin-calculation-start-time>
<contingenciesStartTime>120</contingenciesStartTime>
<stopTime>200</stopTime>
<calculationType>GLOBAL_MARGIN</calculationType>
<accuracy>2</accuracy>
<load-models-rule>ALL_LOADS</load-models-rule>
</margin-calculation-default-parameters>
```
38 changes: 38 additions & 0 deletions docs/margin_calculation/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Margin calculation

```{toctree}
:hidden:
configuration.md
load_variations_supplier.md
```

PowSyBl-Dynaωo provides an implementation of the margin calculation with [Dynaωo-algorithms](https://dynawo.github.io/about/dynalgo), a wrapper around [Dynaωo](https://dynawo.github.io) providing utility algorithms to calculate complex key values of a power system.

The margin calculation is a simulation of a same base power system with a load variation and subject to different events to compute the maximum load increase in a specific region before the voltage collapses.

The algorithm is as follows: we first simulate the maximum load variation(100%) in the first step, and then use the results as the starting point for each event simulation in the final step. If one of those simulation fails, a dichotomy is applied to find out the maximum load variation for which all events (global margin) or each event (local margin) pass.

## Installation

Read this [documentation page](https://dynawo.github.io/install/dynalgo) to learn how to install and configure Dynaωo-algorithms.

## Inputs

The inputs of the margin calculation are the following:
- a static network
- a set of dynamic models provided by the same [suppliers](../dynamic_simulation/dynamic-models-mapping) used for the dynawo dynamic simulation
- a set of [contingencies](inv:powsyblcore:*:*#simulation/security/contingency-dsl)
- a set of [load variations](load_variations_supplier)
- a set of parameters for the [margin calculation](/configuration) and for [Dynawo](../dynamic_simulation/configuration)

## Outputs

The outputs of a margin calculation is a list of load increase result each containing:
- the load increase level
- the status (`CONVERGED`, `DIVERGED` or `CRITERIA_FAILURE`)
- if the base case `CONVERGED`, alist of scenario result for each contingency
- in case of `CRITERIA_FAILURE`, the list of failed criterion

## Going further
- [Run a margin calculation through an iTools command](../iTools/margin-calculation.md): learn how to perform a margin calculation from the command line
You may find an extensive documentation of the Dynawo project [here](https://github.com/dynawo/dynawo/releases/latest/download/DynawoDocumentation.pdf).
30 changes: 30 additions & 0 deletions docs/margin_calculation/load_variations_supplier.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Load variations supplier
Loads variation supplier creates loads variations used for the margin calculation.

## Implementation
Powsybl-Dynawo handle provide one supplier using JSON configuration file.
All variations should be written in an `variations` array.

## Loads variation model
The variation model has two attributes:
- `loadsIds`: an array of load ids.
- `variationValue`: the variation to apply on loads.

**Json configuration:**
```json
{
"variations": [
{
"loadsIds": ["LOAD", "LOAD2"],
"variationValue": 20
},
{
"loadsIds": ["LOAD3"],
"variationValue": 10.2
}
]
}
```

## Loads variation builder
Ultimately, the supplier call the dedicated builder `LoadsVariationBuilder` that can be used directly by developers.
Loading