diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml new file mode 100644 index 0000000000..934aaacee0 --- /dev/null +++ b/docs/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +build: + os: ubuntu-20.04 + tools: + python: "3.9" + +sphinx: + configuration: docs/conf.py + +python: + install: + - requirements: docs/requirements.txt \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..346b8d5581 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,27 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + + +clean: + @echo "Removing $(SOURCEDIR)/reference/api" + @rm -rf "$(SOURCEDIR)/reference/api" + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..74bf7738b5 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,10 @@ +These are the documentation sources for OpenRAO. +Please keep them up-to-date with your developments. +They are published on powsybl-openrao.readthedocs.io and pull requests are built and previewed automatically. + +In order to build the docs locally, run the following commands: +~~~bash +pip install -r docs/requirements.txt +sphinx-build -a docs ./build-docs +~~~ +Then open `build-docs/index.html` in your browser. \ No newline at end of file diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 0000000000..2ea6b5c3fe Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/_static/img/CSA-profiles.png b/docs/_static/img/CSA-profiles.png new file mode 100644 index 0000000000..5a1238d91f Binary files /dev/null and b/docs/_static/img/CSA-profiles.png differ diff --git a/docs/_static/img/CracCreationContext.png b/docs/_static/img/CracCreationContext.png new file mode 100644 index 0000000000..c3a04f3173 Binary files /dev/null and b/docs/_static/img/CracCreationContext.png differ diff --git a/docs/_static/img/Flows.png b/docs/_static/img/Flows.png new file mode 100644 index 0000000000..83ac6653ef Binary files /dev/null and b/docs/_static/img/Flows.png differ diff --git a/docs/_static/img/General-GLSK.png b/docs/_static/img/General-GLSK.png new file mode 100644 index 0000000000..d710ed6de3 Binary files /dev/null and b/docs/_static/img/General-GLSK.png differ diff --git a/docs/_static/img/HVDC_AC_model.png b/docs/_static/img/HVDC_AC_model.png new file mode 100644 index 0000000000..9f375a29fe Binary files /dev/null and b/docs/_static/img/HVDC_AC_model.png differ diff --git a/docs/_static/img/NativeCrac.png b/docs/_static/img/NativeCrac.png new file mode 100644 index 0000000000..b12f1cd33e Binary files /dev/null and b/docs/_static/img/NativeCrac.png differ diff --git a/docs/_static/img/Search-tree-with-combinations.png b/docs/_static/img/Search-tree-with-combinations.png new file mode 100644 index 0000000000..3b5262fe3f Binary files /dev/null and b/docs/_static/img/Search-tree-with-combinations.png differ diff --git a/docs/_static/img/States_AUTO.png b/docs/_static/img/States_AUTO.png new file mode 100644 index 0000000000..7e1b2cbd0d Binary files /dev/null and b/docs/_static/img/States_AUTO.png differ diff --git a/docs/_static/img/angle_monitoring.png b/docs/_static/img/angle_monitoring.png new file mode 100644 index 0000000000..ccbc8a39bb Binary files /dev/null and b/docs/_static/img/angle_monitoring.png differ diff --git a/docs/_static/img/angle_monitoring_algorithm.png b/docs/_static/img/angle_monitoring_algorithm.png new file mode 100644 index 0000000000..4a47a11bc0 Binary files /dev/null and b/docs/_static/img/angle_monitoring_algorithm.png differ diff --git a/docs/_static/img/busbar.png b/docs/_static/img/busbar.png new file mode 100644 index 0000000000..f85a7f4882 Binary files /dev/null and b/docs/_static/img/busbar.png differ diff --git a/docs/_static/img/core-cne-structure.png b/docs/_static/img/core-cne-structure.png new file mode 100644 index 0000000000..69658ca10a Binary files /dev/null and b/docs/_static/img/core-cne-structure.png differ diff --git a/docs/_static/img/core-cne.png b/docs/_static/img/core-cne.png new file mode 100644 index 0000000000..7382534525 Binary files /dev/null and b/docs/_static/img/core-cne.png differ diff --git a/docs/_static/img/curative1.png b/docs/_static/img/curative1.png new file mode 100644 index 0000000000..af622586ce Binary files /dev/null and b/docs/_static/img/curative1.png differ diff --git a/docs/_static/img/curative2.png b/docs/_static/img/curative2.png new file mode 100644 index 0000000000..218d703fca Binary files /dev/null and b/docs/_static/img/curative2.png differ diff --git a/docs/_static/img/equally-balanced-GLSK.png b/docs/_static/img/equally-balanced-GLSK.png new file mode 100644 index 0000000000..e95601eb9d Binary files /dev/null and b/docs/_static/img/equally-balanced-GLSK.png differ diff --git a/docs/_static/img/farao3.jpg b/docs/_static/img/farao3.jpg new file mode 100644 index 0000000000..12a4bbca3b Binary files /dev/null and b/docs/_static/img/farao3.jpg differ diff --git a/docs/_static/img/flow-diagram-nativeCrac.png b/docs/_static/img/flow-diagram-nativeCrac.png new file mode 100644 index 0000000000..5b6d3f6c5a Binary files /dev/null and b/docs/_static/img/flow-diagram-nativeCrac.png differ diff --git a/docs/_static/img/flowcnec.png b/docs/_static/img/flowcnec.png new file mode 100644 index 0000000000..d1b75e79e7 Binary files /dev/null and b/docs/_static/img/flowcnec.png differ diff --git a/docs/_static/img/instants-states.png b/docs/_static/img/instants-states.png new file mode 100644 index 0000000000..8f0247eeb1 Binary files /dev/null and b/docs/_static/img/instants-states.png differ diff --git a/docs/_static/img/king-tut.svg b/docs/_static/img/king-tut.svg new file mode 100644 index 0000000000..05ef20a4ca --- /dev/null +++ b/docs/_static/img/king-tut.svg @@ -0,0 +1,3009 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + Openclipart + + + Tut-Ankh-Penguin + 2013-02-18T09:20:20 + Funky Tut - they said you do the penguin ;-) (see song 'King Tut' by Steve Martin) + https://openclipart.org/detail/175188/tut-ankh-penguin-by-moini-175188 + + + Moini + + + + + King Tut + Tut + Tutankhamun + Tux + animal + archaeology + archeology + bird + egypt + egyptian + penguin + pharaoh + pyramid + + + + + + + + + + + diff --git a/docs/_static/img/linear-rao-algo.png b/docs/_static/img/linear-rao-algo.png new file mode 100644 index 0000000000..d46daec7e3 Binary files /dev/null and b/docs/_static/img/linear-rao-algo.png differ diff --git a/docs/_static/img/logo-farao-f-seul-orange.svg b/docs/_static/img/logo-farao-f-seul-orange.svg new file mode 100644 index 0000000000..a884254a80 --- /dev/null +++ b/docs/_static/img/logo-farao-f-seul-orange.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + diff --git a/docs/_static/img/merit-order-GLSK-2.png b/docs/_static/img/merit-order-GLSK-2.png new file mode 100644 index 0000000000..e953d1d9cf Binary files /dev/null and b/docs/_static/img/merit-order-GLSK-2.png differ diff --git a/docs/_static/img/modular.png b/docs/_static/img/modular.png new file mode 100644 index 0000000000..54bcd5c917 Binary files /dev/null and b/docs/_static/img/modular.png differ diff --git a/docs/_static/img/modular2.png b/docs/_static/img/modular2.png new file mode 100644 index 0000000000..fcec50a7b8 Binary files /dev/null and b/docs/_static/img/modular2.png differ diff --git a/docs/_static/img/patl-tatl.png b/docs/_static/img/patl-tatl.png new file mode 100644 index 0000000000..7e30c5a64b Binary files /dev/null and b/docs/_static/img/patl-tatl.png differ diff --git a/docs/_static/img/proportional-GLSK.png b/docs/_static/img/proportional-GLSK.png new file mode 100644 index 0000000000..c75ac06c37 Binary files /dev/null and b/docs/_static/img/proportional-GLSK.png differ diff --git a/docs/_static/img/proportional-to-remaining-GLSK.png b/docs/_static/img/proportional-to-remaining-GLSK.png new file mode 100644 index 0000000000..3cc782a759 Binary files /dev/null and b/docs/_static/img/proportional-to-remaining-GLSK.png differ diff --git a/docs/_static/img/proportional-to-target-power-GLSK.png b/docs/_static/img/proportional-to-target-power-GLSK.png new file mode 100644 index 0000000000..bba025676d Binary files /dev/null and b/docs/_static/img/proportional-to-target-power-GLSK.png differ diff --git a/docs/_static/img/rao_steps.png b/docs/_static/img/rao_steps.png new file mode 100644 index 0000000000..f62db1cc0e Binary files /dev/null and b/docs/_static/img/rao_steps.png differ diff --git a/docs/_static/img/search-tree-algo-with-linear.jpg b/docs/_static/img/search-tree-algo-with-linear.jpg new file mode 100644 index 0000000000..52b05dec24 Binary files /dev/null and b/docs/_static/img/search-tree-algo-with-linear.jpg differ diff --git a/docs/_static/img/search-tree-example.png b/docs/_static/img/search-tree-example.png new file mode 100644 index 0000000000..eacfa75a7d Binary files /dev/null and b/docs/_static/img/search-tree-example.png differ diff --git a/docs/_static/img/search-tree-rao-algo.png b/docs/_static/img/search-tree-rao-algo.png new file mode 100644 index 0000000000..da4a87fb44 Binary files /dev/null and b/docs/_static/img/search-tree-rao-algo.png differ diff --git a/docs/_static/img/simulation_ara.png b/docs/_static/img/simulation_ara.png new file mode 100644 index 0000000000..ba464a1250 Binary files /dev/null and b/docs/_static/img/simulation_ara.png differ diff --git a/docs/_static/img/swe-cne-structure.png b/docs/_static/img/swe-cne-structure.png new file mode 100644 index 0000000000..bfc20696e7 Binary files /dev/null and b/docs/_static/img/swe-cne-structure.png differ diff --git a/docs/_static/img/swe-cne.png b/docs/_static/img/swe-cne.png new file mode 100644 index 0000000000..41a8b1c2ad Binary files /dev/null and b/docs/_static/img/swe-cne.png differ diff --git a/docs/_static/img/tutorial/basecase.svg b/docs/_static/img/tutorial/basecase.svg new file mode 100644 index 0000000000..d5ee6e9773 --- /dev/null +++ b/docs/_static/img/tutorial/basecase.svg @@ -0,0 +1,840 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 167 + + + + + + + + + + + + -167 + + + + + + + + + + + + + + -167 + + + + + + + + + + + + 167 + + + + + + + + + + + + + + 500 + + + + + + + + + + + + -500 + + + + + + + + + + + + + + 500 + + + + + + + + + + + + -500 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 333 + + + + + + + + + + + + -333 + + + + + + + + + + + + + + + + + + + -167 + + + + + + + + + + + + 167 + + + + + + + + + + + + + + 167 + + + + + + + + + + + + -167 + + + + + + + + + + + + + + 333 + + + + + + + + + + + + -333 + + + + + + + + + + + + + + -500 + + + + + + + + + + + + 500 + + + + + + + + + + + + + + -500 + + + + + + + + + + + + 500 + + + + + + + + + + + + + + -500 + + + + + + + + + + + + 500 + + + + + + + + + + + + + + -500 + + + + + + + + + + + + 500 + + + + + + + + + + + + + + -0 + + + + + + + + + + + + 0 + + + + + + + + + + + + + + 500 + + + + + + + + + + + + -500 + + + + + + + + + + + + + + 500 + + + + + + + + + + + + -500 + + + + + + + + + + + + + + -0 + + + + + + + + + + + + 0 + + + + + + + + + + + + + + + + + + + + +
+
BBE1AA1
+ + + + + +
+
+
kV / 0.7Β°
+
+ + +
+
BBE2AA1
+ + + + + + + + + +
+
+
kV / 0.0Β°
+
+
kV / 1.3Β°
+
+ + +
+
DDE1AA1
+ + + + + +
+
+
kV / 0.7Β°
+
+ + +
+
DDE2AA1
+ + + + + +
+
+
kV / 1.3Β°
+
+ + +
+
DDE3AA1
+ + + + + +
+
+
kV / -0.0Β°
+
+ + +
+
FFR1AA1
+ + + + + +
+
+
kV / -4.0Β°
+
+ + +
+
FFR2AA1
+ + + + + +
+
+
kV / -2.0Β°
+
+ + +
+
FFR3AA1
+ + + + + +
+
+
kV / -2.0Β°
+
+ + +
+
NNL1AA1
+ + + + + +
+
+
kV / 5.3Β°
+
+ + +
+
NNL2AA1
+ + + + + +
+
+
kV / 3.3Β°
+
+ + +
+
NNL3AA1
+ + + + + +
+
+
kV / 3.3Β°
+
+ + + diff --git a/docs/_static/img/tutorial/curative.svg b/docs/_static/img/tutorial/curative.svg new file mode 100644 index 0000000000..2545a631cc --- /dev/null +++ b/docs/_static/img/tutorial/curative.svg @@ -0,0 +1,840 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 661 + + + + + + + + + + + + -661 + + + + + + + + + + + + + + -661 + + + + + + + + + + + + 661 + + + + + + + + + + + + + + 1,000 + + + + + + + + + + + + -1,000 + + + + + + + + + + + + + + 333 + + + + + + + + + + + + -333 + + + + + + + + + + + + + + 333 + + + + + + + + + + + + -333 + + + + + + + + + + + + + + 333 + + + + + + + + + + + + -333 + + + + + + + + + + + + + + 339 + + + + + + + + + + + + -339 + + + + + + + + + + + + + + + + + + + -0 + + + + + + + + + + + + 0 + + + + + + + + + + + + + + -0 + + + + + + + + + + + + 0 + + + + + + + + + + + + + + -0 + + + + + + + + + + + + 0 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -0 + + + + + + + + + + + + 0 + + + + + + + + + + + + + + -333 + + + + + + + + + + + + 333 + + + + + + + + + + + + + + -667 + + + + + + + + + + + + 667 + + + + + + + + + + + + + + -333 + + + + + + + + + + + + 333 + + + + + + + + + + + + + + 667 + + + + + + + + + + + + -667 + + + + + + + + + + + + + + 333 + + + + + + + + + + + + -333 + + + + + + + + + + + + + + -333 + + + + + + + + + + + + 333 + + + + + + + + + + + + + + + + + + + + +
+
BBE1AA1
+ + + + + +
+
+
kV / -2.6Β°
+
+ + +
+
BBE2AA1
+ + + + + + + + + +
+
+
kV / -5.2Β°
+
+
kV / 0.0Β°
+
+ + +
+
DDE1AA1
+ + + + + +
+
+
kV / -10.5Β°
+
+ + +
+
DDE2AA1
+ + + + + +
+
+
kV / -10.5Β°
+
+ + +
+
DDE3AA1
+ + + + + +
+
+
kV / -10.5Β°
+
+ + +
+
FFR1AA1
+ + + + + +
+
+
kV / -11.9Β°
+
+ + +
+
FFR2AA1
+ + + + + +
+
+
kV / -10.5Β°
+
+ + +
+
FFR3AA1
+ + + + + +
+
+
kV / -9.2Β°
+
+ + +
+
NNL1AA1
+ + + + + +
+
+
kV / 4.0Β°
+
+ + +
+
NNL2AA1
+ + + + + +
+
+
kV / 1.3Β°
+
+ + +
+
NNL3AA1
+ + + + + +
+
+
kV / 2.6Β°
+
+ + + diff --git a/docs/_static/img/tutorial/outage.svg b/docs/_static/img/tutorial/outage.svg new file mode 100644 index 0000000000..15279b73ef --- /dev/null +++ b/docs/_static/img/tutorial/outage.svg @@ -0,0 +1,840 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 661 + + + + + + + + + + + + -661 + + + + + + + + + + + + + + -661 + + + + + + + + + + + + 661 + + + + + + + + + + + + + + 1,000 + + + + + + + + + + + + -1,000 + + + + + + + + + + + + + + 1,000 + + + + + + + + + + + + -1,000 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 339 + + + + + + + + + + + + -339 + + + + + + + + + + + + + + + + + + + -0 + + + + + + + + + + + + 0 + + + + + + + + + + + + + + -0 + + + + + + + + + + + + 0 + + + + + + + + + + + + + + -0 + + + + + + + + + + + + 0 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -0 + + + + + + + + + + + + 0 + + + + + + + + + + + + + + -333 + + + + + + + + + + + + 333 + + + + + + + + + + + + + + -667 + + + + + + + + + + + + 667 + + + + + + + + + + + + + + -333 + + + + + + + + + + + + 333 + + + + + + + + + + + + + + 667 + + + + + + + + + + + + -667 + + + + + + + + + + + + + + 333 + + + + + + + + + + + + -333 + + + + + + + + + + + + + + -333 + + + + + + + + + + + + 333 + + + + + + + + + + + + + + + + + + + + +
+
BBE1AA1
+ + + + + +
+
+
kV / 2.6Β°
+
+ + +
+
BBE2AA1
+ + + + + + + + + +
+
+
kV / 0.0Β°
+
+
kV / 5.2Β°
+
+ + +
+
DDE1AA1
+ + + + + +
+
+
kV / -5.3Β°
+
+ + +
+
DDE2AA1
+ + + + + +
+
+
kV / -5.3Β°
+
+ + +
+
DDE3AA1
+ + + + + +
+
+
kV / -5.3Β°
+
+ + +
+
FFR1AA1
+ + + + + +
+
+
kV / -6.6Β°
+
+ + +
+
FFR2AA1
+ + + + + +
+
+
kV / -5.3Β°
+
+ + +
+
FFR3AA1
+ + + + + +
+
+
kV / -4.0Β°
+
+ + +
+
NNL1AA1
+ + + + + +
+
+
kV / 11.9Β°
+
+ + +
+
NNL2AA1
+ + + + + +
+
+
kV / 9.2Β°
+
+ + +
+
NNL3AA1
+ + + + + +
+
+
kV / 10.5Β°
+
+ + + diff --git a/docs/_static/img/tutorial/preventive.svg b/docs/_static/img/tutorial/preventive.svg new file mode 100644 index 0000000000..eb05f74066 --- /dev/null +++ b/docs/_static/img/tutorial/preventive.svg @@ -0,0 +1,840 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 461 + + + + + + + + + + + + -461 + + + + + + + + + + + + + + -461 + + + + + + + + + + + + 461 + + + + + + + + + + + + + + 402 + + + + + + + + + + + + -402 + + + + + + + + + + + + + + 402 + + + + + + + + + + + + -402 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -59 + + + + + + + + + + + + 59 + + + + + + + + + + + + + + + + + + + -199 + + + + + + + + + + + + 199 + + + + + + + + + + + + + + 199 + + + + + + + + + + + + -199 + + + + + + + + + + + + + + 399 + + + + + + + + + + + + -399 + + + + + + + + + + + + + + -598 + + + + + + + + + + + + 598 + + + + + + + + + + + + + + -598 + + + + + + + + + + + + 598 + + + + + + + + + + + + + + -533 + + + + + + + + + + + + 533 + + + + + + + + + + + + + + -467 + + + + + + + + + + + + 467 + + + + + + + + + + + + + + 65 + + + + + + + + + + + + -65 + + + + + + + + + + + + + + 467 + + + + + + + + + + + + -467 + + + + + + + + + + + + + + 533 + + + + + + + + + + + + -533 + + + + + + + + + + + + + + 65 + + + + + + + + + + + + -65 + + + + + + + + + + + + + + + + + + + + +
+
BBE1AA1
+ + + + + +
+
+
kV / 1.8Β°
+
+ + +
+
BBE2AA1
+ + + + + + + + + +
+
+
kV / 0.0Β°
+
+
kV / 3.7Β°
+
+ + +
+
DDE1AA1
+ + + + + +
+
+
kV / 1.8Β°
+
+ + +
+
DDE2AA1
+ + + + + +
+
+
kV / 2.6Β°
+
+ + +
+
DDE3AA1
+ + + + + +
+
+
kV / 1.0Β°
+
+ + +
+
FFR1AA1
+ + + + + +
+
+
kV / -3.4Β°
+
+ + +
+
FFR2AA1
+ + + + + +
+
+
kV / -1.3Β°
+
+ + +
+
FFR3AA1
+ + + + + +
+
+
kV / -1.6Β°
+
+ + +
+
NNL1AA1
+ + + + + +
+
+
kV / 7.1Β°
+
+ + +
+
NNL2AA1
+ + + + + +
+
+
kV / 5.3Β°
+
+ + +
+
NNL3AA1
+ + + + + +
+
+
kV / 5.0Β°
+
+ + + diff --git a/docs/_static/img/voltage_monitoring.png b/docs/_static/img/voltage_monitoring.png new file mode 100644 index 0000000000..585803a969 Binary files /dev/null and b/docs/_static/img/voltage_monitoring.png differ diff --git a/docs/_static/img/voltage_monitoring_algorithm.png b/docs/_static/img/voltage_monitoring_algorithm.png new file mode 100644 index 0000000000..f8774efdf7 Binary files /dev/null and b/docs/_static/img/voltage_monitoring_algorithm.png differ diff --git a/docs/_static/logos/powsybl_logo.svg b/docs/_static/logos/powsybl_logo.svg new file mode 100644 index 0000000000..499d4b9e30 --- /dev/null +++ b/docs/_static/logos/powsybl_logo.svg @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst new file mode 100644 index 0000000000..dd40993e0d --- /dev/null +++ b/docs/_templates/autosummary/class.rst @@ -0,0 +1,27 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + + {% block methods %} + {% if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + {% for item in methods %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + {% for item in attributes %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} diff --git a/docs/_templates/autosummary/class_without_members.rst b/docs/_templates/autosummary/class_without_members.rst new file mode 100644 index 0000000000..72892fb280 --- /dev/null +++ b/docs/_templates/autosummary/class_without_members.rst @@ -0,0 +1,6 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + diff --git a/docs/_templates/navbar-brand-powsybl-openrao.html b/docs/_templates/navbar-brand-powsybl-openrao.html new file mode 100644 index 0000000000..5925c6dc59 --- /dev/null +++ b/docs/_templates/navbar-brand-powsybl-openrao.html @@ -0,0 +1,4 @@ + + + {{ project }} + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..6cb8d58e15 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,96 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +# Path to python sources, for doc generation on readthedocs +source_path = os.path.abspath('..') +sys.path.insert(0, source_path) +print(f'appended {source_path}') + + +# -- Project information ----------------------------------------------------- + +project = 'PowSyBl Open RAO' +copyright = '2024, RTE (http://www.rte-france.com)' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.viewcode', + 'sphinx.ext.doctest', + 'sphinx.ext.napoleon', + 'sphinx.ext.todo', + 'sphinx.ext.intersphinx', + 'sphinx_tabs.tabs', + 'myst_parser'] +myst_enable_extensions = [ + "amsmath", + "colon_fence", + "dollarmath" +] +myst_heading_anchors = 6 + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "pydata_sphinx_theme" + +html_title = 'PowSyBl Open RAO' +html_short_title = 'PowSyBl Open RAO' + +html_logo = '_static/logos/powsybl_logo.svg' +html_favicon = "_static/favicon.ico" + +html_theme_options = { + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/powsybl/powsybl-open-rao", + "icon": "fab fa-github-square", + } + ], + "navbar_start": ["navbar-brand-powsybl-openrao"], +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +todo_include_todos = True + +# Links to external documentations : python 3 and pandas +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + 'pandas': ('https://pandas.pydata.org/docs', None), +} + +# Generate one file per method +autosummary_generate = True \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000..f3e83bcb18 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,7 @@ +PowSyBl Open RAO's user documentation +===================================== + +.. toctree:: + :maxdepth: 2 + + input-data/index diff --git a/docs/input-data/crac/cim.md b/docs/input-data/crac/cim.md new file mode 100644 index 0000000000..0dc96120a0 --- /dev/null +++ b/docs/input-data/crac/cim.md @@ -0,0 +1,416 @@ +# CIM CRAC format + +## Header overview + +```xml + + CIM_CRAC_DOCUMENT + 1 + B15 + A48 + FAKE + A36 + FAKE + A04 + 2021-03-31T15:02:00Z + + A42 + + + 2021-04-01T22:00Z + 2021-04-02T22:00Z + + 10YCB-FR-ES-PT-S + + TimeSeries_1 + ... + + + TimeSeries_2 + ... + + + ... + +``` +A crac market document has a time interval for its validity. Therefore, **this document has to be imported for a specific datetime** – hourly-precise. +Moreover, only timeseries whose mRIDs are configured in the CimCracCreationParameters [timeseries-mrids](creation-parameters.md#timeseries-mrids) +parameter are imported. This allows the import of border-specific contraints and remedial actions. +Each timeseries is configured using a curve: either **SEQUENTIAL_FIXED_SIZE_BLOCKS_CURVE_TYPE** (value "A01"), +or **VARIABLE_SIZED_BLOCK_CURVE** (value "A03"). +- In the case of SEQUENTIAL_FIXED_SIZE_BLOCKS_CURVE_TYPE, all period's points represent one resolution timespan (**resolution** is a parameter i.e. 60 minutes), their **position** parameter gives their relative start and end in their periods timespan (starting from "1") depending on resolution. +- In the case of VARIABLE_SIZED_BLOCK_CURVE, period's points can represent multiple resolution timespans, their **position** parameter gives their relative start, and their end is either equal to the next defined point's beginning, or the end of the period if no other point is defined after. +### Period examples + +#### SEQUENTIAL_FIXED_SIZE_BLOCKS_CURVE_TYPE +All period points are present from position 1 to position 24, and represent an hour (because resolution is "PT60M" = 60 minutes): +- point position 1 is applicable for timestamps between 2021-04-01T22:00Z (included) and 2021-04-01T23:00Z (excluded) +- point position 2 is applicable for timestamps between 2021-04-01T23:00Z (included) and 2021-04-01T24:00Z (excluded) +- point position 3 is applicable for timestamps between 2021-04-01T24:00Z (included) and 2021-04-02T01:00Z (excluded), etc +```xml + + TimeSeries2 + B54 + A01 + FAKE + FAKE + + + 2021-04-01T22:00Z + 2021-04-02T22:00Z + + PT60M + + 1 + + ... + + + + 2 + + ... + + + (...) + + 24 + + ... + + + + +``` + +#### VARIABLE_SIZED_BLOCK_CURVE +- point position 5 is applicable for timestamps between 2021-04-02T02:00Z (included) and 2021-04-02T11:00Z (excluded) +- point position 14 is applicable for timestamps between 2021-04-02T11:00Z (included) and 2021-04-02T15:00Z (excluded) +- point position 18 is applicable for timestamps between 2021-04-02T15:00Z (included) and 2021-04-02T22:00Z (excluded) +```xml + + TimeSeries2 + B54 + A03 + FAKE + FAKE + + + 2021-04-01T22:00Z + 2021-04-02T22:00Z + + PT60M + + 5 + + ... + + + + 14 + + ... + + + + 18 + + ... + + + + +``` + +## Contingencies + +```xml + + ContingenciesSeries1 + B55 + ContingenciesSeries + A52 + + Co-1 + Co-1-name + + networkElementId + Co1NetworkElementName + 1------0 + 1------0 + + + + ... + +``` +Contingencies are listed in Series of business type B55, B56 or B57. They are defined in Contingency_Series elements. The associated network elements are defined in the registered resources. + +## CNECs + +### FlowCnecs + +```xml + + CNECs_after_all_contingencies + B57 + CNECs_after_all_contingencies + A52 + βšͺOPTIONAL + ... + + + CNEC-2 + CNEC-2-name + + FAKE_ID + CNEC-2 + 1---W + 1--W + + A02 + P1 + A02 + 2.0 + + + A07 + AMP + A01 + 2.0 + + + + + ... + +``` +CNECs are defined in Monitored_Series elements, in B56 or B57 Series. A CNEC has one registered resource that defines its network element via its mrID. The optimization_MarketObjectStatus indicates if the CNEC is monitored or optimized. + +As it is defined in the CRAC model, a CNEC is associated to a state. If the Series containing the Monitored_Series has one or many Contingency_Series that have previously been [correctly defined](#contingencies), CNECs shall be created after these referenced contingencies. When no Contingency_Series are present in this Series, CNECs shall be created after all the contingencies present in the CRAC. The Measurements tags define the instants on which CNECs are defined via the measurementType tag, and the CNEC's threshold values. + +Finally, a CNEC can be named in the following way : _[network element name] - [side (placeholder if the branch is a TieLine)] - [direction in which the CNEC is monitored (placeholder)] - [monitored (placeholder for MNECs)] - [contingency (placeholder for when a contingency is defined.)] - [instant]_. + +### AngleCnecs + +```xml + + Angle1 + B56 + Angle1-name + A52 + + AngleCnec1 + B87 + AngleCnec1-name + DD + 30 + + networkElementId + RegisteredResource1 + A47 + + + networkElementId + RegisteredResource2 + A46 + + + + ... + + + ... + + +``` +AngleCnecs are easily distinguishable thanks to the AdditionalConstraint_Series tag. They define an AngleCnec in curative with an importing element, an exporting element (cf. the two registered resources) and with a threshold with a max bound defined by quantity. +In the CIM CRAC, AngleCnecs are actually defined with their corresponding remedial actions in B56 Series (ie Remedial Action series). The Contingency_Series (unique) refers to the contingency after which the AngleCnec is monitored. + +### VoltageCnecs + +[VoltageCnecs are defined in the CimCracCreationParameters](creation-parameters.md#voltage-cnecs-creation-parameters). +Nevertheless, they are imported via the CimCracCreator because that's where the information on which contingencies are imported lies. +Only voltage CNECs with contingencies that were previously correctly defined shall be imported. + +## Remedial Actions + +Remedial actions are listed in Series of business type B56. + +```xml + + RA-Series-1 + B56 + RA_SERIES + Z01 + βšͺOPTIONAL + ... + + βšͺOPTIONAL + ... + + + RTE-PRA_1 + RTE preventive remedial action number 1 + B59 + A18 + A39 + ... + βšͺOPTIONAL + 10YFR-XXX------C + + + ... + +``` +BusinessType in B56 series should always be B59. In RemedialAction_Series, the applicationMode_MarketObjectStatus defines the Remedial Action's instant : +- Preventive : A18 +- Curative : A19 +- Preventive and curative : A27 +- Auto : A20. + +By default, the operator is read from the RemedialAction_Series' mRID, as the string that precedes the first "-" character. In the example above, the operator would be "RTE". + +RemedialAction_Series may also contain Contingency_Series, Monitored_Series and Shared_Domain tags. Remedial actions' [usage rules](json.md#remedial-actions-and-usages-rules) will be defined depending on these tags: +- RemedialAction_Series that don't have any Monitored_Series children tags nor any Shared_Domain tags define **FreeToUse** remedial actions. +- When Monitored_Series tags exist, they define CNECs for which the remedial action series is available. These CNECs could have been defined previously in B57 series, or they are only defined in this B56 series following the [same logic described previously](#cnecs). When the RemedialAction_Series also contains a Contingency_Series, the only CNECs from the Monitored_Series tags that will be considered are those that list CNECs defined with a contingency from the Contingency_Series. For each remaining CNEC, the remedial action is defined with a **OnFlowConstraint** on the remedial action's instant. +- When the RemedialAction_Series has no Contingency_Series, no Monitored_Series, and a Shared_Domain tag, the Shared_Domain tag must be taken into account. It represents a country. Then, the remedial action is defined with a **OnFlowConstraintInCountry** on the remedial action's instant. + +Some remedial actions may have to be aligned in order to keep the same set-point value. +When it's the case, this information is retrieved [from the CracCreationParameters file](creation-parameters.md#range-action-groups-cim) +and the remedial actions are defined with a common groupId. + +### PST Range Actions + +```xml + + RA-Series-1 + B56 + RA_AFTER_ALL_CONTINGENCIES + Z01 + + PRA_1 + PRA_1 + B59 + A18 + A39 + + networkElementId + RA1-name + A06 + 1------0 + 1------0 + A26 + 33.0 + 1.0 + C62 + + + ... + +``` + +PST Range Actions have a unique RegisteredResource with A06 psrType, that stands for phase shift transformer. They can be defined with a range, rangeType being specified by the marketObjectStatus and min and max range values being defined by resourceCapacity min and max capacities. + +### Network Actions + +Network actions have one or more registered resources, that represent elementary actions. Each elementary action's type is defined by its psrType : +- **pst set-point** elementary actions have a A06 psrType, that stands for phase shift transformer. They differ from range actions as they have a specific set-point instead of an allowed range. That's why they have a default capacity tag instead of a minimumCapacity and/or a maximumCapacity tag. + +```xml + + RA-Series-1 + B56 + RA_1 + Z01 + + ... + + networkElementId + RA1-name + A06 + 1------0 + 1------0 + A25 + 11 + C62 + + ... + + ... + +``` + +- **injection set-point** elementary actions have a A04 or a A05 psrType, that respectively stand for generation and load. In a similar way to pst set-points, injection set-points do not have a minimumCapacity nor a maximumCapacity, but they have a defaultCapacity when the marketObjectStatus is A26 (stands for ABSOLUTE) with unitSymbol MAW. The marketObjectStatus may also be A23 for STOP. In that case, no defaultCapacity may be present. + +```xml + + RA-Series-1 + B56 + RA_1 + Z01 + + ... + + networkElementId + RA1-name + A04 + 10YPT-XXX------W + 10YPT-XXX------W + A26 + 100 + MAW + + ... + + ... + +``` + +- **topological** elementary actions have a A01, AO2, A07 or a B24 psrType, that respectively stand for tie-line, line, circuit breaker and transformer. In a similar way to other elementary actions, topological elementary actions do not have a minimumCapacity nor a maximumCapacity. Since they aren't defined by a set-point, they don't have a defaultCapacity either. They are entirely defined by the marketObjectStatus : A21 for OPEN, and A22 for CLOSE. + +```xml + + RA-Series-1 + B56 + RA_1 + Z01 + + ... + + networkElementId + RA1-name + A07 + 10YES-XXX------0 + 10YES-XXX------0 + A22 + + ... + + ... + +``` +A network action is imported if all of its elementary actions are imported. + +### HVDC Range Actions + +In the CIM CRAC format as it is actually used, the HVDC remedial action is defined in two separate remedial actions, each representing one direction: +- the first RemedialAction_Series is a range action in the A -> B direction, with 0 to XXX MW available. +- the second RemedialAction_Series is a range action in the B -> A direction, with 0 to XXX MW available. + +Each of these RemedialAction_Series can contain 4 RegisteredResources, allowing to use 2 HVDC lines as a remedial action group (i.e. setting both lines to same set-point): +- the first RegisteredResource sets the HVDC line #1 to "active power set-point" mode. +- the second RegisteredResource defines the allowed set-point range on the HVDC line #1. +- the third RegisteredResource sets the HVDC line #2 to "active power set-point" mode. +- the fourth RegisteredResource defines the allowed set-point range on the HVDC line #2. + +In the end, two HVDC range actions with an absolute range of -XXX MW to XXX MW each are defined, on both HVDC lines. These HVDC range actions are aligned, i.e. they share the same group ID. That means that they must have the same set-point. + +## Extra rules + +In order to ensure the imported CRAC is usable in the RAO, FARAO implements the following special rules: +- Hybrid (range-actions + network-actions) remedial actions are prohibited. +- If AUTO CNECs exist without any automaton that can eventually secure them, these CNECs are duplicated in the + outage instant in order to be secured by the preventive RAO. +- HVDC set-point remedial actions that require the deactivation of [angle-droop active power control](https://www.powsybl.org/pages/documentation/grid/model/extensions.html#hvdc-angle-droop-active-power-control) + (AC-emulation) are only supported at an auto instant. diff --git a/docs/input-data/crac/creation-context.md b/docs/input-data/crac/creation-context.md new file mode 100644 index 0000000000..2bab42e04b --- /dev/null +++ b/docs/input-data/crac/creation-context.md @@ -0,0 +1,527 @@ +# CRAC creation context + +## Introduction +When FARAO tries to import a native CRAC file ([FlowBasedConstraint](fbconstraint), [CSE](cse), [CIM](cim), ...) +into an [internal CRAC format](json), some data transformation can happen, and data present in the final CRAC object +will not be a "one-to-one" exact representation of the data in the original file. +This can be an issue for the final user, as [querying the RAO result file or object](https://farao-community.github.io/docs/output-data/rao-result-json#contents) +needs knowledge of the artefacts FARAO created during CRAC creation. +The [CracCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-api/src/main/java/com/powsybl/openrao/data/craccreation/creator/api/CracCreationContext.java) +classes produced by the different CRAC creators allow the user to access meta-information +about the CRAC creation process, and to map the original file to the created artifacts in the FARAO object, or to +error messages if some objects could not be imported. +This is particularly useful if the user needs to export the RAO result in a format different from [FARAO's internal format](https://farao-community.github.io/docs/output-data/rao-result-json), +and to reference CNECs and remedial actions as they were defined in the original (native) CRAC file. +Many implementations of CracCreationContext exist, depending on the original format. Every implementation has its own +specific API. CracCreationContexts are the main output of CracCreators. +```java +Network network = ... +NativeCrac nativeCrac = NativeCracImporters.importData(Paths.get("/example_file.xml")); +OffsetDateTime timestamp = ... +CracCreationContext cracCreationContext = CracCreators.createCrac(nativeCrac, network, timestamp); +``` +![CracCreationContext inheritance](/_static/img/CracCreationContext.png) + +## Non-specific information +All CracCreationContext implementations present the following information. + +### CRAC creation success +A simple boolean set to true if a FARAO CRAC could be created from the native CRAC file. +```java +boolean success = cracCreationContext.isCreationSuccessful(); +``` + +### CRAC object +The created CRAC object, to be used in the RAO. +```java +Crac crac = cracCreationContext.getCrac(); +``` + +### Timestamp +When applicable, this field contains the timestamp for which the CRAC has been created from the original CRAC file (as +some CRAC formats, such as [FlowBasedConstraint](fbconstraint), can support constraint definition for multiple timestamps). +This field can be useful if the timestamp needs to be exported in a custom results file. +```java +cracCreationContext.getTimeStamp(); +``` + +### Network name +Contains the name of the network that was used to create the CRAC object. +```java +cracCreationContext.getNetworkName(); +``` + +### CRAC creation report +A textual report that can usefully be logged. It contains information about elements that were ignored or modified in the +original CRAC. +The report's lines all begin with one of these tags: +- **[ERROR]**: happens when a CRAC could not be created (e.g. if the user tried to import a [FlowBasedConstraint](fbconstraint) +file without defining a timestamp, or a [CSE](cse) file with a non-UCTE network file, etc.) +- **[REMOVED]**: happens when FARAO ignores elements of the CRAC because they cannot be imported, or because they are not relevant +for the RAO (e.g. if a contingency is defined on an element that doesn't exist in the network, or if a CNEC is neither +optimized nor monitored, etc.) +- **[ADDED]**: happens if FARAO decides to add elements that were not explicitly defined in the original file (e.g. if the +CRAC contains AUTO CNECs without any remedial action associated, FARAO will automatically duplicate them in the outage +instant in order to secure them during the preventive RAO) +- **[ALTERED]**: happens if FARAO imports an element after altering it or ignoring some of its components (e.g. if a monitored +element shall be so after multiple contingencies, among which some were not imported for any reason, then only valid +contingencies will be used for the created CNECs) +- **[WARN]**: non-critical warnings (e.g. if the user defined a timestamp for a CRAC format that doesn't require one, the +timestamp is ignored and a warning is logged) +- **[INFO]**: non-critical information + +The final user shall check these messages to ensure that their CRAC file is well-defined. +```java +cracCreationContext.getCreationReport().printCreationReport(); +``` + +## UCTE implementation +A common UCTE interface [UcteCracCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-api/src/main/java/com/powsybl/openrao/data/craccreation/creator/api/stdcreationcontext/UcteCracCreationContext.java) +has been defined in order to collect the common fields a CracCreationContext implementation should hold when created using a **UCTE** network. +Of course, not all CRAC formats use UCTE convention, so not all CRAC formats can implement this UCTE interface. +Currently, this interface is implemented by [FlowBasedConstraint](fbconstraint) and [CSE](cse) crac creators. +It has all the [non-specific](#non-specific-information) features, plus the following. + +### Branch CNEC creation contexts +The [BranchCnecCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-api/src/main/java/com/powsybl/openrao/data/craccreation/creator/api/stdcreationcontext/BranchCnecCreationContext.java) +contains information about the creation of CNECs in FARAO. One BranchCreationContext is created for every native CNEC-equivalent +element in the original CRAC, that can be uniquely identified. It holds the following information: +- **NativeId** is the unique identifier of the native object in the original CRAC. Depending on the CRAC implementation, +FARAO can construct this by concatenating multiple elements in order to ensure the ID is unique in the file. +- **isImported** is a boolean equal to true if FARAO was able to import one or multiple CNECs from this element. +- **isAltered** is a boolean equal to true if FARAO had to alter some elements of this CNEC when importing it. +- **ImportStatus** contains further information about the import status of the element (see [appendix](#elementary-import-status)) +- **ImportStatusDetail** is a user-friendly message explaining why the element has not been imported (if applicable) +- **NativeBranch** is the UCTE branch referred to in the original CRAC, with a "from" node, a "to" node, and a suffix (order code or alias) +- **isBaseCase** is a boolean equal to true if the CNEC has been created for the preventive instant +- **ContingencyId** (if present) is the ID of the contingency for which the CNEc is monitored +- **CreatedCnecIds** holds the ID(s) of the FARAO CNEC(s) that were created for this native critical branch. These are the +IDs the user should use to query the internal CRAC & RaoResult objects. +- **isDirectionInvertedInNetwork** is a boolean equal to true if the from/to in the original CRAC are the inverse of the +PowSyBl network's from/to. This means that FARAO had to invert the branch when importing it (in order to be coherent with the network) +as well as its flow constraints, and that the flow results in the RaoResult will be inverted in regard to the original CRAC's convention. +The user should be careful to invert these results before exploiting them. + +Here is a complete example of BranchCnecCreationContext usage to export user-comprehensible RAO results: + +```java +UcteCracCreationContext ucteCracCreationContext = ... +RaoResult raoResult = ... + +// Do a custom results export of all native CNEC results +ucteCracCreationContext.getBranchCnecCreationContexts().foreach(context -> printSomeResults(context, ucteCracCreationContext, raoResult)); + +// Query the results of a specific native CNEC called "BranchCnecFR_1" +BranchCnecCreationContext context = ucteCracCreationContext.getBranchCnecCreationContext("BranchCnecFR_1"); +printSomeResults(context, ucteCracCreationContext, raoResult); + +void printSomeResults(BranchCnecCreationContext context, CracCreationContext cracCreationContext, RaoResult raoResult) { + System.out.println(String.format("Native critical branch ID: %s", context.getNativeId())); + System.out.println(String.format("Native line: %s %s %s", context.getNativeBranch().getFrom(), context.getNativeBranch().getTo(), context.getNativeBranch().getSuffix())); + if (!context.isImported()) { + System.out.println(String.format("The native branch could not be imported by FARAO for the following reason: %s - %s", context.getImportStatus(), context.getImportStatusDetail())); + System.out.println("The element has been ignored by the RAO, we cannot access any result for it!"); + return; + } + double flowMultiplier; + if (context.isDirectionInvertedInNetwork()) { + System.out.println(String.format("In the network the line is called %s %s %s, so all its results will be inverted!", context.getNativeBranch().getTo(), context.getNativeBranch().getFrom(), context.getNativeBranch().getSuffix())); + flowMultiplier = -1.; + } else { + flowMultiplier = 1.; + } + if (context.isBaseCase()) { + System.out.println("Monitored in preventive only"); + } else { + System.out.println(String.format("Monitored after contingency: %s", context.getContingencyId().get())); + } + context.getCreatedCnecsIds().entrySet().forEach(entry -> { + System.out.println(String.format("Created CNEC for instant %s: %s", entry.getKey(), entry.getValue())); + FlowCnec flowCnec = cracCreationContext.getCrac().getFlowCnec(entry.getValue()); + System.out.println(String.format("The left-side flow on this native critical branch after RAO is: %.2f A", flowMultiplier * raoResult.getFlow(OptimizationState.afterOptimizing(flowCnec.getState()), flowCnec, Side.LEFT, Unit.AMPERE))); + System.out.println(String.format("The right-side flow on this native critical branch after RAO is: %.2f A", flowMultiplier * raoResult.getFlow(OptimizationState.afterOptimizing(flowCnec.getState()), flowCnec, Side.RIGHT, Unit.AMPERE))); + System.out.println(String.format("The flow margin on this native critical branch after RAO is: %.2f A", raoResult.getMargin(OptimizationState.afterOptimizing(flowCnec.getState()), flowCnec, Unit.AMPERE))); + } + ); +} +``` + +### Remedial action creation contexts +The [RemedialActionCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-api/src/main/java/com/powsybl/openrao/data/craccreation/creator/api/stdcreationcontext/RemedialActionCreationContext.java) +contains information about the creation of remedial actions in FARAO. One RemedialActionCreationContext is created for every native +remedial-action element in the original CRAC, that can be uniquely identified. It holds the following information: +- **NativeId** is the unique identifier of the native object in the original CRAC. Depending on the CRAC implementation, + FARAO can construct this by concatenating multiple elements in order to ensure the ID is unique in the file. +- **isImported** is a boolean equal to true if FARAO was able to import a remedial action from this element. +- **isAltered** is a boolean equal to true if FARAO had to alter some elements of this remedial action when importing it. +- **ImportStatus** contains further information about the import status of the element (see [appendix](#elementary-import-status)) +- **ImportStatusDetail** is a user-friendly message explaining why the element has not been imported (if applicable) +- **CreatedRAId** holds the ID of the FARAO remedial action that was created from this native element. This is the +ID the user should use to query the internal CRAC & RaoResult objects. + +Here is a complete example of RemedialActionCreationContext usage to export user-comprehensible RAO results: + +```java +UcteCracCreationContext ucteCracCreationContext = ... +RaoResult raoResult = ... + +// Do a custom results export of all native remedial action results +ucteCracCreationContext.getRemedialActionCreationContexts().foreach(context -> printSomeResults(context, ucteCracCreationContext, raoResult)); + +// Query the results of a specific native remedial action called "RemedialAction656" +RemedialActionCreationContext context = ucteCracCreationContext.getRemedialActionCreationContext("RemedialAction656"); +printSomeResults(context, ucteCracCreationContext, raoResult); + +void printSomeResults(RemedialActionCreationContext context, CracCreationContext cracCreationContext, RaoResult raoResult) { + System.out.println(String.format("Native remedial action ID: %s", context.getNativeId())); + if (!context.isImported()) { + System.out.println(String.format("The remedial action could not be imported by FARAO for the following reason: %s - %s", context.getImportStatus(), context.getImportStatusDetail())); + System.out.println("The element has been ignored by the RAO, we cannot access any result for it!"); + return; + } + System.out.println(String.format("The remedial action created in the FARAO CRAC is called: %s", context.getCreatedRAId())); + RemedialAction remedialAction = cracCreationContext.getCrac().getRemedialAction(context.getCreatedRAId()); + cracCreationContext.getCrac().getStates().forEach(state -> { + String stateDescription = String.format("instant %s%s", state.getInstant(), state.isPreventive() ? "" : " after contingency " + state.getContingency().get().getId()); + if (raoResult.getActivatedNetworkActionsDuringState(state).contains(remedialAction)) { + // Remedial action is a network action, it has been activated in this state + System.out.println(String.format("The network action has been selected by RAO at %s", stateDescription)); + } else if (raoResult.getActivatedRangeActionsDuringState(state).contains(remedialAction)) { + // Remedial action is a range action, it has been activated in this state. We can query its optimal set-point. + System.out.println(String.format("The range action has been selected by RAO at %s, with optimal set-point %.2f", stateDescription, raoResult.getOptimizedSetPointOnState(state, (RangeAction) remedialAction))); + } + }); +} +``` + +## FlowBasedConstraint implementation +The [FbConstraintCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-fb-constraint/src/main/java/com/powsybl/openrao/data/craccreation/creator/fbconstraint/craccreator/FbConstraintCreationContext.java) +is a [UcteCracCreationContext](#ucte-implementation) implementation with no extra features. + +## CSE implementation +The [CseCracCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-cse/src/main/java/com/powsybl/openrao/data/craccreation/creator/cse/CseCracCreationContext.java) +is a [UcteCracCreationContext](#ucte-implementation) implementation with one extra feature for contingencies. + +### Outage creation contexts +The [CseOutageCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-cse/src/main/java/com/powsybl/openrao/data/craccreation/creator/cse/outage/CseOutageCreationContext.java) +contains information about the creation of contingencies in FARAO. One CseOutageCreationContext is created for every native +"Outage" element in the original CSE CRAC, that can be uniquely identified. It holds the following information: +- **NativeId** is the unique identifier of the native Outage (contained in the "Name" tag) +- **isImported** is a boolean equal to true if FARAO was able to import a contingency from this element. +- **isAltered** is a boolean equal to true if FARAO had to alter some elements of this contingency when importing it. +- **ImportStatus** contains further information about the import status of the element (see [appendix](#elementary-import-status)) +- **ImportStatusDetail** is a user-friendly message explaining why the element has not been imported (if applicable) +- **CreatedContingencyId** holds the ID of the FARAO contingency that was created from this native element. This is the +ID the user should use to query the internal CRAC & RaoResult objects. + +Here is a complete example of CseOutageCreationContext usage: + +```java +CseCracCreationContext cseCracCreationContext = ... +RaoResult raoResult = ... + +// Print some information about all native Outage elements +cseCracCreationContext.getOutageCreationContexts().foreach(context -> printSomeInformation(context, cseCracCreationContext, raoResult)); + +// Query the information about a specific Outage called "Outage123" +CseOutageCreationContext context = cseCracCreationContext.getRemedialActionCreationContext("Outage123"); +printSomeInformation(context, cseCracCreationContext, raoResult); + +void printSomeInformation(CseOutageCreationContext context, CracCreationContext cracCreationContext, RaoResult raoResult) { + System.out.println(String.format("Native outage ID: %s", context.getNativeId())); + if (!context.isImported()) { + System.out.println(String.format("The outage could not be imported by FARAO for the following reason: %s - %s", context.getImportStatus(), context.getImportStatusDetail())); + System.out.println("The element has been ignored by the RAO, we cannot access any more information for it!"); + return; + } + System.out.println(String.format("The contingency created in the FARAO CRAC is called: %s", context.getCreatedContingencyId())); + Contingency contingency = cracCreationContext.getCrac().getContingency(context.getCreatedContingencyId()); + cracCreationContext.getCrac().getStates(contingency).forEach(state -> { + System.out.println(String.format("The contingency is monitored at instant %s", state.getInstant())); + System.out.println(String.format("At this instant, and after this contingency, %s CNECs are monitored by the RAO", cracCreationContext.getCrac().getCnecs(state).size())); + }); +} +``` + +## CIM implementation +The [CimCracCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-cim/src/main/java/com/powsybl/openrao/data/craccreation/creator/cim/craccreator/CimCracCreationContext.java) +is not a UcteCracCreationParameters implementation. +It has all the [non-specific](#non-specific-information) features, plus the following. + +### Contingency series creation contexts +The [CimContingencyCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-cim/src/main/java/com/powsybl/openrao/data/craccreation/creator/cim/craccreator/contingency/CimContingencyCreationContext.java) +contains information about the creation of contingencies in FARAO. One CimContingencyCreationContext is created for every +[B55](cim.md#contingencies) "Contingency_Series" element in the original CSE CRAC, that can be uniquely identified. +It holds the following information: +- **NativeId** is the unique identifier of the native Contingency_Series (contained in the "mRID" tag) +- **NativeName** is the user-friendly name of the native Contingency_Series (contained in the "name" tag) +- **isImported** is a boolean equal to true if FARAO was able to import a contingency from this element. +- **isAltered** is a boolean equal to true if FARAO had to alter some elements of this contingency when importing it. +- **ImportStatus** contains further information about the import status of the element (see [appendix](#elementary-import-status)) +- **ImportStatusDetail** is a user-friendly message explaining why the element has not been imported (if applicable) +- **CreatedContingencyId** holds the ID of the FARAO contingency that was created from this native element. This is the + ID the user should use to query the internal CRAC & RaoResult objects. + +Here is a complete example of CimContingencyCreationContext usage: + +```java +CimCracCreationContext cimCracCreationContext = ... +RaoResult raoResult = ... + +// Print some information about all native Contingency_Series elements +cimCracCreationContext.getContingencyCreationContexts().foreach(context -> printSomeInformation(context, cimCracCreationContext, raoResult)); + +// Query the information about a specific Contingency_Series with mRID "CO-125" +RemedialActionCreationContext context = cimCracCreationContext.getContingencyCreationContextById("CO-125"); +printSomeInformation(context, cimCracCreationContext, raoResult); + +// Query the information about a specific Contingency_Series with name "N-1 on FR-ES branch" +RemedialActionCreationContext context = cimCracCreationContext.getContingencyCreationContextByName("N-1 on FR-ES branch"); +printSomeInformation(context, cimCracCreationContext, raoResult); + +void printSomeInformation(CimContingencyCreationContext context, CracCreationContext cracCreationContext, RaoResult raoResult) { + System.out.println(String.format("Native Contingency_Series ID: %s", context.getNativeId())); + System.out.println(String.format("Native Contingency_Series name: %s", context.getNativeName())); + if (!context.isImported()) { + System.out.println(String.format("The Contingency_Series could not be imported by FARAO for the following reason: %s - %s", context.getImportStatus(), context.getImportStatusDetail())); + System.out.println("The element has been ignored by the RAO, we cannot access any more information for it!"); + return; + } + System.out.println(String.format("The contingency created in the FARAO CRAC is called: %s", context.getCreatedContingencyId())); + Contingency contingency = cracCreationContext.getCrac().getContingency(context.getCreatedContingencyId()); + cracCreationContext.getCrac().getStates(contingency).forEach(state -> { + System.out.println(String.format("The contingency is monitored at instant %s", state.getInstant())); + System.out.println(String.format("At this instant, and after this contingency, %s CNECs are monitored by the RAO", cracCreationContext.getCrac().getCnecs(state).size())); + }); +} +``` + +### Monitored series creation contexts +The [MonitoredSeriesCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-cim/src/main/java/com/powsybl/openrao/data/craccreation/creator/cim/craccreator/cnec/MonitoredSeriesCreationContext.java) +contains information about the creation of CNECs in FARAO. One MonitoredSeriesCreationContext is created for every native +[B57](cim.md#flowcnecs) "Monitored_Series" in the original CRAC, that can be uniquely identified. It holds the following information: +- **NativeId** is the unique identifier of the native Monitored_Series (contained in the "mRID" tag) +- **NativeName** is the user-friendly name of the native Monitored_Series (contained in the "name" tag) +- **NativeResourceId** is the ID of the network element monitored by the Monitored_Series (contained in the "RegisteredResource/mRID" tag) +- **NativeResourceName** is the user-friendly name of the network element monitored by the Monitored_Series (contained in the "RegisteredResource/name" tag) +- **isImported** is a boolean equal to true if FARAO was able to import one or multiple CNECs from this element. +- **isAltered** is a boolean equal to true if FARAO had to alter some elements of this CNEC when importing it. +- **ImportStatus** contains further information about the import status of the element (see [appendix](#elementary-import-status)) +- **ImportStatusDetail** is a user-friendly message explaining why the element has not been imported (if applicable) +- **CreatedCnecIds** holds the ID(s) of the FARAO CNEC(s) that were created for this native critical branch. These are the + IDs the user should use to query the internal CRAC & RaoResult objects. +- **MeasurementCreationContexts** is a set + of [MeasurementCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-cim/src/main/java/com/powsybl/openrao/data/craccreation/creator/cim/craccreator/cnec/MeasurementCreationContext.java) + objects. One MeasurementCreationContexts is created for every "Measurements" tag inside the Monitored_Series. In fact, + one "Measurement" can create multiple FARAO CNECs, depending on the contingencies and instants defined for the + Monitored_Series in the CIM CRAC (see [here](cim.md#flowcnecs) fore more detail). Every MeasurementCreationContext + contains the following information: + - **isImported** is a boolean equal to true if FARAO was able to import at least one CNEC from this "Measurements". + - **ImportStatus** contains further information about the import status of the element (see [appendix](#elementary-import-status)) + - **ImportStatusDetail** is a user-friendly message explaining why the element has not been imported (if applicable) + - **CnecCreationContexts** is a map containing, for every state (i.e. (Instant, Contingency) pair), up to one + [CnecCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-cim/src/main/java/com/powsybl/openrao/data/craccreation/creator/cim/craccreator/cnec/CnecCreationContext.java) + . Every CnecCreationContext holds the following information: + - **isImported** is a boolean equal to true if FARAO was able to import a CNEC from this "Measurements", for the given contingency & instant. + - **ImportStatus** contains further information about the import status of the element (see [appendix](#elementary-import-status)) + - **CreatedCnecIds** holds the ID of the FARAO CNEC that was created (if applicable) from this "Measurements", for + the given contingency & instant. This is the ID the user should use to query the internal CRAC & RaoResult objects. + +Here is a complete example of MonitoredSeriesCreationContext usage to export user-comprehensible RAO results: + +```java +CimCracCreationContext cimCracCreationContext = ... +RaoResult raoResult = ... + +// Do a custom results export of all native Monitored_Series results +cimCracCreationContext.getMonitoredSeriesCreationContexts().foreach(context -> printSomeResults(context, cimCracCreationContext, raoResult)); + +// Query the results of a specific Monitored_Series with mRID "MR-10" +MonitoredSeriesCreationContext context = cimCracCreationContext.getMonitoredSeriesCreationContext("MR-10"); +printSomeResults(context, cimCracCreationContext, raoResult); + +void printSomeResults(MonitoredSeriesCreationContext context, CracCreationContext cracCreationContext, RaoResult raoResult) { + System.out.println(String.format("Native Monitored_Series ID & name: %s - %s", context.getNativeId(), context.getNativeName())); + System.out.println(String.format("Monitored network element ID & name: %s - %s", context.getNativeResourceId(), context.getNativeResourceName())); + if (!context.isImported()) { + System.out.println(String.format("The Monitored_Series could not be imported by FARAO for the following reason: %s - %s", context.getImportStatus(), context.getImportStatusDetail())); + System.out.println("The element has been ignored by the RAO, we cannot access any result for it!"); + return; + } + System.out.println(String.format("This Monitored_Series created %s CNECs in the FARAO CRAC", context.getCreatedCnecIds().size())); + context.getMeasurementCreationContexts().forEach(measurementContext -> { + if (!measurementContext.isImported()) { + System.out.println(String.format("One Measurement has not been imported for the following reason: %s - %s", measurementContext.getImportStatus(), measurementContext.getImportStatusDetail())); + } else { + measurementContext.getCnecCreationContexts().forEach((k, v) -> { + if (v.isImported()) { + System.out.println(String.format("Created CNEC ID for instant %s, after contingency %s, is %s", k.getKey(1), k.getKey(0), v.getCreatedCnecId())); + FlowCnec flowCnec = cracCreationContext.getCrac().getFlowCnec(v.getCreatedCnecId()); + System.out.println(String.format("Its flow margin after RAO is: %.2f MW", raoResult.getMargin(OptimizationState.afterOptimizing(flowCnec.getState()), flowCnec, Unit.MEGAWATT))); + } else { + System.out.println(String.format("The CNEC could not be created for instant %s, after contingency %s, for the following reason: %s - %s", k.getKey(1), k.getKey(0), v.getImportStatus(), v.getImportStatusDetail())); + } + }); + } + }); +} +``` + +### Angle CNEC creation contexts +The [AngleCnecCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-cim/src/main/java/com/powsybl/openrao/data/craccreation/creator/cim/craccreator/cnec/AngleCnecCreationContext.java) +contains information about the creation of angle CNECs in FARAO. One AngleCnecCreationContext is created for every native +[B56](cim.md#anglecnecs) "AdditionalConstraint_Series" in the original CRAC, that can be uniquely identified. +It holds the following information: +- **NativeId** is the unique identifier of the native AdditionalConstraint_Series (contained in the "mRID" tag) +- **isImported** is a boolean equal to true if FARAO was able to import one or multiple CNECs from this element. +- **ImportStatus** contains further information about the import status of the element (see [appendix](#elementary-import-status)) +- **ImportStatusDetail** is a user-friendly message explaining why the element has not been imported (if applicable) +- **CreatedCnecId** is the ID of the FARAO angle CNEC that was created for this AdditionalConstraint_Series. + This is the ID the user should use to query the internal CRAC & RaoResult objects. +- **ContingencyId** holds the ID of the contingency for this angle CNEC. It can be used with internal objects. + +Here is a complete example of AngleCnecCreationContext usage to export user-comprehensible RAO results: + +```java +CimCracCreationContext cimCracCreationContext = ... +RaoResult raoResult = ... + +// Do a custom results export of all native AdditionalConstraint_Series results +cimCracCreationContext.getAngleCnecCreationContexts().foreach(context -> printSomeResults(context, cimCracCreationContext, raoResult)); + +// Query the results of a specific AdditionalConstraint_Series with mRID "AC-100" +AngleCnecCreationContext context = cimCracCreationContext.getAngleCnecCreationContext("AC-100"); +printSomeResults(context, cimCracCreationContext, raoResult); + +void printSomeResults(AngleCnecCreationContext context, CracCreationContext cracCreationContext, RaoResult raoResult) { + System.out.println(String.format("AdditionalConstraint_Series ID: %s", context.getNativeId())); + if (!context.isImported()) { + System.out.println(String.format("The angle CNEC could not be imported by FARAO for the following reason: %s - %s", context.getImportStatus(), context.getImportStatusDetail())); + System.out.println("The element has been ignored by the RAO, we cannot access any result for it!"); + return; + } + System.out.println(String.format("The angle CNEC created in the FARAO CRAC is called: %s", String.join(", ", context.getCreatedAngleCnecId()))); + AngleCnec angleCnec = cracCreationContext.getCrac().getAngleCnec(context.getCreatedAngleCnecId()); + // Print its angle value (note that this will not work with the default search-tree RAO implementation) + System.out.println(String.format("Its angle value after RAO is: %.2f", raoResult.getAngle(OptimizationState.afterOptimizing(angleCnec.getState()), angleCnec, Unit.DEGREE))); +} +``` + +### Voltage CNEC creation contexts +The [VoltageCnecCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-cim/src/main/java/com/powsybl/openrao/data/craccreation/creator/cim/craccreator/cnec/VoltageCnecCreationContext.java) +contains information about the creation of angle CNECs in FARAO. One VoltageCnecCreationContext is created for every voltage +CNEC that should be created, as configured in the [CimCracCreationParameters](creation-parameters.md#voltage-cnecs-creation-parameters). +It holds the following information: +- **NativeNetworkElementId** is the unique identifier of the network element that is monitored +- **Instant** is the instant for which the CNEC is created +- **NativeContingencyName** is the name of the contingency for which the CNEC is created (if instant is not preventive), + as defined in the "name" field of the [B55](cim.md#contingencies) Contingency_Series +- **isImported** is a boolean equal to true if FARAO was able to import the voltage CNEC +- **ImportStatus** contains further information about the import status of the element (see [appendix](#elementary-import-status)) +- **ImportStatusDetail** is a user-friendly message explaining why the element has not been imported (if applicable) +- **CreatedCnecId** is the ID of the FARAO voltage CNEC that was created. + This is the ID the user should use to query the internal CRAC & RaoResult objects. + +Here is a complete example of VoltageCnecCreationContext usage to export user-comprehensible RAO results: + +```java +CimCracCreationContext cimCracCreationContext = ... +RaoResult raoResult = ... + +// Do a custom results export of all voltage CNECs results +cimCracCreationContext.getVoltageCnecCreationContexts().foreach(context -> printSomeResults(context, cimCracCreationContext, raoResult)); + +// Query the results of a specific voltage CNEC that was created for network element "ne1", at instant "curative", after contingency "co1" +VoltageCnecCreationContext context = cimCracCreationContext.getVoltageCnecCreationContext("ne1", Instant.CURATIVE, "co1"); +printSomeResults(context, cimCracCreationContext, raoResult); + +void printSomeResults(VoltageCnecCreationContext context, CracCreationContext cracCreationContext, RaoResult raoResult) { + System.out.println(String.format("Voltage CNEC for network element %s after contingency %s at instant %s", context.getNativeNetworkElementId(), context.getNativeContingencyName(), context.getInstant())); + if (!context.isImported()) { + System.out.println(String.format("The voltage CNEC could not be imported by FARAO for the following reason: %s - %s", context.getImportStatus(), context.getImportStatusDetail())); + System.out.println("The element has been ignored by the RAO, we cannot access any result for it!"); + return; + } + System.out.println(String.format("The voltage CNEC created in the FARAO CRAC is called: %s", String.join(", ", context.getCreatedCnecId()))); + VoltageCnec voltageCnec = cracCreationContext.getCrac().getVoltageCnec(context.getCreatedCnecId()); + // Print its voltage value (note that this will not work with the default search-tree RAO implementation) + System.out.println(String.format("Its angle value after RAO is: %.2f", raoResult.getVoltage(OptimizationState.afterOptimizing(voltageCnec.getState()), voltageCnec, Unit.KILOVOLT))); +} +``` + +### Remedial action series creation contexts +The CIM [RemedialActionSeriesCreationContext](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-cim/src/main/java/com/powsybl/openrao/data/craccreation/creator/cim/craccreator/remedialaction/RemedialActionSeriesCreationContext.java) +contains information about the creation of remedial actions in FARAO. One RemedialActionSeriesCreationContext is created for every +[B56](cim.md#remedial-actions) "RemedialAction_Series" element in the original CRAC, that can be uniquely identified. +It holds the following information: +- **NativeId** is the unique identifier of the native RemedialAction_Series (contained in the "mRID" tag) +- **isImported** is a boolean equal to true if FARAO was able to import a remedial action from this element. +- **isAltered** is a boolean equal to true if FARAO had to alter some elements of this remedial action when importing it. +- **ImportStatus** contains further information about the import status of the element (see [appendix](#elementary-import-status)) +- **ImportStatusDetail** is a user-friendly message explaining why the element has not been imported (if applicable) +- **isInverted** is a boolean equal to true if the imported remedial action had to be inverted with regard to the original + CRAC convention, in order to comply with the PowSyBl network convention (this is especially useful for HVDC range actions). + If this field is set to true, the user should be careful to invert results accordingly (see example below). +- **CreatedIds** holds the IDs of the FARAO remedial actions that were created from this native element (generally holds up + to one ID, except for HVDC range actions where it can hold multiple IDs). These are the IDs the user should use to query + the internal CRAC & RaoResult objects. + +Here is a complete example of RemedialActionSeriesCreationContext usage to export user-comprehensible RAO results: + +```java +CimCracCreationContext cimCracCreationContext = ... +RaoResult raoResult = ... + +// Do a custom results export of all native remedial action results +cimCracCreationContext.getRemedialActionSeriesCreationContexts().foreach(context -> printSomeResults(context, cimCracCreationContext, raoResult)); + +// Query the results of a specific RemedialAction_Series with mRID "PRA_5" +RemedialActionSeriesCreationContext context = cimCracCreationContext.getRemedialActionSeriesCreationContext("PRA_5"); +printSomeResults(context, cimCracCreationContext, raoResult); + +void printSomeResults(RemedialActionSeriesCreationContext context, CracCreationContext cracCreationContext, RaoResult raoResult) { + System.out.println(String.format("RemedialAction_Series ID: %s", context.getNativeId())); + if (!context.isImported()) { + System.out.println(String.format("The remedial action could not be imported by FARAO for the following reason: %s - %s", context.getImportStatus(), context.getImportStatusDetail())); + System.out.println("The element has been ignored by the RAO, we cannot access any result for it!"); + return; + } + System.out.println(String.format("The remedial action(s) created in the FARAO CRAC is (are) called: %s", String.join(", ", context.getCreatedIds()))); + context.getCreatedIds().forEach(createdRaId -> { + System.out.println(String.format("Remedial action %s:", createdRaId)); + RemedialAction remedialAction = cracCreationContext.getCrac().getRemedialAction(createdRaId); + cracCreationContext.getCrac().getStates().forEach(state -> { + String stateDescription = String.format("instant %s%s", state.getInstant(), state.isPreventive() ? "" : " after contingency " + state.getContingency().get().getId()); + if (raoResult.getActivatedNetworkActionsDuringState(state).contains(remedialAction)) { + // Remedial action is a network action, it has been activated in this state + System.out.println(String.format("The network action has been selected by RAO at %s", stateDescription)); + } else if (raoResult.getActivatedRangeActionsDuringState(state).contains(remedialAction)) { + // Remedial action is a range action, it has been activated in this state. We can query its optimal set-point. + int multiplier = context.isInverted() ? -1 : 1; + System.out.println(String.format("The range action has been selected by RAO at %s, with optimal set-point %.2f", stateDescription, multiplier * raoResult.getOptimizedSetPointOnState(state, (RangeAction) remedialAction))); + } + }); + }); +} +``` + +## Appendix +### Elementary import status +[ImportStatus](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-api/src/main/java/com/powsybl/openrao/data/craccreation/creator/api/ImportStatus.java) +is an enum field that can be used in the API to filter elements that were not imported for different reasons. +For instance, the user may choose to write information about CNECs that were not imported because they are not useful in +the RAO ("NOT_FOR_RAO"), but ignore the other ones. +Here are the possible values of this enum: +- **IMPORTED**: the element was successfully imported +- **ELEMENT_NOT_FOUND_IN_NETWORK**: the element references a network element that was not found in the network (e.g. a +critical branch defined on a line that does not exist in the PowSyBl network) +- **INCOMPLETE_DATA**: the element is missing crucial information needed to define a complete FARAO object (e.g. a flow +CNEC defined without a flow limit) +- **INCONSISTENCY_IN_DATA**: the element definition is inconsistent (e.g. a PST range action that is defined on a non-PST +network element) +- **NOT_YET_HANDLED_BY_FARAO**: the business element is not yet supported by FARAO (e.g. line impedance remedial-actions +are not yet supported) +- **NOT_FOR_RAO**: the element is ignored because it will not be used in the RAO (e.g. critical branches that are neither +optimized nor monitored) +- **NOT_FOR_REQUESTED_TIMESTAMP**: the element is ignored because it does not apply to the given timestamp +- **OTHER**: any error that does not fall into one of the categories above diff --git a/docs/input-data/crac/creation-parameters.md b/docs/input-data/crac/creation-parameters.md new file mode 100644 index 0000000000..299b35e12f --- /dev/null +++ b/docs/input-data/crac/creation-parameters.md @@ -0,0 +1,363 @@ +# CRAC creation parameters + +## Introduction +Native CRAC formats do not always hold all the information needed in order to conduct a precise remedial action optimisation. +For instance, when monitoring current flows (vs their limits) on lines, one can wonder if they shall monitor +the current on both sides of the line, on the left side only, or on the right side only. +In DC convention, it doesn't matter: it is enough for the RAO to monitor the left side, allowing it to have a smaller optimisation problem. +In AC convention, it is generally preferred to monitor both sides, as flows on both sides can be different because of losses. + +In FARAO's [internal CRAC format](json), it is possible to define which side(s) to monitor, and this is needed in the RAO. +However, no CRAC format actually defines this configuration, thus it is necessary to add an extra configuration object +when creating a CRAC object to be used in the RAO. +This is the purpose of FARAO's "CRAC creation parameters". + +## Creating a CracCreationParameters object +(and reading/writing it to a file). +Some examples: +```java +// Creating the object +CracCreationParameters parameters = new CracCreationParameters(); + +// Writing it to an output stream +OutputStream outputStreeam = ... +JsonCracCreationParameters.write(parameters, outputStream); + +// Reading an object from a file +Path jsonFilePath = ... +parameters = JsonCracCreationParameters.read(jsonFilePath); +``` + + +## Non-specific parameters +FARAO's [CracCreationParameters](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-api/src/main/java/com/powsybl/openrao/data/craccreation/creator/api/parameters/CracCreationParameters.java) +defines a few parameters needed for all native CRAC formats. + +### crac-factory +FARAO's [Crac](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac/crac-api/src/main/java/com/powsybl/openrao/data/cracapi/Crac.java) +object is actually just an interface, with a default implementation in [CracImpl](https://github.com/powsybl/powsybl-open-rao/tree/main/data/crac/crac-impl/src/main/java/com/powsybl/openrao/data/cracimpl). +As a FARAO toolbox user, you are allowed to define your own custom Crac implementation. This implementation shall be instanced using a [CracFactory](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac/crac-api/src/main/java/com/powsybl/openrao/data/cracapi/CracFactory.java). +FARAO's default implementation is [CracImplFactory](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac/crac-impl/src/main/java/com/powsybl/openrao/data/cracimpl/CracImplFactory.java). +Parameter "crac-factory" allows the user to define which CracFactory implementation (thus which Crac implementation) to +use. If you do not have a custom implementation (which should be the case of most users), set it to "CracImplFactory". + +### default-monitored-line-side +This parameter defines which side(s) of a line the RAO should monitor by default (side is defined as per [PowSyBl](https://www.powsybl.org/pages/documentation/) +convention), when optimizing line's flow margin. +Note that this parameter is ignored when the line side to monitor is defined by the native CRAC itself (e.g. when a +cross-border tie-line is monitored by one TSO only, then the RAO will automatically detect on which side this TSO is). +Possible values for this parameter are: +- **monitor-lines-on-left-side** to monitor lines on left side only (typically to be used in DC-loadflow mode) +- **monitor-lines-on-right-side** to monitor lines on right side only (alternatively in DC-loadflow mode) +- **monitor-lines-on-both-sides** to monitor lines on both sides; the flow limits defined in the native CRAC file will then +apply to both sides (typically to be used in AC-loadflow mode) + +> πŸ’‘ **NOTE** +> If you don't know which option to choose, it is safest to go with **monitor-lines-on-both-sides** + +### ra-usage-limits-per-instant +This parameter limits the usage of remedial actions for given instants. +The instant ID must match an ID of an instant in the CRAC. +If the given instant contains multiple states (possible for auto and curative instant), the given limits are applied independently on each state. +The RAs usage limits contain the following fields : + + - **max-ra :** + - Expected value: integer + - Default value: 2^32 -1 (max integer value) + - Usage: It defines the maximum number of remedial actions allowed for the given instant. The RAO will prioritize remedial actions that have the best impact on the minimum margin. + + - **max-tso :** + - Expected value: integer + - Default value: 2^32 -1 (max integer value) + - Usage: It defines the maximum number of TSOs that can apply remedial actions for the given instant. The RAO will choose the best TSOs combination to maximize the minimum margin. + + - **max-ra-per-tso :** + - Expected value: a map with string keys and integer values. The keys should be the same as the RAs’ operators as written in the CRAC file + - Default value: empty map + - Usage: It defines the maximum number of remedial actions allowed for each TSO, for the given instant. + The TSOs should be identified using the same IDs as in the CRAC. If a TSO is not listed in this map, then the number of its allowed RAs is supposed infinite. + + - **max-topo-per-tso :** + Exactly the same as **max-ra-per-tso** but it only concerns topological RAs + + - **max-pst-per-tso :** + Exactly the same as **max-ra-per-tso** but it only concerns PST RAs + +### complete example +::::{tabs} +:::{group-tab} JAVA API +```java +CracCreationParameters cracCreationParameters = new CracCreationParameters(); +cracCreationParameters.setCracFactoryName("CracImplFactory"); +cracCreationParameters.setDefaultMonitoredLineSide(CracCreationParameters.MonitoredLineSide.MONITOR_LINES_ON_BOTH_SIDES); +RaUsageLimits raUsageLimits = new RaUsageLimits(); +raUsageLimits.setMaxRa(10); +raUsageLimits.setMaxRaPerTso(Map.of("FR", 4, "BE", 6)) +cracCreationParameters.addRaUsageLimitsForAGivenInstant("curative", raUsageLimits); +``` +::: +:::{group-tab} JSON file +```json +{ + "crac-factory": "CracImplFactory", + "default-monitored-line-side" : "monitor-lines-on-both-sides", + "ra-usage-limits-per-instant" : [ { + "instant": "curative", + "max-ra" : 10, + "max-ra-per-tso" : {"FR": 4, "BE": 6} + } ] +} +``` +::: +:::: + +## CSE-specific parameters +The [CSE native crac format](cse) lacks important information that other formats don't. +The user can define a [CseCracCreationParameters](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-cse/src/main/java/com/powsybl/openrao/data/craccreation/creator/cse/parameters/CseCracCreationParameters.java) +extension to the CracCreationParameters object in order to define them. + +### range-action-groups (CSE) +The CSE native CRAC format does not allow defining [aligned range actions](introduction.md#range-action). This extra parameter +allows the user to do just that. +To use it, you have to define a list of strings containing the IDs of range actions that have to be aligned seperated by a +" + " sign; for example "range-action-1-id + range-action-17-id" and "range-action-8-id + range-action-9-id". +See [example below](#full-cse-example) for a better illustration. + +### bus-bar-change-switches +As explained in the CSE native CRAC format section [here](cse.md#bus-bar-change), bus-bar-change remedial actions are defined in FARAO +as [switch pair network actions](introduction.md#switch-pair). +These switches are not defined in the native CRAC nor in the original network, they should be created artificially in the +network and their IDs should be sent to the RAO. +This parameter allows the definition of the switch(es) to open and the switch(es) to close for every bus-bar change remedial action. +To use it, for every bus-bar-change remedial action ID, define the IDs of the pairs of switches to open/close. +See [example below](#full-cse-example) for a better illustration. + +### full CSE example +::::{tabs} +:::{group-tab} JAVA API +```java +// Create CracCreationParameters and set global parameters +CracCreationParameters cracCreationParameters = new CracCreationParameters(); +cracCreationParameters.setCracFactoryName("CracImplFactory"); +cracCreationParameters.setDefaultMonitoredLineSide(CracCreationParameters.MonitoredLineSide.MONITOR_LINES_ON_BOTH_SIDES); +// Create CSE-specific parameters +CseCracCreationParameters cseParameters = new CseCracCreationParameters(); +cseParameters.setRangeActionGroupsAsString(List.of("rangeAction3 + rangeAction4", "hvdc1 + hvdc2")); +cseParameters.setBusBarChangeSwitchesSet(Set.of( + new BusBarChangeSwitches("remedialAction1", Set.of(new SwitchPairId("switch1", "switch2"), new SwitchPairId("switch3", "switch4"))), + new BusBarChangeSwitches("remedialAction2", Set.of(new SwitchPairId("switch5", "switch6"))) +)); +// Add CSE extension to CracCreationParameters +cracCreationParameters.addExtension(CseCracCreationParameters.class, cseParameters); +``` +::: +:::{group-tab} JSON file +```json +{ + "crac-factory": "CracImplFactory", + "default-monitored-line-side": "monitor-lines-on-both-sides", + "extensions": { + "CseCracCreatorParameters": { + "range-action-groups": [ + "rangeAction3 + rangeAction4", + "hvdc1 + hvdc2" + ], + "bus-bar-change-switches": [ + { + "remedial-action-id": "remedialAction1", + "switch-pairs": [ + { + "open": "switch1", + "close": "switch2" + }, + { + "open": "switch3", + "close": "switch4" + } + ] + }, + { + "remedial-action-id": "remedialAction2", + "switch-pairs": [ + { + "open": "switch5", + "close": "switch6" + } + ] + } + ] + } + } +} +``` +::: +:::: + +## CIM-specific parameters +The [CIM native CRAC format](cim) lacks important information that other formats don't. +The user can define a [CimCracCreationParameters](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creator-cim/src/main/java/com/powsybl/openrao/data/craccreation/creator/cim/parameters/CimCracCreationParameters.java) +extension to the CracCreationParameters object in order to define them. + +### timeseries-mrids +Some processes require the RAO to split the CIM CRAC into multiple smaller CRACs, in particular in order to optimize different +borders separately. For example, the SWE CC process requires the RAO to be split into one France-Spain RAO and one +Spain-Portugal RAO. This is possible thanks to the CIM CRAC's TimeSeries tags, that can allocate crac objects to one of +the two borders. +The "timeseries-mrids" parameters allows the user to set which timeseries should be read from the CIM CRAC file, in order +to define the CNECs and remedial actions of the border-specific RAO. TimeSeries are identified by their "mRID" value. +See [example below](#full-cim-example) for a better illustration. + +### range-action-groups (CIM) +Like the CSE native CRAC format, the CIM format does not allow defining [aligned range actions](introduction.md#range-action). +This extra parameter allows the user to do just that. +To use it, you have to define a list of strings containing the IDs of range actions that have to be aligned seperated by a +" + " sign; for example "range-action-1-id + range-action-17-id" and "range-action-8-id + range-action-9-id". +See [example below](#full-cim-example) for a better illustration. + +### range-action-speeds +FARAO can simulate range-action automatons, that is automatons that shift their set-points until one or many CNECs are secured. +In order to do that, FARAO must know which automaton is quicker than the other, because activating one automaton can render +the others useless. +As the CIM native CRAC format does not allow the definition of relative automaton speeds, this parameter allows the user to do it. +To use it, set the speed of every range action automaton, defined by its ID. A smaller value means a speedier automaton. +Beware that FARAO cannot optimize range-action automatons that do not have a defined speed ; also that aligned range actions +must have the same speed. +See [example below](#full-cim-example) for a better illustration. + +### voltage-cnecs-creation-parameters +The CIM CRAC does not allow the definition of [VoltageCnecs](json.md#voltage-cnecs). This parameter allows the user +to add VoltageCnecs during CRAC creation. +To define voltage CNECs, the user has to define: +- A list of monitored network elements, identified by their unique ID in the network file. These network elements must be VoltageLevels. +- Instants for which these elements should be monitored (among instant IDs defined in the CRAC) +- For instants other than preventive that are selected, a list of contingencies after which these elements are monitored +at defined instants (the contingences shall be identified by their CIM CRAC mRIDs as they figure in the B55 Series/Contingency_Series) +- For every instant, the minimum and maximum voltage thresholds to be respected for every nominal voltage level. +See [example below](#full-cim-example) for a better illustration. + + +### full CIM example +::::{tabs} +:::{group-tab} JAVA API +```java +// Create CracCreationParameters and set global parameters +CracCreationParameters cracCreationParameters = new CracCreationParameters(); +// Create CIM-specific parameters +CimCracCreationParameters cimParameters = new CimCracCreationParameters(); +// Only read TimeSeries with mRIDs "border1-ts1" and "border1-ts2" from the CIM CRAC +cimParameters.setTimeseriesMrids(Set.of("border1-ts1", "border1-ts2")); +// Align rangeAction1 with rangeAction2 and rangeAction10 with rangeAction11 +cimParameters.setRangeActionGroupsAsString(List.of("rangeAction1 + rangeAction2", "rangeAction10 + rangeAction11")); +// rangeAction1 and rangeAction2 are automatons that act faster than rangeAction3 +cimParameters.setRemedialActionSpeed(Set.of( + new RangeActionSpeed("rangeAction1", 1), + new RangeActionSpeed("rangeAction2", 1), + new RangeActionSpeed("rangeAction3", 2) +)); +// Define voltage CNECs to be created +// Monitor these voltage levels (using their IDs in the network): +Set voltageMonitoredElements = Set.of("ne1", "ne2"); +// At preventive instant, constrain voltage CNECs: +// - with a nominal V of 400kV, to stay between 395 and 430kV +// - with a nominal V of 200kV, to stay above 180kV +Map preventiveVoltageThresholds = Map.of( + 400., new VoltageThreshold(Unit.KILOVOLT, 395., 430.), + 200., new VoltageThreshold(Unit.KILOVOLT, 180., null) +); +// At curative instant, constrain voltage CNECs: +// - with a nominal V of 400kV, to stay between 380 and 430kV +// - with a nominal V of 210kV, to stay below 230kV +Map curativeVoltageThresholds = Map.of( + 400., new VoltageThreshold(Unit.KILOVOLT, 380., 430.), + 210., new VoltageThreshold(Unit.KILOVOLT, null, 230.) +); +// Define these voltage CNECs for the following contingencies, as identified in the CIM CRAC: +Set voltageContingencies = Set.of("N-1 ONE", "N-1 TWO"); +// Put all this together in the CIM CRAC creation parameters +cimParameters.setVoltageCnecsCreationParameters(new VoltageCnecsCreationParameters( + Map.of( + "preventive", new VoltageMonitoredContingenciesAndThresholds(null, preventiveVoltageThresholds), + "curative", new VoltageMonitoredContingenciesAndThresholds(voltageContingencies, curativeVoltageThresholds) + ), + voltageMonitoredElements +)); +// Add CIM extension to CracCreationParameters +cracCreationParameters.addExtension(CimCracCreationParameters.class, cimParameters); +``` +::: +:::{group-tab} JSON file +```json +{ + "crac-factory": "CracImplFactory", + "default-monitored-line-side": "monitor-lines-on-both-sides", + "extensions": { + "CimCracCreatorParameters": { + "timeseries-mrids" : [ "border1-ts1", "border1-ts2" ], + "range-action-groups": [ + "rangeAction1 + rangeAction2", + "rangeAction10 + rangeAction11" + ], + "range-action-speeds": [ + { + "range-action-id": "rangeAction1", + "speed": 1 + }, + { + "range-action-id": "rangeAction2", + "speed": 1 + }, + { + "range-action-id": "rangeAction3", + "speed": 2 + } + ], + "voltage-cnecs-creation-parameters": { + "monitored-states-and-thresholds": [ + { + "instant": "preventive", + "thresholds-per-nominal-v": [ + { + "nominalV": 400, + "unit": "kilovolt", + "min": 395, + "max": 430 + }, + { + "nominalV": 200, + "unit": "kilovolt", + "min": 180 + } + ] + }, + { + "instant": "curative", + "thresholds-per-nominal-v": [ + { + "nominalV": 400, + "unit": "KiloVolt", + "min": 380, + "max": 430 + }, + { + "nominalV": 210, + "unit": "KILOVOLT", + "max": 230 + } + ], + "contingency-names": [ + "N-1 ONE", + "N-1 TWO" + ] + } + ], + "monitored-network-elements": [ + "ne1", + "ne2" + ] + } + } + } +} +``` +::: +:::: diff --git a/docs/input-data/crac/csa.md b/docs/input-data/crac/csa.md new file mode 100644 index 0000000000..f3ba432dd7 --- /dev/null +++ b/docs/input-data/crac/csa.md @@ -0,0 +1,891 @@ +# CSA-Profiles CRAC format + +## Presentation + +For the CSA process, the CRAC data is split over multiple XML files called **CSA profiles**, each one with its own +specific purpose, and which were inspired by the CGM format. This format +was [introduced by ENTSO-E](https://www.entsoe.eu/data/cim/cim-for-grid-models-exchange/). The objects in the different +CSA profiles reference one another using **mRID** links (UUID format) which makes it possible to separate the +information among several distinct files. + +## Header overview + +The FARAO importer only supports version `2.3` headers for CSA profiles (see +[ENTSO-E website](https://www.entsoe.eu/Documents/CIM_documents/Grid_Model_CIM/MetadataAndHeaderDataExchangeSpecification_v2.3.0.pdf)). + +```xml + + + + ... + 2023-01-01T00:00:00Z + 2100-01-01T00:00:00Z + ... + + ... + +``` + +Each CSA profile is identified by a `dcat:keyword` that states which category of features it bears. To be valid for +FARAO, a profile must have exactly one keyword defined in its header. Besides, FARAO currently handles 5 different CSA +profiles, the keyword and purpose of which are gathered in the following table: + +| Keyword | Full Name | Purpose | +|---------|--------------------------|----------------------------------------| +| AE | Assessed Element | Definition of CNECs. | +| CO | Contingency | Definition of contingencies. | +| ER | Equipment Reliability | Definition of AngleCNECs' thresholds. | +| RA | Remedial Action | Definition of remedial actions. | +| SSI | Steady State Instruction | Overriding data for specific instants. | + +Besides, each CSA profile has a period of validity delimited by the `dcat:startDate` and `dcat:endDate` fields (both +required) in the header. If the time at which the import occurs is outside of this time interval, the profile is +ignored. + +> Several other fields can be added to the header but these will be ignored by FARAO. + +## Profiles overview + +The CRAC data is spread over different profiles that reference one another. The relation between the objects and the +fields read by FARAO are displayed in the following chart. + +> Fields preceded by a "~" are optional. + +![CSA profiles usage overview](/_static/img/CSA-profiles.png) + +## Contingencies + +The [contingencies](json.md#contingencies) are described in the **CO** profile. They can be represented by three types of +objects: `OrdinaryContingency`, `ExceptionalContingency` and `OutOfRangeContingency`. The contingency must be +associated to the impacted network elements through `ContingencyEquipment` objects. + +::::{tabs} +:::{group-tab} OrdinaryContingency +```xml + + + ... + + ordinary-contingency + Ordinary contingency + Example of ordinary contingency. + true + + + + contingency-equipment + Contingency equipment + Example of contingency equipment. + + + + + ... + +``` +::: +:::{group-tab} ExceptionalContingency +```xml + + + ... + + exceptional-contingency + Exceptional contingency + Example of exceptional contingency. + true + + + + contingency-equipment + Contingency equipment + Example of contingency equipment. + + + + + ... + +``` +::: +:::{group-tab} OutOfRangeContingency +```xml + + + ... + + out-of-range-contingency + Out-of-range contingency + Example of out-of-range contingency. + true + + + + contingency-equipment + Contingency equipment + Example of contingency equipment. + + + + + ... + +``` +::: +:::: + +A contingency is imported only if the `normalMustStudy` field is set to `true` and if it is referenced by a +valid `ContingencyEquipment`, i.e. having `Equipment` pointing to an existing network element and a `contingentStatus` +being `outOfService`. A contingency with no associated `ContingencyEquipment` will be ignored. + +> - The contingency can still be imported if `normalMustStudy` is set to `false` if the contingency is also defined in + the SSI profile with its field `mustStudy` set to `true`. +> - The network elements must be defined in the CGMES. + +From the `OrdinaryContingency` / `ExceptionalContingency` / `OutOfRangeContingency` object, the `mRID` is used as the +contingency's identifier. Besides, the `EquipmentOperator` is converted to a friendly name and concatenated with the +`name` to create the contingency's name (if the TSO is missing, only the name is used; if the name is missing, the +`mRID` will be used instead). Finally, the `ContingencyEquipment`'s `Equipment` is used as the contingency's network +element. + +## CNECs + +The [CNECs](json.md#cnecs) are described in the **AE** profile with an `AssessedElement` object which bears the identifier, +name, instant(s) and operator information. + +```xml + + + ... + + assessed-element + Assessed element + Example of assessed element. + true + true + false + false + + + ... + +``` + +The CNEC is imported only if the `normalEnabled` fields is set to `true` or missing. If the `inBaseCase` field is set +to `true` a **preventive** CNEC is created from this assessed element (but this does not mean that a curative CNEC +cannot be created as well). The `AssessedSystemOperator` and the `name` are concatenated together with the CNEC's +instant (with the pattern *TSO_name - instant*) to create the CNEC's name. + +> The CNEC can still be imported if `normalEnabled` is set to `false` if the AssessedElement is also defined in the SSI +> profile with its field `enabled` set to `true`. + +Finally, in order to specify the type, value(s) of the threshold(s) and associated network elements of the CNEC, two +options are possible: + +- using an `OperationalLimit` that points to an eponymous object in either the ER or EQ profile depending on the type of + CNEC (see below) +- (FlowCNECs only) using a `ConductingEquipment` that points to a line to define FlowCNECs for the PATL and all the TATL + of the line at once + +> If none or both fields are present the AssessedElement will be ignored. + +A CNEC can also be made curative by linking it to a contingency through an `AssessedElementWithContingency`. In this +case, the contingency's name is added to the CNEC's name. + +```xml + + + ... + + assessed-element-with-contingency + + + + + true + + ... + +``` + +The distinction between the types of CNEC (FlowCNEC, AngleCNEC or VoltageCNEC) comes from the type of `OperationalLimit` +of the Assessed Element (or the use of a `ConductingEquipment` for FlowCNECs). + +### FlowCNEC + +::::{tabs} +:::{group-tab} OperationalLimit +The CNEC is a [FlowCNEC](json.md#flow-cnecs) if its associated `OperationalLimit` is a `CurrentLimit` which can be found in +the **EQ** profile (CGMES file). + +```xml + + + ... + + assessed-element + Assessed element + Example of assessed element. + true + true + false + false + + + + ... + +``` + +```xml + + + ... + + operational-limit-set + Operational limit set + Example of operational limit set + + + + operational-limit-type + Operational limit type + Example of operational limit type + + + 30 + + + current-limit + Current limit + Example of current limit + + + 100.0 + + ... + +``` + +The CNEC's threshold value (in AMPERES) is determined by the `value` field of the `CurrentLimit` and must be positive. +Whether this is the maximum or minimum threshold of the CNEC depends on the `OperationalLimitType`'s `direction`: + +- if the `direction` is `high`, the maximum value of the threshold is `+ normalValue` +- if the `direction` is `absoluteValue`, the maximum value of the threshold is + `normalValue` and the minimum value of + the threshold is `- normalValue` + +The CNEC's threshold side depends on the nature of the `OperationalLimitSet`'s `Terminal` which must reference an +existing line in the network and which also defines the CNEC's network element: + +- if the line is a `CGMES.Terminal1` or a `CGMES.Terminal_Boundary_1` in PowSyBl, the threshold of the CNEC is on the + **left** side +- if the line is a `CGMES.Terminal2` or a `CGMES.Terminal_Boundary_2` in PowSyBl, the threshold of the CNEC is on the + **right** side + +If the `OperationalLimitType`'s `kind` is `tatl`, the `OperationalLimitType`'s `acceptableDuration` field must be +present and sets the FlowCNEC's instant: + +- if `acceptableDuration` = 0, the FlowCNEC is **preventive** or **curative** (if linked to a contingency) +- if 0 < `acceptableDuration` ≀ 60, the FlowCNEC is monitored at the **outage** instant +- if 60 < `acceptableDuration` ≀ 900, the FlowCNEC is monitored at the **auto** instant +- if `acceptableDuration` > 900, the FlowCNEC is **curative** + +If the `AssessedElement` is `inBaseCase` and the limit is a PATL, a preventive FlowCNEC is added as well. + +::: +:::{group-tab} ConductingEquipment + +FlowCNECs can also be defined with a `ConductingEquipement` that points to a line in the CGMES. + +```xml + + + ... + + assessed-element + Assessed element + Example of assessed element. + true + true + false + false + + + + ... + +``` + +In that case, several FlowCNECs can be defined at once depending on the number of TATLs defined for the line (given that +the `AssessedElement` is linked to a contingency). Thus, for each associated contingency and each TATL: + +- a curative FlowCNEC is created if the TATL duration is null +- an outage FlowCNEC is created if the TATL duration is below 60 seconds +- an auto FlowCNEC is created if the TATL duration is between 60 (excluded) and 900 (included) seconds +- a curative FlowCNEC is created if the TATL duration is greater than 900 seconds + +For each contingency, a curative FlowCNEC is also created using the PATL. Finally, if the `AssessedElement` +is `inBaseCase` a preventive FlowCNEC is added using the PATL as well. In all case, the limit's threshold is used for +both the maximum (positive) and minimum (negative) FlowCNEC's thresholds. +::: +:::: + +### AngleCNEC + +The CNEC is an [AngleCNEC](json.md#angle-cnecs) if its associated `OperationalLimit` is a `VoltageAngleLimit` which can be +found in the **ER** profile. + +```xml + + + ... + + operational-limit-set + Operational limit set + Example of operational limit set + + + + operational-limit-type + Operational limit type + Example of operational limit type + + + + voltage-angle-limit + Voltage angle limit + Example of voltage angle limit + + + 100.0 + true + + + ... + +``` + +The CNEC's threshold value (in DEGREES) is determined by the `normalValue` field of the `VoltageAngleLimit` and must be +positive. Whether this is the maximum or minimum threshold of the CNEC depends on the `OperationalLimitType`' +s `direction`: + +- if the `direction` is `high`, the maximum value of the threshold is `+ normalValue` +- if the `direction` is `low`, the minimum value of the threshold is `- normalValue` +- if the `direction` is `absoluteValue`, the maximum value of the threshold is + `normalValue` and the minimum value of + the threshold is `- normalValue` + +An AngleCNEC also has two terminals, one being the importing element and the other being the exporting element, which +imposes the flow direction. Two terminals are referenced by the AngleCNEC in the CSA profiles. The first one (called +*terminal_1*) is referenced by the `VoltageAngleLimit`'s `AngleReferenceTerminal` field. The second one (called +*terminal_2*) is referenced by the `OperationalLimitSet`'s `Terminal` field. The flow direction is determined depending +on the `VoltageAngleLimit`'s `isFlowToRefTerminal` field value: + +- if it is missing of `false`, the importing element is *terminal_1* and the exporting element is *terminal_2* +- if it is present of `true`, the exporting element is *terminal_1* and the importing element is *terminal_2* + +> ⚠️ Note that if the `OperationalLimitType`'s `direction` is **not** `absoluteValue`, the `isFlowToRefTerminal` must be +> present otherwise the AngleCNEC will be ignored. + +### VoltageCNEC + +The CNEC is a [VoltageCNEC](json.md#voltage-cnecs) if its associated `OperationalLimit` is a `VoltageLimit` which can be +found in the **EQ** profile (CGMES file). + +```xml + + + ... + + operational-limit-set + Operational limit set + Example of operational limit set + + + + operational-limit-type + Operational limit type + Example of operational limit type + true + + + + voltage-limit + Voltage limit + Example of voltage limit + + + 100.0 + + ... + +``` + +To be valid, the VoltageCNEC's `isInfiniteDuration` field must be set to `true`. It is missing or set to `false` it will +be ignored. + +The CNEC's threshold value (in KILOVOLTS) is determined by the `value` field of the `VoltageLimit` and must be positive. +Whether this is the maximum or minimum threshold of the CNEC depends on the `OperationalLimitType`'s `direction`: + +- if the `direction` is `high`, the maximum value of the threshold is `+ normalValue` +- if the `direction` is `low`, the minimum value of the threshold is `- normalValue` + +The VoltageCNEC's network element is determined by the `OperationalLimitSet`'s `Terminal`. The latter must reference an +existing BusBarSection in the network. + +## Remedial Actions + +The [remedial actions](json.md#remedial-actions-and-usages-rules) are described in the **RA** profile. The most general way to describe a +remedial action is with a `GridStateAlterationRemedialAction` object that bears the identifier, name, operator, speed +and instant of the remedial action. + +```xml + + + ... + + remedial-action + RA + Example of RA + true + + PT50S + + + ... + +``` + +The remedial action is imported only if the `normalAvailable` field is set to `true`. + +> The remedial action can still be imported if `normalAvailable` is set to `false` if the remedial action is also +> defined in the SSI profile with its field `avilable` set to `true`. + +As for the [contingencies](#contingencies), the `mRID` is used as the remedial action's identifier and +the `RemedialActionSystemOperator` and `name` are concatenated together to create the remedial action's name. The +instant of the remedial action is determined by the `kind` which can be either `preventive` or `curative`. Finally, +the `timeToImplement` is converted to a number of seconds and used as the remedial action's speed. + +In the following, we describe the different types of remedial actions that can be imported in FARAO from the CSA +profiles. The general pattern is to link a `GridStateAlteration` object which references the parent remedial +action (`GridStateAlterationRemedialAction`) and a `StaticPropertyRange` which contains the physical and numerical +definition of the remedial action. The field of the `StaticPropertyRange` are: + +- `normalValue` which contains the numerical data of the remedial action (such as the set-point, the PST tap, ...) +- `PropertyReference` which indicated the network element's property that will be affected by the remedial action +- `valueKind` which indicates whether the `normalValue` is defined independently of the previous state (`absolute`) of + the network element or relatively (`incremental`) +- `direction` which bears the logic of whether the `normalValue` is an extreme value, an increase / decrease or just a + standalone value + +### PST Range Action + +A [PST range action](json.md#pst-range-action) is described by a `TapPositionAction` object which references its parent +remedial action (`GridStateAlterationRemedialAction`) and the PST affected by the action. + +```xml + + + ... + + tap-position-action + Tap position action + Example of tap position action + true + + + + + ... + +``` + +The PST range action is considered only if the `normalEnabled` field is set to `true`. Besides, the `TapChanger` must +reference an existing PST in the network and the `PropertyReference` must necessarily be `TapChanger.step` since it is +the PST's tap position which shifts. + +> The PST range action can still be imported if `normalEnabled` is set to `false` if the TapPositionAction is also +> defined in the SSI profile with its field `enabled` set to `true`. + +To be valid, the `TapPositionAction` must itself be referenced by at most two `StaticPropertyRange` objects which +provide the numerical values for the minimum and/or maximum reachable taps. If no `StaticPropertyRange` is present, the +range of the remedial action will be set from the PST range read in the network. + +```xml + + + ... + + static-property-range-for-tap-position-action-max + Upper bound for tap position action + + 7.0 + + + + + + static-property-range-for-tap-position-action-min + Lower bound for tap position action + + -7.0 + + + + + ... + +``` + +For the `StaticPropertyRange`, the `PropertyReference` must also be `TapChanger.step`. The value of the tap is +determined by the `normalValue`: if the `direction` is `up` this is the maximum reachable tap and if it is `down` it is +the minimum. Note that the `valueKind` must be `absolute` to indicate that the limit does not depend on the previous +PST's state. Up to two `StaticPropertyRange` objects can be linked to the same PST range action to set the minimum +and/or maximum tap. + +> The `normalValue` can be overridden in the SSI profile if a `RangeConstraint` with the same mRID as +> the `StaticPropertyRange` is defined. In that case, the field `value` of the `RangeConstraint` will be considered +> instead. + +### Network Actions + +#### Topological Action + +A [topological action](json.md#network-actions) is described by a `TopologyAction` object which references its parent +remedial action (`GridStateAlterationRemedialAction`) and the switch affected by the action. + +```xml + + + ... + + topology-action + Topology action + Example of topology action + true + + + + + ... + +``` + +The topological action is considered only if the `normalEnabled` field is set to `true`. Besides, the `Switch` must +reference an existing switch in the network and the `PropertyReference` must necessarily be `Switch.open` since a +topology action is about opening or closing such a switch. + +> The topological action can still be imported if `normalEnabled` is set to `false` if the TopologyAction is also +> defined in the SSI profile with its field `enabled` set to `true`. + +To be valid, the `TopologyAction` must itself be referenced by one `StaticPropertyRange` object which indicates whether +to open or to close the switch. + +```xml + + + ... + + static-property-range-for-topology-action + Example of StaticPropertyRange to open a switch + + 1 + + + + + ... + +``` + +For the `StaticPropertyRange`, the `PropertyReference` must also be `Switch.open`. Note that the `valueKind` must +be `absolute` and the `direction` must be `none` to indicate that the limit does not depend on the previous switch's +state. Finally, the `normalValue` field sets the behaviour of the switch: + +- if it is 0 the switch will be closed +- if it is 1 the switch will be opened + +> The `normalValue` can be overridden in the SSI profile if a `RangeConstraint` with the same mRID as +> the `StaticPropertyRange` is defined. In that case, the field `value` of the `RangeConstraint` will be considered +> instead. + +#### Injection Set-point Action + +An [injection set-point action](json.md#network-actions) is described by a `SetPointAction` object which references its +parent remedial action (`GridStateAlterationRemedialAction`) and the network element affected by the action, and which +is itself referenced by a `StaticPropertyRange` object to provide the numerical value of the set-point. Currently, FARAO +handles three types of CSA set-point actions: the **rotating machine actions**, the **power electronics connection +actions** and the **shunt compensator modifications**. All three are handled similarly by FARAO but their respective +descriptions in the CSA profiles differ from one another. + +::::{tabs} +:::{group-tab} RotatingMachineAction +A rotating machine action is described with a `RotatingMachineAction` object in the RA profile. + +```xml + + + ... + + rotating-machine-action + Rotating machine action + Example of rotating machine action + true + + + + + ... + +``` + +The rotating machine action is considered only if the `normalEnabled` field is set to `true`. Besides, +the `RotatingMachine` must reference an existing generator in the network and the `PropertyReference` must necessarily +be `RotatingMachine.p` since the remedial action acts on the generator's power. + +> The rotating machine action can still be imported if `normalEnabled` is set to `false` if the RotatingMachineAction is +> also defined in the SSI profile with its field `enabled` set to `true`. + +To be valid, the `RotatingMachineAction` must itself be referenced by a `StaticPropertyRange` which provides the value +of the set-point. + +```xml + + + ... + + static-property-range-for-rotating-machine-action + Set-point in MW + + 100.0 + + + + + ... + +``` + +For the `StaticPropertyRange`, the `PropertyReference` must also be `RotatingMachine.p`. The value of the set-point (in +MW) is determined by the `normalValue` given that the `valueKind` is `absolute` and that the `direction` is none to +indicate that the set-point is an imposed value without any degree of freedom for the RAO. + +> The `normalValue` can be overridden in the SSI profile if a `RangeConstraint` with the same mRID as +> the `StaticPropertyRange` is defined. In that case, the field `value` of the `RangeConstraint` will be considered +> instead. +::: +:::{group-tab} PowerElectronicsConnectionAction +A power electronics connection action is described with a `PowerElectronicsConnectionAction` object in the RA profile. + +```xml + + + ... + + power-electronics-connection-action + Power electronics connection action + Example of power electronics connection action + + true + + + + + ... + +``` + +The power electronics connection action is considered only if the `normalEnabled` field is set to `true`. Besides, +the `PowerElectronicsConnection` must reference an existing power electronics connection in the network and +the `PropertyReference` must necessarily be `PowerElectronicsConnection.p` since the remedial action acts on the power +electronics connection's power. + +> The power electronics connection action can still be imported if `normalEnabled` is set to `false` if the +> PowerElectronicsConnectionAction is also defined in the SSI profile with its field `enabled` set to `true`. + +To be valid, the `PowerElectronicsConnectionAction` must itself be referenced by a `StaticPropertyRange` which provides +the value of the set-point. + +```xml + + + ... + + static-property-range-for-power-electronics-connection-action + + Set-point in MW + + 75.0 + + + + + ... + +``` + +For the `StaticPropertyRange`, the `PropertyReference` must also be `PowerElectronicsConnection.p`. The value of the +set-point (in MW) is determined by the `normalValue` given that the `valueKind` is `absolute` and that the `direction` +is none to indicate that the set-point is an imposed value without any degree of freedom for the RAO. + +> The `normalValue` can be overridden in the SSI profile if a `RangeConstraint` with the same mRID as +> the `StaticPropertyRange` is defined. In that case, the field `value` of the `RangeConstraint` will be considered +> instead. +::: +:::{group-tab} ShuntCompensatorModification +A shunt compensator modification is described with a `ShuntCompensatorModification` object in the RA profile. + +```xml + + + ... + + shunt-compensator-modification + Shunt compensator modification + Example of shunt compensator modification + true + + + + + ... + +``` + +The shunt compensator modification is considered only if the `normalEnabled` field is set to `true`. Besides, +the `ShuntCompensator` must reference a shunt compensator in the network and the `PropertyReference` must necessarily +be `ShuntCompensator.sections` since the remedial action acts on the number of sections of the shunt compensator. + +> The shunt compensator modification can still be imported if `normalEnabled` is set to `false` if the +> ShuntCompensatorModification is also defined in the SSI profile with its field `enabled` set to `true`. + +To be valid, the `ShuntCompensatorModification` must itself be referenced by a `StaticPropertyRange` which provides the +value of the set-point. + +```xml + + + ... + + static-property-range-for-shunt-compensator-modification + Set-point in SECTION_COUNT + + 5.0 + + + + + ... + +``` + +For the `StaticPropertyRange`, the `PropertyReference` must also be `ShuntCompensator.sections`. The value of the +set-point (in SECTION_COUNT) is determined by the `normalValue` given that the `valueKind` is `absolute` and that +the `direction`is none to indicate that the number of section is an imposed value without any degree of freedom for the +RAO. Note that `normalValue` must be integer-*castable* (i.e. a float number with null decimal part) to model a number +of sections. + +> The `normalValue` can be overridden in the SSI profile if a `RangeConstraint` with the same mRID as +> the `StaticPropertyRange` is defined. In that case, the field `value` of the `RangeConstraint` will be considered +> instead. + +::: +:::: + +### Usage Rules + +#### OnInstant + +By default, if no additional information is given, the remedial action is imported with an **onInstant usage rule** +and an **AVAILABLE usage method**. + +#### OnContingencyState + +If the remedial action is linked to a contingency, its usage method is no longer onInstant and is now +**onContingencyState**. This link is created with a `ContingencyWithRemedialAction` object that bounds together the +remedial action and the contingency. + +```xml + + + ... + + contingency-with-remedial-action + + + + true + + ... + +``` + +The usage method depends on the value of the `combinationConstraintKind` field: + +- if it is `considered`, the usage method is **AVAILABLE**; +- if it is `included`, the usage method is **FORCED**; + +> β›” **Cases with different `combinationConstraintKind` values for the same remedial action-contingency couple** +> +> This case is illegal and will be discarded at the import. + +#### OnConstraint + +If the remedial action is linked to an assessed element (a CNEC), its usage method is no longer onInstant and is now +**onConstraint**. This link is created with a `AssessedElementWithRemedialAction` object that bounds together the +assessed element and the contingency. + +The type of onConstraint usage rule depends on the type of the CNEC the remedial action is bounded to: + +- if it is a FlowCNEC, the usage rule is **onFlowConstraint** +- if it is an AngleCNEC, the usage rule is **onAngleConstraint** +- if it is a VoltageCNEC, the usage rule is **onVoltageConstraint** + +```xml + + + ... + + assessed-element-with-remedial-action + + + + + true + + ... + +``` + +The usage method depends on the value of the `combinationConstraintKind` field. If it is `considered`, the usage method +is **AVAILABLE** whereas the usage method is **FORCED** if the fields is `included`. diff --git a/docs/input-data/crac/cse.md b/docs/input-data/crac/cse.md new file mode 100644 index 0000000000..bce330361d --- /dev/null +++ b/docs/input-data/crac/cse.md @@ -0,0 +1,425 @@ +# CSE CRAC format + +## Header overview + +```xml + + + + + + + + + + + + + + + ... + + +``` +A crac document has a time interval for its validity and a lot of its sub-objects have their own time interval of validity as well. +Therefore, **this document has to be imported for a specific datetime** – hourly-precise – to be able to select only the available elements for this datetime. + +## Branch + +In the PowSyBl vocabulary, **a 'Branch' is an element which is connected to two terminals** (lines, tie-lines, transformers, etc.) +As this object is used almost everywhere in the CRAC, it is introduced first. +A branch has few mandatory tags that should be filled in for FARAO to consider them : **FromNode, ToNode, Order.** They refer to existing network elements by their UCTE code. +However, a branch has also a lot of optional tags that are described right below this example. + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +- **Name** : Alternative way to describe the branch with useful information to identify it more easily when reading logs and results +- **EIC** : Identification +- **AlwaysSelected** : FARAO does not use this tag, it only reads the selected tag one +- **selected** : If selected is false, FARAO will not consider the margin on this branch in its optimization. Default value is true +- **Imax{...} and Ilimit{...}** : Please refer respectively to the [CriticalBranches](#criticalbranches) and [Monitored Elements](#monitoredelements) sections at the end of this page +- **Vn** : It is the nominal voltage, but FARAO reads is directly in the network therefore it is useless to fill it +- **minmargin** : FARAO does not interact with this tag +- **Direction** : Has to be DIRECT, OPPOSITE or BIDIR. **If the Branch is defined in a BaseCaseBranch, a CriticalBranch +or a MonitoredElement, this tag is mandatory.** Please refer to [this section](json.md#flow-cnecs) of JSON CRAC Format +for more information on the behavior of FARAO according to the different direction values. +- **Status** : Must be OPEN or CLOSE for a branch involved in a topological action. Default value is OPEN. See an example in the [topological actions](#network-actions) section of this page. +- **Sensitivity** : FARAO does not interact with this tag +- **PTDFListRef** : FARAO does not interact with this tag +- **Remedial actions** : These remedial actions will be available with OnFlowConstraint usage rule for the branches they are associated to + +## Outages +```xml + + + + + + + + + + + + + + + + + + + + + + + + + ... + +``` + +**Outages are also commonly called β€˜Contingencies’.** +Each outage with multiple associated network elements must have them listed as showcased in the "outage_2" example above. + +## RemedialActions + +```xml + + ... + + + + + + + + ... + + + +``` + +A remedial action can be of different types, but they will always have : +- A name +- A TimeInterval : Has to contain the import datetime. +- An operator : Represents a country in the UCTE country code format +- A tag Application : Instant when the remedial action can be applied (SPS should be written for Instant Auto) +- A tag SharedWith + +**The SharedWith tag** + +This tag defines the usage rule of the remedial action. You can refer to [this section](json.md#remedial-actions-and-usages-rules) for further explanation on the usage rule behavior. + +If SharedWith is "CSE" : FreeToUse +If SharedWith is a UCTE country code : OnFlowConstraintInCountry in the country filled in +If SharedWith is "None" : OnFlowConstraint only for its associated CNECs (c.f. the Branch section above) + +### Range Actions + +#### PST Range Actions + +```xml + + ... + + + + + + + + + + + + + + + + + + + + +``` + +A PST Range Action is defined by its PstRange attribute which contains: +- a Branch +- a VariationType : For now the only VariationType handled by FARAO is "ABSOLUTE" : the mix/max admissible taps of the PST. +- a Min value : Has to be an Integer +- a Max value : Must be an Integer >= Min value + +FARAO minimum tap = max(Network minimum tap, Crac minimum tap) +FARAO maximum tap = min(Network maximum tap, Crac maximum tap) + +#### HVDC Range Actions + +```xml + + ... + + + + + + + + + + + + + + + + + + + + +``` + +For now the only VariationType handled by FARAO is "ABSOLUTE" : the min/max admissible set-points of the HVDC. +**An HVDC Range Action is modelled by an Injection range Action** (the HVDC line is disconnected and replaced by two injections, one on each side of the line, with opposite keys of 1 and -1). +FARAO creates the opposite keys by itself, therefore there is no need to specify it. +⚠️*There isn't any check performed to verify that an applied set-point is between the ranges' min and max.* + +### Network Actions + +#### injection set-point + +```xml + + ... + + + + + + + + + + + + + + + + + +``` + +For now the only VariationType handled by FARAO is "ABSOLUTE", on the node you filled in, the new set-point value will be the one you defined (in MW). + +#### topological actions + +```xml + + ... + + + + + + + + + + + + + + + + + + +``` + +As mentioned earlier, the status must be OPEN or CLOSE and default value is OPEN. + +#### bus bar change +```xml + + ... + + + + + + + + + + + + + + + + + + + + + + + ... + + +``` +These remedial actions consist in the changing of one or multiple lines' end from one bus to another. +In the example above, the remedial action would move: +- Line BBE1AA11 BBE2AA1* 1 (* is a wildcard) on the left side from bus BBE1AA11 (InitialNode) to bus BBE1AA12 (FinalNode) +- Line BBE1AA11 BBE3AA1* 1 (* is a wildcard) on the left side from bus BBE1AA11 (InitialNode) to bus BBE1AA12 (FinalNode) + +These modifications are actually impossible to do easily in a PowSyBl network without modifying its whole structure. +For this reason, the user shall pre-process the network in order to create fictitious buses and switches that shall be opened +or closed by these remedial actions. + +![bus-bar-equivalent-model](/_static/img/busbar.png) + +Using [CseCracCreationParameters](creation-parameters.md#cse-specific-parameters), FARAO can then map these remedial actions to the switches +created by the user, and interpret BusBar remedial actions as [SwitchPairs](introduction.md#switch-pair). + +## CriticalBranches + +It should contain a BaseCaseBranches tag and at least one CriticalBranch + +### BaseCaseBranches + +```xml + + ... + + ... + + + + + + + + + + + + + + + + + + + + + + +``` + +BaseCaseBranches is made of: +- A TimeInterval : Must contain the import datetime. +- A List of branches + +For each branch in the list, if Imax is provided, **a CNEC will be created on Preventive state.** + +### CriticalBranch + +```xml + + ... + + ... + + + + + + + + + + + + + + + +``` + +Each one needs at least these information : +- A TimeInterval : Has to contain the import datetime. +- An outage : Must be an outage name existing in the Outages section +- A branch + +For each critical branch, given an attribute ImaxAfter{Instant}, **a CNEC on the given state will be created :** +- ImaxAfterOutage -> Instant Outage +- ImaxAfterSPS -> Instant Auto +- ImaxAfterCRA -> Instant Curative + +## MonitoredElements + +```xml + + ... + + + + + + + + + + + + + + + + + + +``` + +A MonitoredElement always has a TimeInterval and a branch. +It will not be optimized by FARAO, however it will be monitored. In other words, **on this element, FARAO cannot reduce the margin compared to its initial value.** + +First, if IlimitMNE is filled in, a CNEC on Preventive state will be created. Then, **for each outage in the Outages tag and for each attribute IlimitMNE_After{Instant} that is present, a CNEC will be created on the given state**: +- IlimitMNE_AfterOutage -> Instant Outage +- IlimitMNE_AfterSPS -> Instant Auto +- IlimitMNE_AfterCRA -> Instant Curative + \ No newline at end of file diff --git a/docs/input-data/crac/fbconstraint.md b/docs/input-data/crac/fbconstraint.md new file mode 100644 index 0000000000..b7eb421990 --- /dev/null +++ b/docs/input-data/crac/fbconstraint.md @@ -0,0 +1,182 @@ +# FlowBasedConstraint CRAC format + +## Header overview + +```xml + + + + + + + + + + + + + ... + +``` +A flow-based constraint document has a time interval for its validity and a lot of its sub-objects have their own time +interval of validity as well. Therefore, **this document has to be imported for a specific datetime** – hourly-precise – +to be able to select only the available elements for this datetime. + +## Critical branches + +```xml + + + + 1 + SEASONAL + 1 + 1.1 + 100 + 75 + true + false + DIRECT + DE + +``` +A critical branch represents a CNEC. As it is an identifiable it has a unique ID, "de2_nl3_N" in the example above. + +As it has been indicated previously, a critical branch has a time interval of validity, so it will be imported only if +the import datetime is contained within the time interval of validity. + +```xml + + + ... + + + + +``` + +As it is defined in the CRAC model a CNEC is associated to a state. If the <outage> tag is not present as it is in +the first example the CNEC is associated to the "preventive state" otherwise **two different CNECs will be created** one +on state ("Outage", contingency_id) and another one on state ("Curative", contingency_id). These two CNECs will be on the +same network element but will have different thresholds as it is explained in the **thresholds section**. As two CNECs are +created from a unique CNEC with its ID, a suffix is added to the IDs of the new CNECs " - Outage" and " - Curative". + +### Branch definition + +In the definitions of critical branches or outages appear the <branch> tag, it can be quite singular. This type of +CRAC has to be associated with a network in UCTE format therefore a branch is designated by two nodes – from and to – that +are UCTE nodes and an order code which is defined in the UCTE format literature. The name represents only a more +human-readable name but there is no guaranty on its unicity. + +A branch can also be defined this way : + +```xml + +``` + +Instead of using order code as third identifier, the element name can be used as it is defined in the UCTE format +literature as well. This implies that network elements from the IIDM network have to be identifiable with two different +type of IDs "fromNode toNode orderCode" and "fromNode toNode elementName". This is handled by the aliases, a network +element has its ID "fromNode toNode orderCode" when it's imported from UCTE format, but aliases can be created to +identify it with other names. + +Another problem is that from/to nodes can be inverted in the CRAC compared to what is present in the network. Such +branches are correctly identified when the file is imported, but appears to be inverted in the resulting CRAC - meaning +that their flow sign might be different between the 'CORE-definition' of the branch and the 'FARAO-definition' of the +branch. The inversion of the branch is tracked in the [CracCreationContext](creation-context.md#flowbasedconstraint-implementation) to handle +properly the sign of the flow when the results of the RAO are exported. + +### Thresholds + +Thresholds can be defined in several ways in this format. There are two types of thresholds – permanent and temporary. +In our model permanent limits make sense on preventive and curative states whereas temporary limits make sense only +the outage states. + +Permanent thresholds: +- <imaxA> and <imaxFactor> : the first one is an absolute threshold in Amps the second one is a percentage + of Imax as a limit – Imax being defined for each line in the UCTE network file. +- <permanentImaxA> and <permanentImaxFactor> : same definition of absolute and relative limits as defined previously. + +Both tags can be present, they will be added, the most limiting will be the effective one during the optimisation. + +Temporary thresholds: +- <temporaryImaxA> and <temporaryImaxFactor> : same definitions + +To define thresholds we also have to take <direction> tag into account. As mentioned in the model a network +element has a direction – from/to node – then a threshold can be effective only for positive values of the flow for this +direction for example, this is the definition of DIRECT. If the value is OPPOSITE the threshold will be effective only +for negative values of the flow on this line. And eventually the value BOTH will make it effective for both negative +and positive values. + +### Additional values + +- An FRM value in specified for each CNEC, its value is in MW. Then the effective threshold value for the optimiser will + be the one of the threshold diminished by the FRM value. Several conversions might take place whether we want the + threshold in A or in MW. +- A critical branch can be either a CNEC (optimised) or a MNEC (monitored) or actually both of these. For those that are + neither a CNEC nor a MNEC they will be ignored. +- TSO origin for the critical branch is also specified. As tie-lines are usually defined in two parts in the CRAC there + will always be only one TSO implied per CNEC. + +## Remedial actions + +```xml + + + FR + + true + false + false + ... + + +``` + +Remedial actions can be of different types, but they will always have : +- An ID +- A human-readable name +- Its TSO origin + +Then it has the <actionSet> tag : +- <preventive> tag : if true a usage rule will be added to the remedial action to make it available on preventive state +- <curative> tag : if true some usage rules will be added to the remedial action to make it available on specified + curative states. To specify these states <afterCOId> tag will be used, they defined the outages after which this + remedial action will be available. +- <enforced> tag : it is not used for now + +Eventually different <action> tags can be used to define the concrete actions on the network for the remedial action. + +### Network actions +```xml + + + OPEN + +``` +Network actions are defined with the type "STATUS". The information they need is: +- The network element that is modified +- The type of action (OPEN/CLOSE) + +### Range actions +```xml + + + + -10 + 10 + + PST_G1 + +``` +Only PST range actions can be defined in FlowBasedConstraint documents. They are fully defined using: +- Their network element +- Their allowed tap range +- Eventually, if they belong to a group of aligned PSTs, the ID of the group + + +### Special rules +In order to ensure the imported CRAC is usable in the RAO, FARAO implements these special rules for FlowBasedConstraint documents: +- If multiple PST remedial actions are defined for the same network element and the same state, only one is imported (priority is given to PSTs that have a group ID defined) +- FARAO adds LoopFlow constraints for all critical branches with names ending with "[XX]" (where "XX" is a country code), even if the critical branch is internal to a country + diff --git a/docs/input-data/crac/import.md b/docs/input-data/crac/import.md new file mode 100644 index 0000000000..33a2ae3877 --- /dev/null +++ b/docs/input-data/crac/import.md @@ -0,0 +1,125 @@ +# CRAC import & creation + +## CRAC import/export + +The [FARAO CRAC object model](json) can be directly imported and exported using the farao-crac-io-api. + +The JSON format - also called FARAO internal format - is a raw image of the CRAC object model of FARAO. It is particularly suited to exchange a CRAC java object through files, for instance to exchange CRAC data between microservices or Kubernetes pods of an application. It has an importer and an exporter. The complete round-trip (java objectΒ β†’ exportΒ β†’ json fileΒ β†’ importΒ β†’ java object) has been designed so that the CRAC at the beginning of the chain is exactly the same as the one at the end of the chain. + +Examples of JSON formats are given on this [page](json). +Examples of uses of the farao-crac-io-api are given below: +~~~java +// import a CRAC from a PATH +Crac crac = CracImporters.importCrac(Paths.get("/tmp/crac.json")); + +// import a CRAC from an input stream +Crac crac = CracImporters.importCrac("crac.json", new FileInputStream(new File("/tmp/crac.json"))); + +// export a CRAC in JSON in a file +CracExporters.exportCrac(crac, "Json", Paths.get("/tmp/crac.json")); + +// export a CRAC in security limit format in an output stream +// (a network is required for this exporter) +CracExporters.exportCrac(crac, network, "SecurityLimit", outputStream); +~~~ + +## Versioning of internal JSON CRAC files +Json files and json importer/exporter are versioned. +The version number does not correspond to the version number of farao-core. The version only increase when a modification is made within the JSON importer / exporter. +- The number version of the json files corresponds to the number of version of the exporter by which it has been exported. +- A Json file can be imported by farao-core only if the versions of the file and the importer are compatible (see below) + + +| File version (example) | Importer version (example) | Is compatible? | Explanation | +|------------------------|----------------------------|----------------|-------------| +| 1.0 | 1.0 | YES | | +| 1.0 | 1.1 | YES | The importer is compatible with all the previous versions of the json file, **given that the first number of the version does not change**! | +| 1.1 | 1.0 | NO[^1] | The importer is *a priori* not compatible with newer versions of the file.
For instance, if a json CRAC is generated with farao-core 3.5.0 (importer version = 1.1) and read with farao-core 3.4.3 (importer version = 1.0), the importer should not work.
However, the import is not systematically rejected. It might even work in some situation.
For instance, in the example above, if a 1.1 crac does not contain the feature specific to its version, the newly introduced switchPair elementary action, it will still be importable by the 1.0 importer. | +| 1.0 | 2.0 | NO | compatibility is not ensured anymore when first version number change | +| 2.0 | 1.0 | NO | compatibility is not ensured anymore when first version number change | + +[^1]: might work in some situations + + +## NativeCrac, CracCreators and CracCreationContext + +The FARAO CRAC object model is not a bijection of all existing formats. To handle more complex formats, which do not have a one-to-one mapping with the FARAO CRAC object model, an overlay has been designed. + +![NativeCrac](/_static/img/NativeCrac.png) + +- The **NativeCrac** is a java object which is a raw representation of the initial CRAC "complex" format. The NativeCrac contains all the information present in the initial file. For instance, for xml CRAC formats, their NativeCrac contains classes which are automatically generated from the XSD of the format. + +- The NativeCrac can be imported from a file with a **NativeCracImporter**. + +- The NativeCrac can be converted in a CRAC with a **CracCreator**, the CracCreator needs a network to interpret the data +of the NativeCrac. Moreover, the creators of formats which contain more than one timestamp also need a timestamp in the +form of a java OffsetDateTime as the created CRAC object only contains one timestamp. [CracCreationParameters](creation-parameters) +can also be provided to the CracCreator, with some configurations which set the behaviour of the Creator. + +- The CracCreator returns a [CracCreationContext](creation-context). It contains: +-- the created CRAC object +-- additional information which explains how the initial format has been mapped into the FARAO format. This mapping is often not straightforward (see below). The CracCreationContext enables to keep in memory a link between the NativeCrac and the CRAC objects. + + +> πŸ’‘ **NOTE** +> The flow-based constraint document contains two types of CNECs: base-case CNECs and post-contingency CNECs. Each post-contingency CNECs corresponds to two FlowCnecs in FARAO: one FlowCnec associated with the outage instant and one FlowCnec associated with a curative instant. The initial id of the CNEC cannot be kept, as it would be duplicated into the FARAO format, and new ids are therefore created by the CracCreator on the fly. +> +> As a consequence, the interpretation of the created CRAC is not straightforward as it contains more Cnecs than the initial format, and with different ids. +> +> The CracCreationContext is here to ease the interpretation of the CRAC, and for instance store the information on how each CNEC of the initial format has been mapped - in one or two FlowCnecs - and for a given CNEC of the initial format, what are the id(s) of the created FlowCnec(s). +> +> This is an example, but the CracCreationContext of the fb-constraint-document is also used for other reasons, such as: +> - keep track of the data which hasn't been imported in FARAO due to quality issue +> - keep track of the branch which has been inverted because the initial format was not consistent with the iidm network (the Network is needed for that operation, that is an example of the reason why it is required by the CracCreator) +> - keep some information of the initial format which are not imported in the FARAO CRAC. +> +> In the CORE CC process, this CracCreationContext is re-used when results are exported at the end of the RAO, in order to roll back the modifications which has been made during the creation, and export at the end of the process a CNE file which is consistent with the initial CRAC file. + +The formats handled by the CracCreator are: +- [FlowBasedConstraint document](fbconstraint), also known as Merged-CB, CBCORA or F301 ([farao-crac-creator-fb-constraint](https://github.com/powsybl/powsybl-open-rao/tree/main/data/crac-creation/crac-creator-fb-constraint)) +- [CSE CRAC](cse) ([farao-crac-creator-cse](https://github.com/powsybl/powsybl-open-rao/tree/main/data/crac-creation/crac-creator-cse)) +- [CIM CRAC](cim) ([farao-crac-creator-cim](https://github.com/powsybl/powsybl-open-rao/tree/main/data/crac-creation/crac-creator-cim)) +- [CSA PROFILES CRAC](csa) ([farao-crac-creator-csa-profiles](https://github.com/powsybl/powsybl-open-rao/tree/main/data/crac-creation/crac-creator-csa-profiles)) + +When creating a CRAC from one of these formats, the chain presented above can be coded step by step, or utility methods can be used to make all the import in one line of code. Some examples are given below: + +~~~java +// use the crac-creator-api to import a Crac in one go +Crac crac = CracCreators.importAndCreateCrac(Paths.get("/complexCrac.xml"), network, null).getCrac(); + + +// use the crac-creator-api to import a Crac in two steps, with one timestamp +OffsetDateTime offsetDateTime = OffsetDateTime.parse("2019-01-08T00:30Z"); + +NativeCrac nativeCrac = NativeCracImporters.importData(Paths.get("/complexCrac.xml")); +CracCreationContext cracCreationContext = CracCreators.createCrac(nativeCrac, network, offsetDateTime); + +Crac crac = cracCreationContext.getCrac(); + +// if the format is known, use directly the suited implementations of NativeCracImporter and CracCreator +// if no configuration is explicitly given, use the default one +// this approach is preferred as the previous one is the format is known, as it returns directly the expected implementation of the CracCreationContext +FbConstraint nativeCrac = new FbConstraintImporter().importNativeCrac(new FileInputStream(new File("fbDocument.xml"))); +CracCreationParameters paramaters = CracCreationParameters.load(); +FbConstraintCreationContext cracCreationContext = new FbConstraintCracCreator().createCrac(nativeCrac, network, offsetDateTime, parameters); +Crac crac = cracCreationContext.getCrac(); + +// alternatively, create a CRAC using a specific import configuration load from a JSON format +CracCreationParameters parameters = JsonCracCreationParameters.read(getClass().getResourceAsStream("/parameters/cse-crac-creation-parameters-nok.json")); +~~~ + +## Implementing new CRAC formats +You are welcome to contribute to the project if you need to import a new native CRAC format to be used in FARAO. +You can find inspiration in existing CRAC creators' code: +- [farao-crac-creator-fb-constraint](https://github.com/powsybl/powsybl-open-rao/tree/main/data/crac-creation/crac-creator-fb-constraint) +- [farao-crac-creator-cse](https://github.com/powsybl/powsybl-open-rao/tree/main/data/crac-creation/crac-creator-cse) +- [farao-crac-creator-cim](https://github.com/powsybl/powsybl-open-rao/tree/main/data/crac-creation/crac-creator-cim) +- [farao-crac-creator-csa-profiles](https://github.com/powsybl/powsybl-open-rao/tree/main/data/crac-creation/crac-creator-csa-profiles) + +To help you with that, the package [farao-crac-creation-util](https://github.com/powsybl/powsybl-open-rao/tree/main/data/crac-creation/crac-creation-util) +offers utility classes that can make mapping the CRAC elements to the PowSyBl network elements much easier. +You should also get familiar with our java [CRAC creation API](json). + +## Example of application of CRAC creation / import / export + +![flow-diagram](/_static/img/flow-diagram-nativeCrac.png) diff --git a/docs/input-data/crac/index.rst b/docs/input-data/crac/index.rst new file mode 100644 index 0000000000..e9665ee54c --- /dev/null +++ b/docs/input-data/crac/index.rst @@ -0,0 +1,17 @@ +CRAC +==== + +Reference documentation for Open RAO's CRAC input data + +.. toctree:: + :maxdepth: 2 + + introduction.md + import.md + creation-parameters.md + json.md + fbconstraint.md + cse.md + cim.md + csa.md + creation-context.md diff --git a/docs/input-data/crac/introduction.md b/docs/input-data/crac/introduction.md new file mode 100644 index 0000000000..548a1637ee --- /dev/null +++ b/docs/input-data/crac/introduction.md @@ -0,0 +1,51 @@ +# Introduction + +The CRAC (***C**ontingency list, **R**emedial **A**ctions and additional **C**onstraints*) file model contains two main categories of objects: +- CNECs, containing the network elements to be monitored after given contingencies, +- and the remedial actions that can be used to secure these elements. + +## CNEC + +CNEC means *Critical Network Element & Contingency* as defined in the literature. It associates a **network element** with a **state**: it represents a network element at a specific instant in preventive state or after a contingency. + +A CNEC is associated to **thresholds**. These thresholds can be of different types according to the considered network element, so that flows, voltage levels and angles can be monitored on these CNECs. Flow thresholds are usually associated to lines, while voltage and angle thresholds are usually associated to nodes. + +## Remedial action + +FARAO distinguishes two types of remedial actions, **range actions** and **network actions**. The key difference between the two types is that the latter has only two possible states (activated/deactivated), while the former can be activated in different "ways". + +### Range action + +Range actions are actions on the network with a degree of freedom: the choice of a **set-point** within a given range. +These actions can be optimised linearly, with some approximations. For more information related to the linear optimisation +of range actions in FARAO, please refer to the [dedicated documentation page](https://farao-community.github.io/docs/engine/ra-optimisation/linear-rao). + +They can be defined on some categories of network elements: +- Phase Shift Transformer (PST), +- HVDC line, +- Production unit. + +A range action can also be a counter-trade remedial action corresponding to an exchange from an exporting country to an +importing country. + +The determination of the optimal set-point improving a network situation requires some data: +- the current value in a specified network, +- the minimal reachable value according to the specified network – or the maximal authorized variation for a decreasing variation, +- the maximal reachable value according to the specified network – or the maximal authorized variation for an increasing variation, +- the sensitivity of a set-point variation on every CNEC for the specified network. + +Any 2 or more range actions (of same type) can be aligned into range action "groups" in FARAO, which constrains the RAO to set them to the same set-point at all times. + +### Network action + +Network actions are any other kind of action on the network, such as the opening/closing of a network element, setting the tap position of a PST to a given set-point, etc. They can only be activated, or remain inactive. +They are used in the [search-tree RAO](https://farao-community.github.io/docs/engine/ra-optimisation/search-tree-rao) only. +One network action can combine one or multiple elementary actions. These are the types of elementary actions handled in FARAO: +#### Topological actions +It consists in the opening or the closing of one branch or one switch of the network. +#### PST set-point +It consists in the modification of the tap of a PST to a pre-defined target tap. +#### Injection set-point +It consists in the modification of an injection (load, generator, dangling line or shunt compensator) to a pre-defined set-point. +#### Switch pair +It consists in opening a switch and closing another. diff --git a/docs/input-data/crac/json.md b/docs/input-data/crac/json.md new file mode 100644 index 0000000000..446b700ad2 --- /dev/null +++ b/docs/input-data/crac/json.md @@ -0,0 +1,1339 @@ +--- +title: Internal json CRAC format +--- + +# Internal json CRAC format + +## Introduction + +The name CRAC is a standard denomination defined by the ENTSO-E which means: **C**ontingency list, **R**emedial +**A**ctions, and additional **C**onstraints. + +In other words, it gathers the following information: +- critical outages, +- critical network elements, +- and remedial actions. + +It is typically used in European coordinated processes. It enables, for a given geographical region, to define the +network elements that might be critical after specific outages, and the remedial actions that might help to manage them. + +**A CRAC object model has been designed in FARAO** in order to store all the aforementioned information. This page aims to present: +- the content and the organization of the data present in the FARAO CRAC object model, +- how a FARAO CRAC object can be built, + - using the java API, + - or using the FARAO internal Json CRAC format. + +Note that other pages of this documentation describe how the FARAO CRAC object model can be built with other standard +CRAC formats, such as the [FlowBasedConstraint](fbconstraint) format, the [CSE](cse) Format, and the [CIM](cim) format. + +## Full CRAC examples +Example of complete CRACs are given below + +::::{tabs} +:::{group-tab} JAVA creation API +The creation of a small CRAC is for instance made in this test class of farao-core repository: +[example on GitHub](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac/crac-impl/src/test/java/com/powsybl/openrao/data/cracimpl/utils/CommonCracCreation.java) +::: +:::{group-tab} JSON file +An example of a small CRAC in the json internal format of FARAO is given below: +[example on GitHub](https://github.com/powsybl/powsybl-open-rao/blob/main/ra-optimisation/search-tree-rao/src/test/resources/crac/small-crac-with-network-actions.json) +::: +:::: + +The following paragraphs of this page explain, step by step, the content of these examples. + +> **KEY** +> πŸ”΄ marks a **mandatory** field +> βšͺ marks an **optional** field +> πŸ”΅ marks a field that can be **mandatory in some cases** +> ⭐ marks a field that must be **unique** in the CRAC + +## Network elements +FARAO relies on the [PowSyBl framework](https://www.powsybl.org/), and FARAO's CRAC relies on some elements of +[PowSyBl's network model](https://www.powsybl.org/pages/documentation/grid/model/): the so-called network elements. + +The network elements can be: +- the elements that are disconnected from the network by a contingency, +- the power lines that are identified as critical network elements in the CRAC, +- the PSTs that are identified by the CRAC as remedial actions, +- the switches that can be used as topological remedial actions... + +Network elements are referenced in the CRAC with: + +πŸ”΄β­ an id +: The id **must** match the [unique id of a PowSyBl object](https://www.powsybl.org/pages/documentation/grid/model/#introduction). +When using a network element, the applications relying on the CRAC will look in the Network for an identifiable element +with the very same id: if this element cannot be found, it can lead to an error in the application. When building the CRAC, +one must therefore make sure that only the network elements whose IDs can be understood by the PowSyBl iidm Network are +added to the CRAC. This is particularly important to keep in mind if you want to [develop your own CRAC importer](import.md#implementing-new-crac-formats). + +βšͺ a name +: The name shouldn't be absolutely required by the application relying on the CRAC object, but it could be useful to +make the CRAC or some outputs of the application more readable for humans. + +::::{tabs} +:::{group-tab} JAVA creation API +Network elements are never built on their own in the CRAC object: they are always a component of a larger business object, +and are added implicitly to the CRAC when the business object is added (e.g. a contingency, a CNEC, or a remedial action). +When building a business object, one of the two following methods can be used to add a network element to it (using an +ID only, or an ID and a name). +~~~java +(...).withNetworkElement("network_element_id") +(...).withNetworkElement("network_element_id", "network_element_name") +~~~ +These methods will be depicted in the following examples on this page. +::: +:::{group-tab} JSON file +Network elements' IDs are defined within the objects that contain them. Examples are given later in this page, +for contingencies, CNECs and remedial actions. Moreover, the internal Json CRAC format contains an index of network +element names, in which network elements that have a name are listed, with their name and their ID. +~~~json +"networkElementsNamePerId" : { + "network_element_id_1" : "[BE-FR] Interconnection between Belgium and France", + "network_element_id_4" : "[DE-DE] Internal PST in Germany" +}, +~~~ +::: +:::: + +## Contingencies +A CRAC object must define "critical contingencies" (or "critical outages", or "CO", or "N-k"...). +The denomination chosen within the FARAO internal format is **"Contingency"**. + +A contingency is the representation of an incident on the network (i.e. a cut line or a group/transformer failure, etc.). +In FARAO, it is modelled by the loss of one or several network elements. Usually we have either a one-network-element-loss +called "N-1", or a two-network-element-loss called "N-2". + +Examples: +- N-1: The loss of one generator +- N-2: The loss of two parallel power lines + +A contingency is a probable event that can put the grid at risk. Therefore, contingencies must +be considered when operating the electrical transmission / distribution system. + +In FARAO, contingencies are defined in the following way: + +::::{tabs} +:::{group-tab} JAVA creation API +~~~java +crac.newContingency() + .withId("CO_0001") + .withName("N-1 on generator") + .withNetworkElement("powsybl_generator_id", "my_generators_name") + .add(); + +crac.newContingency() + .withId("CO_0002") + .withName("N-2 on electrical lines") + .withNetworkElement("powsybl_electrical_line_1_id") + .withNetworkElement("powsybl_electrical_line_2_id") + .add(); +~~~ +::: +:::{group-tab} JSON file +~~~json +"contingencies" : [{ + "id" : "CO_0001", + "name" : "N-1 on generator", + "networkElementsIds" : [ "powsybl_generator_id" ] +}, { + "id" : "CO_0002", + "name" : "N-1 electrical lines", + "networkElementsIds" : [ "powsybl_electrical_line_1_id", "powsybl_electrical_line_2_id" ] +}], +~~~ +::: +:::{group-tab} Object fields +πŸ”΄β­ **identifier** +βšͺ **name** +βšͺ **network elements**: list of 0 to N network elements +       πŸ”΄ **network element id**: must be the id of a PowSyBl network identifiable +       βšͺ **network element names**: names are optional, they can be used to make the CRAC +more understandable from a business viewpoint, but applications relying on the CRAC do not necessarily need them. +::: +:::: + +> πŸ’‘ **NOTE** +> The network elements currently handled by FARAO's contingencies are: internal lines, interconnections, transformers, +> PSTs, generators, HVDCs, bus-bar sections, and dangling lines. + +## Instants and States +The instant is a moment in the chronology of a contingency event. Four instants kinds currently exist in FARAO: +- the **preventive** instant kind occurs before any contingency, and describes the "base-case" situation. A CRAC may + contain only one instant of kind preventive. +- the **outage** instant kind occurs just after a contingency happens, in a time too short to allow the activation of any + curative remedial action. A CRAC may contain only one instant of kind outage. +- the **auto** instant kind occurs after a contingency happens, and spans through the activation of automatic curative + remedial actions ("automatons") that are triggered without any human intervention. These automatons are pre-configured + to reduce some constraints, even though they can generate constraints elsewhere in the network. A CRAC may contain any + number of instants of kind auto. +- the **curative** instant kind occurs after a contingency happens, after enough time that would allow the human activation + of curative remedial actions. A CRAC may contain any number of instants of kind auto. + +> πŸ’‘ **NOTE** +> Flow / angle / voltage limits on critical network elements are usually different for each instant. +> The outage and auto instant kinds are transitory, therefore less restrictive temporary limits (TATL) can be allowed in +> these instants. +> On the contrary, the preventive and curative instant kinds are supposed to be a lasting moment during which the grid +> operation is nominal (sometimes thanks to preventive and/or curative remedial actions), so they usually come with +> more restrictive permanent limits (PATL). +> FARAO allows a different limit setting for different instants on critical network elements (see [CNECs](#cnecs)). +> +> ![patl-vs-tatl](/_static/img/patl-tatl.png) +> (**PRA** = Preventive Remedial Action, +> **ARA** = Automatic Remedial Action, +> **CRA** = Curative Remedial Action) + +The FARAO object model includes the notion of "state". A state is either: + +- the preventive state: the state of the base-case network, without any contingency, at the preventive instant. +- the combination of a given contingency with instant outage, auto or curative: the state of the network after the said + contingency, at the given instant (= with more or less delay after this contingency). + +The scheme below illustrates these notions of instant and state. It highlights the combinations of the situations which can be described in a CRAC, with a base-case situation, but also variants of this situation occurring at different moments in time after different probable and hypothetical contingencies. + +![Instants & states](/_static/img/States_AUTO.png) + +States are not directly added to a FARAO CRAC object model; they are implicitly created by business objects +that are described in the following paragraphs ([CNECs](#cnecs) and [remedial actions](#remedial-actions-and-usages-rules)). + +Instants are added one after the other in the CRAC object. +The first instant must be of kind preventive. +The second instant must be of kind outage. + +::::{tabs} +:::{group-tab} JAVA creation API +~~~java +crac.newInstant("preventive", InstantKind.PREVENTIVE) + .newInstant("outage", InstantKind.OUTAGE) + .newInstant("auto", InstantKind.AUTO) + .newInstant("curative1", InstantKind.CURATIVE) + .newInstant("curative2", InstantKind.CURATIVE); +~~~ +::: +:::{group-tab} JSON file +~~~json + "instants" : [ { + "id": "preventive", + "kind": "PREVENTIVE" + }, { + "id": "outage", + "kind": "OUTAGE" + }, { + "id": "auto", + "kind": "AUTO" + }, { + "id": "curative1", + "kind": "CURATIVE" + }, { + "id": "curative2", + "kind": "CURATIVE" + } ], +~~~ +::: +:::: + + +## CNECs +A CRAC should define CNECs. A CNEC is a "**C**ritical **N**etwork **E**lement and **C**ontingency" (also known as "CBCO" +or "Critical Branch and Critical Outage"). + +A CNEC is a **network element**, which is considered at a given **instant**, after a given **contingency** (i.e. at a +given FARAO ["state"](#instants-and-states)). +The contingency is omitted if the CNEC is defined at the preventive instant. + +> πŸ’‘ **NOTE** +> A FARAO CNEC is associated to one instant and one contingency only. This is not the case for all native CRAC formats: +> for instance, in the [CORE merged-CB CRAC format](fbconstraint), the post-outage CNECs are implicitly defined for the +> two instants outage and curative. +> +> However, we are talking here about the internal FARAO CRAC format, which has its own independent conventions, and which +> is imported from native CRAC formats using [CRAC importers](import). + +A CNEC has an operator, i.e. the identifier of the TSO operating its network element. +Moreover, a CNEC can have a reliability margin: a safety buffer to cope with unplanned events or uncertainties of input +data (i.e. an extra margin). + +### Optimised and monitored CNECs +CNECs can be monitored and/or optimised. This notion of monitored/optimised has been introduced by the capacity +calculation on the CORE region, and is now also used for the CSE region: +- maximise the margins of CNECs that are "optimised" +- ensure that the margins of "monitored" CNECs are positive and/or are not decreased by the RAO. + +FARAO contains 3 families of CNECs, depending on which type of physical constraints they have: **FlowCnecs**, +**AngleCnecs** and **VoltageCnecs**. + +### Flow CNECs +A "FlowCnec" has the two following specificities: + +- it contains one network element that is a **Branch**. In the PowSyBl vocabulary, a "Branch" + is an element connected to two terminals. For instance, + [lines](https://www.powsybl.org/pages/documentation/grid/model/#line), + [tie-lines](https://www.powsybl.org/pages/documentation/grid/model/#tie-line), + [transformers](https://www.powsybl.org/pages/documentation/grid/model/#transformers) + and [PSTs](https://www.powsybl.org/pages/documentation/grid/model/#phase-tap-changer) + are all "Branches". +- the physical parameter which is monitored on the CNEC is the **power flow**. + +A FlowCnec has **two sides**, which correspond to the two terminals of the PowSyBl network element of the FlowCnec +(usually called terminals "one" and "two", or terminals "left" and "right"). +The notion of **direction** is also inherent to the FlowCnec: a flow in direction "direct" is a flow from terminal +one/left to terminal two/right, while a flow in direction "opposite" is a flow from terminal two/right to terminal +one/left. The convention of FARAO is that a positive flow is a flow in the "direct" direction, while a negative flow is +a flow in the "opposite" direction. + +> πŸ’‘ **NOTE** +> A FARAO FlowCnec is one implementation of the generic ["BranchCnec"](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac/crac-api/src/main/java/com/powsybl/openrao/data/cracapi/cnec/BranchCnec.java). +> If needed, this would allow you a fast implementation of other types of CNECs, on branches, but with a monitored +> physical parameter other than power flow. + +#### Flow limits on a FlowCnec +A FlowCnec has flow limits, called "thresholds" in FARAO. These thresholds define the limits between which the power +flow of the FlowCnec should ideally remain. +- They can be defined in megawatt, ampere, or in percentage of the Imax of the branch (in which case the Imax is read in + the network file). +- A threshold is defined either on the left or on the right side of the FlowCnec. + > πŸ’‘ **NOTE** + > The side of the branch on which the threshold is set is particularly crucial in the following cases: + > - when the threshold is defined in ampere or %Imax on a [**transformer**](https://www.powsybl.org/pages/documentation/grid/model/#transformers), + > as the current values on the two sides of a transformer are different, + > - when the threshold is defined in %Imax on a [**tie-line**](https://www.powsybl.org/pages/documentation/grid/model/#tie-line), + > as the current limits are usually different on both sides of a tie-line, + > - when the application uses **AC load-flow** computation, as the flow values on the two sides of a branch are + > different (due to losses). The CracCreationParameters allows the user to [decide which side(s) should be monitored by default](creation-parameters.md#default-monitored-line-side). +- A threshold has a minimum and/or a maximum value. The maximum value represents the maximum value of the flow in the "direct" direction + and the minimum value represents the maximum value of the flow in the "opposite" direction. + Therefore, for FlowCnecs that only have one minimum or one maximum value, the flow is implicitly monitored in + only one direction (see example 1 of picture below). + +![FlowCnec-Threshold](/_static/img/flowcnec.png) + + +In the examples above, all the thresholds are defined in megawatt. If the thresholds are defined in ampere, or in %Imax, +additional data is required in order to handle the following conversions: +- if one threshold of the FlowCnec is in ampere or in percentage of Imax, the nominal voltage on both sides of the threshold must be defined +- if one threshold of the FlowCnec is in percentage of Imax, the Imax of the FlowCnec on the side of the threshold must be defined + +> πŸ’‘ **NOTE** +> A FlowCnec's reliability margin is also known as FRM for Flow Reliability Margin. +> It can only be defined in megawatt, it is subtracted from the thresholds of the FlowCnec, adding an extra constraint. + +#### Creating a FlowCnec +In FARAO, FlowCnecs can be created by the java API, or written in the json CRAC internal format, as shown below: + +::::{tabs} +:::{group-tab} JAVA creation API +~~~java +crac.newFlowCnec() + .withId("preventive-cnec-with-one-threshold-id") + .withNetworkElement("network-element-id") + .withInstant("preventive") + .withOperator("operator1") + .withReliabilityMargin(50.) + .withOptimized(true) + .newThreshold() + .withUnit(Unit.MEGAWATT) + .withSide(Side.LEFT) + .withMin(-1500.) + .withMax(1500.) + .add() + .add(); + +crac.newFlowCnec() + .withId("curative-cnec-with-two-thresholds-id") + .withName("curative-cnec-with-two-thresholds-name") + .withNetworkElement("network-element-id") + .withInstant("curative") + .withContingency("contingency-id") + .withOperator("operator1") + .newThreshold() + .withUnit(Unit.PERCENT_IMAX) + .withSide(Side.RIGHT) + .withMax(0.95) + .add() + .newThreshold() + .withUnit(Unit.AMPERE) + .withSide(Side.LEFT) + .withMin(-450.) + .add() + .withReliabilityMargin(50.) + .withOptimized(true) + .withMonitored(false) + .withNominalVoltage(380., Side.LEFT) + .withNominalVoltage(220., Side.RIGHT) + .withIMax(500.) // this means that the value is the same on both sides, but the side could have been specified using "withImax(500., Side.RIGHT)" instead + .add(); +~~~ +::: +:::{group-tab} JSON file +~~~json +"flowCnecs" : [ { + "id" : "preventive-cnec-with-one-threshold-id", + "name" : "preventive-cnec-with-one-threshold-id", + "networkElementId" : "network-element-id", + "operator" : "operator1", + "instant" : "preventive", + "optimized" : true, + "monitored" : false, + "frm" : 50.0, + "thresholds" : [ { + "unit" : "megawatt", + "min" : -1500.0, + "max" : 1500.0, + "side" : "left" + } ] +}, { + "id" : "curative-cnec-with-two-thresholds-id", + "name" : "curative-cnec-with-two-thresholds-name", + "networkElementId" : "network-element-id", + "operator" : "operator1", + "instant" : "curative", + "contingencyId" : "contingency-id", + "optimized" : true, + "monitored" : false, + "frm" : 50.0, + "iMax" : [ 500.0 ], + "nominalV" : [ 380.0, 220.0 ], + "thresholds" : [ { + "unit" : "ampere", + "min" : -450.0, + "side" : "left" + }, { + "unit" : "percent_imax", + "max" : 0.95, + "side" : "right" + } ] +} ] +~~~ +::: +:::{group-tab} Object fields +πŸ”΄β­ **identifier** +βšͺ **name** +πŸ”΄ **network element**: one network element +       πŸ”΄ **network element id**: must be the id of a PowSyBl network identifiable +       βšͺ **network element name** +πŸ”΄ **instant** +πŸ”΅ **contingency**: mandatory, except if the instant is preventive. Must be the id of a contingency which exists in the CRAC +βšͺ **operator** +βšͺ **reliability margin**: default value = 0 MW +βšͺ **optimized**: default value = false +βšͺ **monitored**: default value = false +πŸ”΄ **thresholds**: list of 1 to N thresholds, a FlowCnec must contain at least one threshold +       πŸ”΄ **unit** +       πŸ”΄ **side** +       πŸ”΅ **minValue** +       πŸ”΅ **maxValue**: at least one of minValue/maxValue should be defined +πŸ”΅ **nominal voltages**: mandatory if the FlowCnec has at least one threshold in %Imax or A +πŸ”΅ **iMax**: mandatory if the FlowCnec has at least one threshold in %Imax +::: +:::: + +#### Loop-flow extension +When a FlowCnec carries a LoopFlowThreshold extension (and if [loop-flow constraints are enabled in the RAO](https://farao-community.github.io/docs/parameters#loop-flow-parameters)), +its loop-flow is monitored by the RAO, that will keep it [under its threshold](https://farao-community.github.io/docs/engine/ra-optimisation/loop-flows) +when optimising remedial actions. +The loop-flow extension defines the loop-flow threshold to be respected by the RAO (even though the initial loop-flow +value on this CNEC may override this user-defined thrshold, as explained [here](https://farao-community.github.io/docs/castor/linear-optimisation-problem/max-loop-flow-filler)). + +::::{tabs} +:::{group-tab} JAVA creation API +~~~java +flowCnec = crac.getFlowCnec("cnec-with-mw-loop-flow-extension"); +flowCnec.newExtension(LoopFlowThresholdAdder.class) + .withUnit(Unit.MEGAWATT) + .withValue(150.0) + .add(); + +flowCnec = crac.getFlowCnec("cnec-with-pimax-loop-flow-extension"); +flowCnec.newExtension(LoopFlowThresholdAdder.class) + .withUnit(Unit.PERCENT_IMAX) + .withValue(0.9) + .add(); +~~~ +::: +:::{group-tab} JSON file +~~~json +"flowCnecs" : [ { + "id" : "cnec-with-mw-loop-flow-extension", + ... + "extensions" : { + "LoopFlowThreshold" : { + "inputThreshold" : 150.0, + "inputThresholdUnit" : "megawatt" + } + } +}, { + "id" : "cnec-with-pimax-loop-flow-extension", + ... + "extensions" : { + "LoopFlowThreshold" : { + "inputThreshold" : 0.9, + "inputThresholdUnit" : "percent_imax" + } + } +} ] +~~~ +::: +:::{group-tab} Object fields +πŸ”΄ **unit**: unit of the threshold +πŸ”΄ **value**: value of the threshold in the given unit +       *(if the unit is %Imax, the value should be between 0 and 1, where 1 = 100%)* +::: +:::: + +### Angle CNECs +An "AngleCnec" is a branch which may see a phase angle shift between its two ends when it's disconnected. This may induce +insecurities in the network when it's back up. That's why we monitor angle CNECs and associate with them remedial actions +(generally re-dispatching) that can reduce the phase angle shift between the two ends. + +In terms of FARAO object model, an AngleCnec is a CNEC. Even though it is associated with a branch, it is not a +BranchCnec, because we cannot define on which side it is monitored: it is monitored on both sides (more specifically, +we monitor the phase shift between the two sides). + +An AngleCnec has the following specificities: + +- it contains two network elements, an importing node and an exporting node, that represent the importing and exporting ends of the branch. +- the physical parameter which is monitored by the CNEC is the **angle**. +- it must contain at least one threshold, defined in degrees. A threshold has a minimum and/or a maximum value. + +> πŸ’‘ **NOTE** +> AngleCnecs currently cannot be optimised by the RAO, but they are monitored by an independent +> [AngleMonitoring](https://farao-community.github.io/docs/engine/monitoring/angle-monitoring) module. + +#### Creating an AngleCnec +In FARAO, AngleCnecs can be created by the java API, or written in the json CRAC internal format, as shown below: + +::::{tabs} +:::{group-tab} JAVA creation API +~~~java + cnec1 = crac.newAngleCnec() + .withId("angleCnecId1") + .withName("angleCnecName1") + .withInstant("outage") + .withContingency(contingency1Id) + .withOperator("cnec1Operator") + .withExportingNetworkElement("eneId1", "eneName1") + .withImportingNetworkElement("ineId1", "ineName1") + .newThreshold() + .withUnit(Unit.DEGREE) + .withMax(1000.0) + .withMin(-1000.0) + .add() + .withMonitored() + .add(); + +cnec2 = crac.newAngleCnec() + .withId("angleCnecId2") + .withInstant("preventive") + .withOperator("cnec2Operator") + .withExportingNetworkElement("eneId2") + .withImportingNetworkElement("ineId2") + .withReliabilityMargin(5.0) + .newThreshold() + .withUnit(Unit.DEGREE) + .withMax(500.0) + .add() + .withMonitored() + .add(); +~~~ +::: +:::{group-tab} JSON file +~~~json + "angleCnecs" : [ { + "id" : "angleCnecId1", + "name" : "angleCnecName1", + "exportingNetworkElementId" : "eneId1", + "importingNetworkElementId" : "ineId1", + "operator" : "cnec1Operator", + "instant" : "outage", + "contingencyId" : "contingency1Id", + "optimized" : false, + "monitored" : true, + "reliabilityMargin" : 0.0, + "thresholds" : [ { + "unit" : "degree", + "min" : -1000.0, + "max" : 1000.0 + } ] + } ], + "angleCnecs" : [ { + "id" : "angleCnecId2", + "exportingNetworkElementId" : "eneId2", + "importingNetworkElementId" : "ineId2", + "operator" : "cnec2Operator", + "instant" : "preventive", + "optimized" : false, + "monitored" : true, + "reliabilityMargin" : 5.0, + "thresholds" : [ { + "unit" : "degree", + "max" : 500.0 + } ] + } ] +~~~ +::: +:::{group-tab} Object fields +πŸ”΄β­ **identifier** +βšͺ **name** +πŸ”΄ **importing network element**: one network element +       πŸ”΄ **network element id**: must be the id of a PowSyBl network identifiable +       βšͺ **network element name** +πŸ”΄ **exporting network element**: one network element +       πŸ”΄ **network element id**: must be the id of a PowSyBl network identifiable +       βšͺ **network element name** +πŸ”΄ **instant** +πŸ”΅ **contingency**: mandatory, except if the instant is preventive. Must be the id of a contingency which exists in the CRAC +βšͺ **operator** +βšͺ **reliability margin**: default value = 0 Β° +βšͺ **optimized**: default value = false +βšͺ **monitored**: default value = false +πŸ”΄ **thresholds**: list of 1 to N thresholds, an AngleCnec must contain at least one threshold +       πŸ”΄ **unit** : must be in degrees +       πŸ”΅ **minValue** +       πŸ”΅ **maxValue**: at least one of these two values (min/max) is required +::: +:::: + +### Voltage CNECs +A "VoltageCnec" is a CNEC on which we monitor the voltage on substations. It has the following specificities: +- it contains one network element (a [VoltageLevel](https://www.powsybl.org/pages/documentation/grid/model/#voltage-level)) +- the physical parameter which is monitored by the CNEC is the **voltage**. +- it must contain at least one threshold, defined in kilovolts. A threshold has a minimum and/or a maximum value. + +> πŸ’‘ **NOTE** +> VoltageCnecs currently cannot be optimised by the RAO, but they are monitored by an independent +> [VoltageMonitoring](https://farao-community.github.io/docs/engine/monitoring/voltage-monitoring) module. + +#### Creating a VoltageCnec +In FARAO, VoltageCnecs can be created by the java API, or written in the json CRAC internal format, as shown below: + +::::{tabs} +:::{group-tab} JAVA creation API +~~~java +crac.newVoltageCnec() + .withId("voltageCnecId1") + .withName("voltageCnecName1") + .withInstant("outage") + .withContingency(contingency1Id) + .withOperator("cnec1Operator") + .withNetworkElement("neId1", "neName1") + .newThreshold() + .withUnit(Unit.KILOVOLT) + .withMax(420.0) + .withMin(360.0) + .add() + .withMonitored() + .add(); +crac.newVoltageCnec() + .withId("voltageCnecId2") + .withInstant("preventive") + .withOperator("cnec2Operator") + .withNetworkElement("neId2") + .newThreshold() + .withUnit(Unit.KILOVOLT) + .withMax(440.0) + .add() + .withMonitored() + .add(); +~~~ +::: +:::{group-tab} JSON file +~~~json + "voltageCnecs" : [ { + "id" : "voltageCnecId1", + "name" : "voltageCnecName1", + "networkElementId" : "neId1", + "operator" : "cnec1Operator", + "instant" : "outage", + "contingencyId" : "contingency1Id", + "optimized" : false, + "monitored" : true, + "reliabilityMargin" : 0.0, + "thresholds" : [ { + "unit" : "kilovolt", + "min" : 360.0, + "max" : 420.0 + } ] + } ], + "voltageCnecs" : [ { + "id" : "voltageCnecId2", + "networkElementId" : "neId2", + "operator" : "cnec2Operator", + "instant" : "preventive", + "optimized" : false, + "monitored" : true, + "reliabilityMargin" : 0.0, + "thresholds" : [ { + "unit" : "kilovolt", + "max" : 440.0 + } ] + } ] +~~~ +::: +:::{group-tab} Object fields +πŸ”΄β­ **identifier** +βšͺ **name** +πŸ”΄ **network element**: one network element +       πŸ”΄ **network element id**: must be the id of a PowSyBl network identifiable +       βšͺ **network element name** +πŸ”΄ **instant** +πŸ”΅ **contingency**: mandatory, except if the instant is preventive. Must be the id of a contingency which exists in the CRAC +βšͺ **operator** +βšͺ **reliability margin**: default value = 0 kV +βšͺ **optimized**: default value = false +βšͺ **monitored**: default value = false +πŸ”΄ **thresholds**: list of 1 to N thresholds, a VoltageCnec must contain at least one threshold +       πŸ”΄ **unit** : must be in kilovolts +       πŸ”΅ **minValue** +       πŸ”΅ **maxValue**: at least one of these two values (min/max) is required +::: +:::: + +## Remedial actions and usages rules +A remedial action is an action on the network that is considered capable of reducing constraints on the CNECs. + +Two types of remedial action exists in FARAO: +- **Network Actions**: they have the specificity of being binary. A Network Action is either applied on the network, or + not applied. Topological actions are a typical example of Network Actions. +- **Range Actions**: they have the specificity of having a degree of freedom, a set-point. When a Range Action is + activated, it is activated at a given value of its set-point. PSTs are a typical example of Range Actions. + +Both Network Actions and Range Actions have usage rules which define the conditions under which they can be activated. +The usage rules which exist in FARAO are: +- the **FreeToUse** usage rule (defined for a specific [instant](#instants-and-states)): the remedial action is available in all + the states of a given instant. +- the **OnState** usage rule (defined for a specific [state](#instants-and-states)): the remedial action is available in a given state. +- the **OnFlowConstraintInCountry** usage rule (defined for a specific [Country](https://github.com/powsybl/powsybl-core/blob/main/iidm/iidm-api/src/main/java/com/powsybl/iidm/network/Country.java) + and a specific [instant](#instants-and-states)): the remedial action is available if any FlowCnec in the given country is + constrained (ie has a flow greater than one of its thresholds) at the given instant. +- the **OnFlowConstraint** usage rule (defined for a specific [instant](#instants-and-states) and a specific [FlowCnec](#flow-cnecs)): + the remedial action is available if the given FlowCnec is constrained at the given instant. +- the **OnAngleConstraint** usage rule (defined for a specific [instant](#instants-and-states) and a specific [AngleCnec](#angle-cnecs)): + the remedial action is available if the given AngleCnec is constrained at the given instant. +- the **OnVoltageConstraint** usage rule (defined for a specific [instant](#instants-and-states) and a specific [VoltageCnec](#voltage-cnecs)): + the remedial action is available if the given VoltageCnec is constrained at the given instant. + + +A remedial action has an operator, which is the name of the TSO which operates the remedial action. + +::::{tabs} +:::{group-tab} JAVA creation API +The examples below are given for a Network Action, but the same methods exists for Range Actions. +Complete examples of Network and Range Action creation are given in the following paragraphs. +~~~java +crac.newNetworkAction() + .newFreeToUseUsageRule() + .withUsageMethod(UsageMethod.AVAILABLE) + .withInstant("preventive") + .add(); + +crac.newNetworkAction() + .newOnStateUsageRule() + .withUsageMethod(UsageMethod.AVAILABLE) + .withInstant("curative") + .withContingency("contingency-id") + .add(); + +crac.newNetworkAction() + .newOnFlowConstraintUsageRule() + .withInstant("auto") + .withFlowCnec("flow-cnec-id") + .add(); + +crac.newNetworkAction() + .newOnFlowConstraintInCountryUsageRule() + .withInstant("preventive") + .withCountry(Country.FR) + .add(); + +crac.newNetworkAction() + .newOnAngleConstraintUsageRule() + .withInstant("curative") + .withAngleCnec("angle-cnec-id") + .add(); + +crac.newNetworkAction() + .newOnVoltageConstraintUsageRule() + .withInstant("curative") + .withVoltageCnec("voltage-cnec-id") + .add(); +~~~ +::: +:::{group-tab} JSON file +Complete examples of Network and Range Action in Json format are given in the following paragraphs +~~~json +"freeToUseUsageRules" : [ { + "instant" : "preventive", + "usageMethod" : "available" +} ], +"onStateUsageRules" : [ { + "instant" : "curative", + "contingencyId" : "contingency-id", + "usageMethod" : "available" +} ], +"onFlowConstraintUsageRules" : [ { + "instant" : "auto", + "flowCnecId" : "flow-cnec-id" +} ], +"onFlowConstraintInCountryUsageRules" : [ { + "instant" : "preventive", + "country" : "FR" +} ], +"onAngleConstraintUsageRules" : [ { + "instant" : "curative", + "angleCnecId" : "angle-cnec-id" +} ], +"onVoltageConstraintUsageRules" : [ { + "instant" : "curative", + "voltageCnecId" : "voltage-cnec-id" +} ] +~~~ +::: +:::{group-tab} Object fields +**For FreeToUse usage rules** +πŸ”΄ **instant** +πŸ”΄ **usageMethod** +**For OnState usage rules** +πŸ”΄ **instant** +πŸ”΄ **usageMethod** +πŸ”΄ **contingency**: must be the id of a contingency that exists in the CRAC +**For OnFlowConstraintInCountry usage rules** +πŸ”΄ **instant** +πŸ”΄ **country**: must be the [alpha-2 code of a country](https://github.com/powsybl/powsybl-core/blob/main/iidm/iidm-api/src/main/java/com/powsybl/iidm/network/Country.java) +**For OnFlowConstraint usage rules** +πŸ”΄ **instant** +πŸ”΄ **flowCnecId**: must be the id of a [FlowCnec](#flow-cnecs) that exists in the CRAC +**For OnAngleConstraint usage rules** +πŸ”΄ **instant** +πŸ”΄ **angleCnecId**: must be the id of an [AngleCnec](#angle-cnecs) that exists in the CRAC +**For OnVoltageConstraint usage rules** +πŸ”΄ **instant** +πŸ”΄ **voltageCnecId**: must be the id of an [VoltageCnec](#voltage-cnecs) that exists in the CRAC +**Usage methods** +FARAO handles three different types of usage methods sorted by priority: +1- **UNAVAILABLE**: the remedial action can not be considered by the RAO. +2 - **FORCED**: For automaton instant, the RAO must activate the remedial action under the condition described by the usage rule. For other instants, it will be ignored. +3 - **AVAILABLE**: For automaton instant, the remedial action is ignored. Otherwise, it can be chosen by the RAO under the condition described by the usage rule. + +*NB*: even though OnState usage rules on the preventive state is theoretically possible, it is forbidden by FARAO as the same purpose can be achieved with a FreeToUse usage rule on the preventive instant. +::: +:::: + +## Network Actions +A FARAO "Network Action" is a remedial action with a binary state: it is either active or inactive. +One network action is a combination of one or multiple "elementary actions", among the following: +- Topological action: opening or closing a branch or a switch in the network. +- PST set-point: setting the tap of a PST in the network to a specific position. +- Injection set-point: setting the active power set-point of an element in the network (load, generator, or [dangling line](https://www.powsybl.org/pages/documentation/grid/model/#dangling-line)) + or the number of sections of a shunt compensator to a specific value. +- Switch pairs: opening a switch in the network and closing another (actually used to model [CSE bus-bar change remedial actions](cse.md#bus-bar-change)). + +::::{tabs} +:::{group-tab} JAVA creation API +~~~java +// combination of two topological actions +crac.newNetworkAction() + .withId("topological-na-id") + .withName("topological-na-name") + .withOperator("operator") + .newTopologicalAction() + .withNetworkElement("network-element-id-1") + .withActionType(ActionType.CLOSE) + .add() + .newTopologicalAction() + .withNetworkElement("network-element-id-2") + .withActionType(ActionType.OPEN) + .add() + .newOnInstantUsageRule().withUsageMethod(UsageMethod.AVAILABLE).withInstant(PREVENTIVE_INSTANT).add() + .add(); + +// pst set-point +crac.newNetworkAction() + .withId("pst-setpoint-na-id") + .withName("pst-setpoint-na-name") + .withOperator("operator") + .newPstSetPoint() + .withSetpoint(15) + .withNetworkElement("pst-network-element-id") + .add() + .newOnInstantUsageRule().withUsageMethod(UsageMethod.AVAILABLE).withInstant(PREVENTIVE_INSTANT).add() + .add(); + +// injection set-point with two usage rules +crac.newNetworkAction() + .withId("injection-setpoint-na-id") + .withOperator("operator") + .newInjectionSetPoint() + .withSetpoint(260) + .withNetworkElement("generator-network-element-id") + .withUnit(Unit.MEGAWATT) + .add() + .newOnInstantUsageRule().withUsageMethod(UsageMethod.AVAILABLE).withInstant(PREVENTIVE_INSTANT).add() + .newOnContingencyStateUsageRule().withUsageMethod(UsageMethod.AVAILABLE).withContingency("contingency-id").withInstant(Instant.CURATIVE).add() + .add(); + +// injection set-point on a shunt compensator + crac.newNetworkAction() + .withId("injection-setpoint-shunt-compensator-id") + .withOperator("operator") + .newInjectionSetPoint() + .withSetpoint(3) + .withNetworkElement("shunt-compensator-id") + .withUnit(Unit.SECTION_COUNT) + .add() + .newOnInstantUsageRule().withUsageMethod(UsageMethod.AVAILABLE).withInstant(PREVENTIVE_INSTANT).add() + .add(); + +// switch pair +crac.newNetworkAction() + .withId("switch-pair-na-id") + .withOperator("operator") + .newSwitchPair() + .withSwitchToOpen("switch-to-open-id", "switch-to-open-name") + .withSwitchToClose("switch-to-close-id-and-name") + .add() + .newOnInstantUsageRule().withUsageMethod(UsageMethod.AVAILABLE).withInstant(PREVENTIVE_INSTANT).add() + .add(); +~~~ +::: +:::{group-tab} JSON file +~~~json + "networkActions" : [ { + "id" : "topological-na-id", + "name" : "topological-na-name", + "operator" : "operator", + "freeToUseUsageRules" : [ { + "instant" : "preventive", + "usageMethod" : "available" + } ], + "topologicalActions" : [ { + "networkElementId" : "network-element-id-1", + "actionType" : "close" + }, { + "networkElementId" : "network-element-id-2", + "actionType" : "open" + } ] + }, { + "id" : "pst-setpoint-na-id", + "name" : "pst-setpoint-na-name", + "operator" : "operator", + "freeToUseUsageRules" : [ { + "instant" : "preventive", + "usageMethod" : "available" + } ], + "pstSetpoints" : [ { + "networkElementId" : "pst-network-element-id", + "setpoint" : 15 + } ] + }, { + "id" : "injection-setpoint-na-id", + "name" : "injection-setpoint-na-id", + "operator" : "operator", + "freeToUseUsageRules" : [ { + "instant" : "preventive", + "usageMethod" : "available" + } ], + "onStateUsageRules" : [ { + "instant" : "curative", + "contingencyId" : "contingency-id", + "usageMethod" : "available" + } ], + "injectionSetpoints" : [ { + "networkElementId" : "generator-network-element-id", + "setpoint" : 260.0, + "unit" : "megawatt" + } ] + }, { + "id" : "switch-pair-na-id", + "name" : "switch-pair-na-id", + "operator" : "operator", + "freeToUseUsageRules" : [ { + "instant" : "preventive", + "usageMethod" : "available" + } ], + "switchPairs" : [ { + "open" : "switch-to-open-id", + "close" : "switch-to-close-id" + } ] + } ] +~~~ +::: +:::{group-tab} Object fields +πŸ”΄β­ **identifier** +βšͺ **name** +βšͺ **operator** +βšͺ **freeToUse usage rules**: list of 0 to N FreeToUse usage rules (see previous paragraph on [usage rules](#remedial-actions-and-usages-rules)) +βšͺ **onState usage rules**: list of 0 to N OnState usage rules (see previous paragraph on [usage rules](#remedial-actions-and-usages-rules)) +βšͺ **onFlowConstraintInCountry usage rules**: list of 0 to N OnFlowConstraintInCountry usage rules (see previous paragraph on [usage rules](#remedial-actions-and-usages-rules)) +βšͺ **onFlowConstraint usage rules**: list of 0 to N OnFlowConstraint usage rules (see previous paragraph on [usage rules](#remedial-actions-and-usages-rules)) +βšͺ **onAngleConstraint usage rules**: list of 0 to N OnAngleConstraint usage rules (see previous paragraph on [usage rules](#remedial-actions-and-usages-rules)) +πŸ”΅ **topological actions**: list of 0 to N TopologicalAction +       πŸ”΄ **network element**: id is mandatory, name is optional +       πŸ”΄ **action type** +πŸ”΅ **pst set points**: list of 0 to N PstSetPoint +       πŸ”΄ **network element**: id is mandatory, name is optional +       πŸ”΄ **setpoint**: integer, new tap of the PST +πŸ”΅ **injection set points**: list of 0 to N InjectionSetPoint +       πŸ”΄ **network element**: id is mandatory, name is optional +       πŸ”΄ **setpoint**: double, new value of the injection +       πŸ”΄ **unit**: Unit, unit of the InjectionSetPoint (MEGAWATT for generators, loads and dangling lines, or SECTION_COUNT for linear shunt compensators) +πŸ”΅ **switch pairs**: list of 0 to N SwitchPair +       πŸ”΄ **switch to open (network element)**: id is mandatory, name is optional +       πŸ”΄ **switch to close (network element)**: id is mandatory, name is optional, must be different from switch to open +
+*NB*: A Network Action must contain at least on elementary action. +::: +:::: + +## Range Actions +A FARAO "Range Action" is a remedial action with a continuous or discrete set-point. If the range action is inactive, its +set-point is equal to its value in the initial network. If it is activated, its set-point is optimized by the RAO to +improve the objective function. +FARAO has four types of range actions : PST range actions, HVDC range actions, "injection" range actions and counter- +trading range actions. + +### PST Range Action +A PstRangeAction contains a network element which must point to a [PST in the iidm PowSyBl network model](https://www.powsybl.org/pages/documentation/grid/model/#phase-tap-changer). +The PstRangeAction will be able to modify the set-point of this PST. + +> πŸ’‘ **NOTE** +> - the set-point of the PstRangeAction is the angle of the PST, measured in degrees +> - all the methods of the PST which mention a set-point implicitly use angle values +> - however, they often have an equivalent that uses integer tap positions + +The domain in which the PstRangeAction can modify the tap of the PST is delimited by 'TapRanges'. A PstRangeAction contains a list (which can be empty) of TapRanges. + +TapRanges can be of different types: +- **absolute**: the mix/max admissible tap of the PST, given in the convention of the PowSyBl network model +- **relative to initial network**: the maximum variation of the tap of the PST relatively to its initial tap +- **relative to previous instant**: the maximum variation of the tap of the PST relatively to its tap in the previous instant. Note that this type of range does not make sense for PstRangeActions which are only available in the preventive instant, as there is no instant before the preventive one. + +The final validity range of the PstRangeAction is the intersection of its TapRanges, with the intersection of the min/max feasible taps of the PST. +The PstRangeAction also requires additional data, notably to be able to interpret the TapRanges. Those additional data are: the initial tap of the PST, and a conversion map which gives for each feasible tap of the PST its corresponding angle. Utility methods have been developed in FARAO to ease the management of these additional data during the creation of a PstRangeAction. + +Two or more [aligned PST range actions](introduction.md#range-action) must have the same (random) group ID defined. The RAO will +make sure their optimized set-points are always equal. + +If the PstRangeAction is an automaton, it has to have a speed assigned. This is an integer that defines the relative +speed of this range action compared to other range-action automatons (smaller "speed" value = faster range action). +No two range-action automatons can have the same speed value, unless they are aligned. + +::::{tabs} +:::{group-tab} JAVA creation API +~~~java +crac.newPstRangeAction() + .withId("pst-range-action-1-id") + .withName("pst-range-action-1-name") + .withOperator("operator") + .withNetworkElement("pst-network-element-id") + .withGroupId("pst-range-action-1 is aligned with pst-range-action-2") + .withInitialTap(3) + .withTapToAngleConversionMap(Map.of(-3, 0., -2, .5, -1, 1., 0, 1.5, 1, 2., 2, 2.5, 3, 3.)) + .newTapRange() + .withRangeType(RangeType.ABSOLUTE) + .withMinTap(0) + .withMaxTap(3) + .add() + .newTapRange() + .withRangeType(RangeType.RELATIVE_TO_INITIAL_NETWORK) + .withMinTap(-2) + .withMaxTap(2) + .add() + .newOnInstantUsageRule().withUsageMethod(UsageMethod.AVAILABLE).withInstant(Instant.PREVENTIVE).add() + .withSpeed(1) + .add(); +~~~ +In that case, the validity domain of the PST (intersection of its ranges and feasible taps) is [1; 3] +Note that the [PstHelper utility class](https://github.com/powsybl/powsybl-open-rao/blob/main/data/crac-creation/crac-creation-util/src/main/java/com/powsybl/openrao/data/craccreation/util/PstHelper.java) can ease the creation of the TapToAngleConversionMap. +::: +:::{group-tab} JSON file +~~~json +"pstRangeActions" : [ { + "id" : "pst-range-action-1-id", + "name" : "pst-range-action-1-name", + "operator" : "operator", + "onInstantUsageRules" : [ { + "instant" : "preventive", + "usageMethod" : "available" + } ], + "networkElementId" : "pst-network-element-id", + "groupId" : "pst-range-action-1 is aligned with pst-range-action-2", + "initialTap" : 2, + "tapToAngleConversionMap" : { + "-3" : 0.0, + "-2" : 0.5, + "-1" : 1.0, + "0" : 1.5, + "1" : 2.0, + "2" : 2.5, + "3" : 3.0 + }, + "speed" : 1, + "ranges" : [ { + "min" : 0, + "max" : 3, + "rangeType" : "absolute" + }, { + "min" : -2, + "max" : 2, + "rangeType" : "relativeToInitialNetwork" + } ] +} ] +~~~ +::: +:::{group-tab} Object fields +πŸ”΄β­ **identifier** +βšͺ **name** +βšͺ **operator** +πŸ”΄ **network element**: id is mandatory, name is optional +βšͺ **groupId**: if you want to align this range action with others, set the same groupId for all. You can use any +group ID you like, as long as you use the same for all the range actions you want to align. +πŸ”΅ **speed**: mandatory if it is an automaton +πŸ”΄ **initial tap** +πŸ”΄ **tap to angle conversion map** +πŸ”΄ **tap ranges**: list of 0 to N TapRange +       πŸ”΄ **range type** +       πŸ”΅ **min tap** +       πŸ”΅ **max tap**: at least one value must be defined +βšͺ **onInstant usage rules**: list of 0 to N OnInstant usage rules (see paragraph on [usage rules](#remedial-actions-and-usages-rules)) +βšͺ **onState usage rules**: list of 0 to N OnContingencyState usage rules (see paragraph on [usage rules](#remedial-actions-and-usages-rules)) +βšͺ **onFlowConstraintInCountry usage rules**: list of 0 to N OnFlowConstraintInCountry usage rules (see previous paragraph on [usage rules](#remedial-actions-and-usages-rules)) +βšͺ **onFlowConstraint usage rules**: list of 0 to N OnFlowConstraint usage rules (see previous paragraph on [usage rules](#remedial-actions-and-usages-rules)) +βšͺ **onAngleConstraint usage rules**: list of 0 to N OnAngleConstraint usage rules (see previous paragraph on [usage rules](#remedial-actions-and-usages-rules)) +::: +:::: + +### HVDC Range Action +An HvdcRangeAction contains a network element that must point towards an [HvdcLine of the iidm PowSyBl network model](https://www.powsybl.org/pages/documentation/grid/model/#hvdc-line). +The HvdcRangeAction will be able to modify its active power set-point. + +The domain in which the HvdcRangeAction can modify the HvdcSetpoint is delimited by 'HvdcRanges'. +An HvdcRangeAction contains a list of HvdcRanges. A range must be defined with a min and a max. + +Two or more [aligned HVDC range actions](introduction.md#range-action) must have the same (random) group ID defined. The RAO will +make sure their optimized set-points are always equal. + +If the HvdcRangeAction is an automaton, it has to have a speed assigned. This is an integer that defines the relative +speed of this range action compared to other range-action automatons (smaller "speed" value = faster range action). +No two range-action automatons can have the same speed value, unless they are aligned. + +::::{tabs} +:::{group-tab} JAVA creation API +~~~java + crac.newHvdcRangeAction() + .withId("hvdc-range-action-id") + .withName("hvdc-range-action-name") + .withOperator("operator") + .withNetworkElement("hvec-id") + .newHvdcRange().withMin(-5).withMax(10).add() + .newOnInstantUsageRule().withInstant(Instant.PREVENTIVE).withUsageMethod(UsageMethod.AVAILABLE).add() + .add(); +~~~ +In that case, the validity domain of the HVDC is [-5; 10]. +::: +:::{group-tab} JSON file +~~~json +"hvdcRangeActions" : [ { + "id" : "hvdc-range-action-id", + "name" : "hvdc-range-action-name", + "operator" : "operator", + "freeToUseUsageRules" : [ { + "instant" : "preventive", + "usageMethod" : "available" + } ], + "networkElementId" : "hvdc-id", + "ranges" : [ { + "min" : -5.0, + "max" : 10.0 + } ] +} ] +~~~ +::: +:::{group-tab} Object fields +πŸ”΄β­ **identifier** +βšͺ **name** +βšͺ **operator** +πŸ”΄ **network element**: id is mandatory, name is optional +βšͺ **groupId**: if you want to align this range action with others, set the same groupId for all +πŸ”΅ **speed**: mandatory if it is an automaton +βšͺ **hvdc ranges**: list of 0 to N HvdcRange +       πŸ”΄ **min** +       πŸ”΄ **max** +βšͺ **onInstant usage rules**: list of 0 to N OnInstant usage rules (see paragraph on [usage rules](#remedial-actions-and-usages-rules)) +βšͺ **onContingencyState usage rules**: list of 0 to N OnContingencyState usage rules (see paragraph on [usage rules](#remedial-actions-and-usages-rules)) +βšͺ **onFlowConstraint usage rules**:Β list of 0 to N OnFlowConstraint usage rules (see paragraph on [usage rules](#remedial-actions-and-usages-rules)) +::: +:::: + +### Injection Range Action + +An InjectionRangeAction modifies given generators' & loads' injection set-points inside a given range. +Each impacted generator or load has an associated "key", which is a coefficient of impact that is applied on its set-point. + +This range action is mainly used to represent an HVDC line in an AC equivalent model (where the line is disconnected and +replaced by two injections, one on each side of the line, with opposite keys of 1 and -1). + +![HVDC AC model](/_static/img/HVDC_AC_model.png) + +Two or more [aligned injection range actions](introduction.md#range-action) must have the same (random) group ID defined. The RAO will +make sure their optimized set-points are always equal. + +If the InjectionRangeAction is an automaton, it has to have a speed assigned. This is an integer that defines the relative +speed of this range action compared to other range-action automatons (smaller "speed" value = faster range action). +No two range-action automatons can have the same speed value, unless they are aligned. +::::{tabs} +:::{group-tab} JAVA creation API +~~~java + crac.newInjectionRangeAction() + .withId("injection-range-action-id") + .withName("injection-range-action-name") + .withOperator("operator") + .withNetworkElementAndKey(1, "network-element-1") + .withNetworkElementAndKey(-0.5, "network-element-2") + .newRange().withMin(-1200).withMax(500).add() + .newOnInstantUsageRule().withInstant(Instant.PREVENTIVE).withUsageMethod(UsageMethod.AVAILABLE).add() + .add(); +~~~ +In that case, the validity domain of the injection range action's reference set-point is [-1200; 500]. +This means the set-point of "network-element-1" (key = 1) can be changed between -1200 and +500, while that of "network-element-2" (key = -0.5) will be changed between -250 and +600 +::: +:::{group-tab} JSON file +~~~json +"injectionRangeActions" : [ { + "id" : "injection-range-action-id", + "name" : "injection-range-action-name", + "operator" : "operator", + "onInstantUsageRules" : [ { + "instant" : "preventive", + "usageMethod" : "available" + } ], + "networkElementIdsAndKeys" : { + "network-element-1" : 1.0, + "network-element-2" : -0.5 + }, + "ranges" : [ { + "min" : -1200.0, + "max" : 500.0 + } ] +} ] +~~~ +::: +:::{group-tab} Object fields +πŸ”΄β­ **identifier** +βšͺ **name** +βšͺ **operator** +πŸ”΄ **network element and key** (list of 1 to N): id and key are mandatory, name is optional +βšͺ **groupId**: if you want to align this range action with others, set the same groupId for all +πŸ”΅ **speed**: mandatory if it is an automaton +πŸ”΄ **ranges**: list of 1 to N Range +       πŸ”΄ **min** +       πŸ”΄ **max** +βšͺ **onInstant usage rules**: list of 0 to N OnInstant usage rules (see paragraph on usage rules) +βšͺ **onContingencyState usage rules**: list of 0 to N OnContingencyState usage rules (see paragraph on usage rules) +βšͺ **onFlowConstraint usage rules**:Β list of 0 to N OnFlowConstraint usage rules (see paragraph on usage rules) +::: +:::: + +### Counter-Trade Range Action + +A CounterTradeRangeAction is an exchange between two countries. The exporting country send power to the importing +country. + +It is a costly remedial action which is currently not handled by the RAO. + +::::{tabs} +:::{group-tab} JAVA creation API +~~~java + crac.newCounterTradeRangeAction() + .withId("counter-trade-range-action-id") + .withGroupId("group-id") + .withOperator("operator") + .withExportingCountry(Country.FR) + .withImportingCountry(Country.ES) + .newRange().withMin(0).withMax(1000).add() + .newOnInstantUsageRule().withInstant("preventive").withUsageMethod(UsageMethod.AVAILABLE).add() + .add(); +~~~ +In that case, the validity domain of the counter-trade range action's reference set-point is [0; 1000]. The power is +exported from France to Spain. +::: +:::{group-tab} JSON file +~~~json +"counterTradeRangeActions" : [ { + "id" : "counter-trade-range-action-id", + "name" : "counterTradeRange1Name", + "operator" : null, + "speed" : 30, + "onInstantUsageRules" : [ { + "instant" : "preventive", + "usageMethod" : "available" + } ], + "exportingCountry" : "FR", + "importingCountry" : "ES", + "initialSetpoint" : 50, + "ranges" : [ { + "min" : 0.0, + "max" : 1000.0 + }, { + "min" : -1000.0, + "max" : 1000.0 + } ] +} ] +~~~ +::: +:::{group-tab} Object fields +πŸ”΄β­ **identifier** +βšͺ **name** +βšͺ **operator** +πŸ”΄ **exporting country** +πŸ”΄ **importing country** +βšͺ **groupId**: if you want to align this range action with others, set the same groupId for all +πŸ”΅ **speed**: mandatory if it is an automaton +βšͺ **ranges**: list of 0 to N Range +       πŸ”΄ **min** +       πŸ”΄ **max** +βšͺ **onInstant usage rules**: list of 0 to N OnInstant usage rules (see paragraph on usage rules) +βšͺ **onContingencyState usage rules**: list of 0 to N OnContingencyState usage rules (see paragraph on usage rules) +βšͺ **onFlowConstraint usage rules**: list of 0 to N OnFlowConstraint usage rules (see paragraph on usage rules) +βšͺ **onAngleConstraint usage rules**: list of 0 to N OnAngleConstraint usage rules (see paragraph on usage rules) +βšͺ **onVoltageConstraint usage rules**: list of 0 to N OnVoltageConstraint usage rules (see paragraph on usage rules) +::: +:::: + +## RAs usage limitations +A FARAO "ra-usage-limits-per-instant" consists in limits on the usage of remedial actions for given instants. +The given instant IDs should match an ID of an instant in the CRAC. Otherwise, its limits will be ignored. +See [here](creation-parameters.md#ra-usage-limits-per-instant) for further explanation on each field described in the following example. + +::::{tabs} +:::{group-tab} JAVA creation API +~~~java +crac.newRaUsageLimits("preventive") + .withMaxRa(44) + .withMaxTso(12) + .withMaxRaPerTso(new HashMap<>(Map.of("FR", 41, "BE", 12))) + .withMaxPstPerTso(new HashMap<>(Map.of("BE", 7))) + .withMaxTopoPerTso(new HashMap<>(Map.of("DE", 5))) + .add(); +crac.newRaUsageLimits("curative") + .withMaxRa(3) + .add(); +~~~ +::: +:::{group-tab} JSON file +~~~json +"ra-usage-limits-per-instant" : [ { + "instant": "preventive", + "max-ra" : 44, + "max-tso" : 12, + "max-ra-per-tso" : {"FR": 41, "BE": 12}, + "max-topo-per-tso" : {"DE": 5}, + "max-pst-per-tso" : {"BE": 7} +}, { + "instant": "curative", + "max-ra" : 3 +} ] +~~~ +::: +:::: + diff --git a/docs/input-data/index.rst b/docs/input-data/index.rst new file mode 100644 index 0000000000..3af6f0d363 --- /dev/null +++ b/docs/input-data/index.rst @@ -0,0 +1,9 @@ +Input data +========== + +Reference documentation for Open RAO's input data + +.. toctree:: + :maxdepth: 2 + + crac/index diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000000..922152e96a --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000000..ecd905fb8a --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +sphinx==5.0.2 +sphinx-tabs +pydata-sphinx-theme==0.10.1 +myst-parser \ No newline at end of file