From 48c0319d8b5b5b6116ee87d1acf9f826e00b739e Mon Sep 17 00:00:00 2001 From: bc-rte <142609826+bc-rte@users.noreply.github.com> Date: Tue, 3 Sep 2024 17:18:06 +0200 Subject: [PATCH 1/7] Add Overload Management System documentation (#3110) Signed-off-by: CHIQUET Benoit Co-authored-by: Anne Tilloy --- docs/grid_model/network_subnetwork.md | 49 ++++++++++++++++++++++----- 1 file changed, 41 insertions(+), 8 deletions(-) diff --git a/docs/grid_model/network_subnetwork.md b/docs/grid_model/network_subnetwork.md index 44ae4455340..876dc5ec418 100644 --- a/docs/grid_model/network_subnetwork.md +++ b/docs/grid_model/network_subnetwork.md @@ -807,10 +807,12 @@ A busbar section is a non impedant element used in a node/breaker substation top ## Breaker/switch [![Javadoc](https://img.shields.io/badge/-javadoc-blue.svg)](https://javadoc.io/doc/com.powsybl/powsybl-core/latest/com/powsybl/iidm/network/Switch.html)
+A switch is a device designed to close or open one or more electric circuits. There are several types of switches: +- breakers are capable of breaking currents under abnormal operating conditions (e.g. short-circuit); +- load break switches are capable of breaking currents under normal operating conditions; +- and disconnectors can only make or break negligible current. - +A switch has an attribute to say if it is open or closed. **Available extensions** @@ -819,9 +821,40 @@ A busbar section is a non impedant element used in a node/breaker substation top (internal-connection)= ## Internal connection -**Internal connection** -An internal connection is a non-impedant connection between two components in a voltage level. +[![Javadoc](https://img.shields.io/badge/-javadoc-blue.svg)](https://javadoc.io/doc/com.powsybl/powsybl-core/latest/com/powsybl/iidm/network/VoltageLevel.NodeBreakerView.InternalConnection.html)
+An internal connection is a zero-impedance connection between two elements in a voltage level. - \ No newline at end of file +Contrary to the switch, the internal connection does not have any attribute to say of it is open or closed. + +(overload-management-system)= +## Overload management systems + +[![Javadoc](https://img.shields.io/badge/-javadoc-blue.svg)](https://javadoc.io/doc/com.powsybl/powsybl-core/latest/com/powsybl/iidm/network/OverloadManagementSystem.html)
+An overload management system is an automation system that monitors current on a terminal, defined by an equipment and an optional side. +Based on the measured values, various strategies (referred as 'trippings' in the model) can be implemented to reduce the current. +In a given strategy, if the current exceeds a threshold, a switch can be opened or closed to resolve the violation. + +The switch open or close operation could be modeled using a switch ID, an association of a branch ID and a side, +or an association of a three-windings transformer ID and a side. + +**Overload management system Characteristics** + +| Attribute | Unit | Description | +| --------- | ---- |---------------------------------------------------------| +| $Substation$ | | The substation associated where the system is installed | +| $MonitoredElementId$ | | The network element on which the limit will be monitored | +| $MonitoredSide$ | | The side of the element that is monitored | + +**Tripping Characteristics** + +The supported trippings are: +- Branch tripping, +- Switch tripping, +- and three-windings transformer tripping. + +| Attribute | Unit | Description | +| --------- | ---- | ----------- | +| $Type$ | | The type of tripping (e.g. BranchTripping, SwitchTripping, ...) | +| $CurrentLimit$ | A | The current limit for which the action will be triggered | +| $Key$ | | The tripping key | +| $OpenAction$ | bool | Whether the tripping should be opened or closed | From e0287a9614491d6746f47e6bc34a94e1ddabe680 Mon Sep 17 00:00:00 2001 From: Jon Harper Date: Fri, 6 Sep 2024 17:55:47 +0200 Subject: [PATCH 2/7] CompletableFutureTask, fix spurious error logging when cancelling (#3135) When calling cancel(true), the CompletableFutureTask was throwing a NullPointerException in its run method because cancel(true) causes future.get() to throw a CancellationException without a cause (null) and completeExceptionally requires a non null Exception the exception was thrown to the executor and the very end. Executors usually catch and ignore everything (just logs to stdout) so the problem was just ugly logs and a slight performance drop. This was a regression from 5bef72fa5ee, the actual code is reverted to the previous version (except changing throwable to exception to please avoid sonar warnings I guess) The code change was not logical, we need to unwrap the cause when we have an ExecutionException and we also need to not unwrap the cause otherwise. Signed-off-by: HARPER Jon --- .../computation/CompletableFutureTask.java | 4 ++- .../CompletableFutureTaskTest.java | 33 +++++++++++++++++++ 2 files changed, 36 insertions(+), 1 deletion(-) diff --git a/computation/src/main/java/com/powsybl/computation/CompletableFutureTask.java b/computation/src/main/java/com/powsybl/computation/CompletableFutureTask.java index 806edd34f79..17530b5b420 100644 --- a/computation/src/main/java/com/powsybl/computation/CompletableFutureTask.java +++ b/computation/src/main/java/com/powsybl/computation/CompletableFutureTask.java @@ -45,11 +45,13 @@ public void run() { future.run(); try { complete(future.get()); + } catch (ExecutionException exc) { + completeExceptionally(exc.getCause()); } catch (InterruptedException exc) { Thread.currentThread().interrupt(); completeExceptionally(exc); } catch (Exception exc) { - completeExceptionally(exc.getCause()); + completeExceptionally(exc); } } diff --git a/computation/src/test/java/com/powsybl/computation/CompletableFutureTaskTest.java b/computation/src/test/java/com/powsybl/computation/CompletableFutureTaskTest.java index a97d6e69dd4..3e2c191ea40 100644 --- a/computation/src/test/java/com/powsybl/computation/CompletableFutureTaskTest.java +++ b/computation/src/test/java/com/powsybl/computation/CompletableFutureTaskTest.java @@ -40,10 +40,39 @@ private static List executors() { Executors.newSingleThreadExecutor(), Executors.newCachedThreadPool(), Executors.newWorkStealingPool(), + new MyTestExecutorWithException(), ForkJoinPool.commonPool() ); } + // Very basic executor that spawns a new thread + // and allows to wait for the end of the command. + // It just keeps an exception to be able to assert it. + // You should use it to launch only one command + // because it has just one latch and one exception + private static class MyTestExecutorWithException implements Executor { + + Exception exception = null; + CountDownLatch waitForDone; + + @Override + public void execute(Runnable command) { + (new Thread() { + @Override + public void run() { + waitForDone = new CountDownLatch(1); + try { + command.run(); + } catch (Exception e) { + MyTestExecutorWithException.this.exception = e; + } finally { + waitForDone.countDown(); + } + } + }).start(); + } + } + @ParameterizedTest @MethodSource("parameters") void whenSupplyObjectThenReturnIt(Executor executor) throws Exception { @@ -125,6 +154,10 @@ private void testEffectiveInterrupt(boolean addDependant, Executor executor) thr //Second call to cancel should return false cancelled = task.cancel(true); assertFalse(cancelled); + if (executor instanceof MyTestExecutorWithException myTestExecutor) { + myTestExecutor.waitForDone.await(); + assertNull(myTestExecutor.exception); + } } @ParameterizedTest From 37c801485833b1b2c6d17949d034e0d9978591b9 Mon Sep 17 00:00:00 2001 From: Nicolas Rol Date: Mon, 9 Sep 2024 11:48:10 +0200 Subject: [PATCH 3/7] Create directory for resources in TestPlatformConfigProvider (#3136) Signed-off-by: Nicolas Rol --- .../config/test/TestPlatformConfigProvider.java | 1 + .../config/test/TestPlatformConfigProviderTest.java | 11 ++++++++--- .../resources/com/powsybl/config/test/filelist.txt | 1 + .../powsybl/config/test/subfolder/subfolder_file.txt | 1 + 4 files changed, 11 insertions(+), 3 deletions(-) create mode 100644 config-test/src/test/resources/com/powsybl/config/test/subfolder/subfolder_file.txt diff --git a/config-test/src/main/java/com/powsybl/config/test/TestPlatformConfigProvider.java b/config-test/src/main/java/com/powsybl/config/test/TestPlatformConfigProvider.java index 91e9f860a0c..08abd246cf1 100644 --- a/config-test/src/main/java/com/powsybl/config/test/TestPlatformConfigProvider.java +++ b/config-test/src/main/java/com/powsybl/config/test/TestPlatformConfigProvider.java @@ -74,6 +74,7 @@ public PlatformConfig getPlatformConfig() { // The resources have relative paths (no leading slash) with full package path. Path dest = cfgDir.resolve(resource); LOGGER.info("Copying classpath resource: {} -> {}", resource, dest); + Files.createDirectories(dest.getParent()); Files.copy(TestPlatformConfigProvider.class.getResourceAsStream(resource), dest); } } catch (IOException e) { diff --git a/config-test/src/test/java/com/powsybl/config/test/TestPlatformConfigProviderTest.java b/config-test/src/test/java/com/powsybl/config/test/TestPlatformConfigProviderTest.java index 3b28bbed509..3545bd0ada0 100644 --- a/config-test/src/test/java/com/powsybl/config/test/TestPlatformConfigProviderTest.java +++ b/config-test/src/test/java/com/powsybl/config/test/TestPlatformConfigProviderTest.java @@ -30,11 +30,16 @@ void test() throws IOException { assertEquals("/work/" + TestPlatformConfigProvider.CONFIG_DIR, platformConfig.getConfigDir().map(Path::toString).orElse(null)); - Path testPath = platformConfig.getConfigDir().map(p -> p.resolve("other.txt")).orElse(null); + checkFileContent(platformConfig, "other.txt", "conf"); + checkFileContent(platformConfig, "subfolder/subfolder_file.txt", "subfile content"); + assertEquals("baz", platformConfig.getOptionalModuleConfig("foo").flatMap(c -> c.getOptionalStringProperty("bar")).orElse("")); + } + + private void checkFileContent(PlatformConfig platformConfig, String file, String content) throws IOException { + Path testPath = platformConfig.getConfigDir().map(p -> p.resolve(file)).orElse(null); assertNotNull(testPath); String testContent = Files.readAllLines(testPath, StandardCharsets.UTF_8).get(0); - assertEquals("conf", testContent); - assertEquals("baz", platformConfig.getOptionalModuleConfig("foo").flatMap(c -> c.getOptionalStringProperty("bar")).orElse("")); + assertEquals(content, testContent); } @Test diff --git a/config-test/src/test/resources/com/powsybl/config/test/filelist.txt b/config-test/src/test/resources/com/powsybl/config/test/filelist.txt index 8c98f97de36..4e6ac675e5d 100644 --- a/config-test/src/test/resources/com/powsybl/config/test/filelist.txt +++ b/config-test/src/test/resources/com/powsybl/config/test/filelist.txt @@ -1,3 +1,4 @@ config.yml other.txt base-voltages.yml +subfolder/subfolder_file.txt diff --git a/config-test/src/test/resources/com/powsybl/config/test/subfolder/subfolder_file.txt b/config-test/src/test/resources/com/powsybl/config/test/subfolder/subfolder_file.txt new file mode 100644 index 00000000000..7b98f0ca009 --- /dev/null +++ b/config-test/src/test/resources/com/powsybl/config/test/subfolder/subfolder_file.txt @@ -0,0 +1 @@ +subfile content \ No newline at end of file From 89894c4da71ce59e4b1ee078bc81e37376061f92 Mon Sep 17 00:00:00 2001 From: FranckLecuyer <47824306+FranckLecuyer@users.noreply.github.com> Date: Mon, 9 Sep 2024 16:32:12 +0200 Subject: [PATCH 4/7] Distinguish between line and 2 windings transformer in TerminalFinder default rules (#3117) Signed-off-by: Franck LECUYER --- .../java/com/powsybl/iidm/network/util/TerminalFinder.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/iidm/iidm-api/src/main/java/com/powsybl/iidm/network/util/TerminalFinder.java b/iidm/iidm-api/src/main/java/com/powsybl/iidm/network/util/TerminalFinder.java index 49bb1afa601..837b40102d8 100644 --- a/iidm/iidm-api/src/main/java/com/powsybl/iidm/network/util/TerminalFinder.java +++ b/iidm/iidm-api/src/main/java/com/powsybl/iidm/network/util/TerminalFinder.java @@ -86,7 +86,8 @@ private static List> getDefaultRules() { List> rules = new ArrayList<>(); rules.add(t -> t.getConnectable() instanceof BusbarSection); rules.add(t -> t.getConnectable() instanceof Injection); - rules.add(t -> t.getConnectable() instanceof Branch); + rules.add(t -> t.getConnectable() instanceof Line); + rules.add(t -> t.getConnectable() instanceof TwoWindingsTransformer); rules.add(t -> t.getConnectable() instanceof ThreeWindingsTransformer); rules.add(t -> t.getConnectable() instanceof HvdcConverterStation); rules.add(Objects::nonNull); From 9f6c550f3092cbd3bdc35be05c14a2d98e48fda6 Mon Sep 17 00:00:00 2001 From: Coline Piloquet <55250145+colinepiloquet@users.noreply.github.com> Date: Wed, 11 Sep 2024 10:09:19 +0200 Subject: [PATCH 5/7] Documentation wording corrections (#3124) Signed-off-by: Coline PILOQUET --- docs/README.md | 8 +- docs/data/timeseries.md | 6 +- docs/grid_exchange_formats/ampl/index.md | 2 +- docs/grid_exchange_formats/cgmes/export.md | 38 +- docs/grid_exchange_formats/cgmes/import.md | 54 +-- docs/grid_exchange_formats/cgmes/index.md | 6 +- docs/grid_exchange_formats/iidm/export.md | 6 +- docs/grid_exchange_formats/iidm/import.md | 4 +- docs/grid_exchange_formats/iidm/index.md | 2 +- docs/grid_exchange_formats/index.md | 2 +- docs/grid_exchange_formats/matpower/import.md | 4 +- docs/grid_exchange_formats/psse/import.md | 46 +-- docs/grid_exchange_formats/psse/index.md | 4 +- docs/grid_exchange_formats/ucte/export.md | 2 +- .../ucte/format_specification.md | 14 +- docs/grid_exchange_formats/ucte/import.md | 46 +-- docs/grid_exchange_formats/ucte/index.md | 4 +- docs/grid_features/extraction.md | 18 +- docs/grid_features/import_post_processor.md | 6 +- docs/grid_features/loadflow_validation.md | 16 +- docs/grid_model/additional.md | 22 +- docs/grid_model/extensions.md | 70 ++-- docs/grid_model/index.md | 2 +- docs/grid_model/network_subnetwork.md | 338 +++++++++--------- docs/index.md | 2 +- docs/simulation/dynamic/configuration.md | 2 +- docs/simulation/dynamic/index.md | 4 +- .../dynamic_security/configuration.md | 4 +- docs/simulation/dynamic_security/index.md | 6 +- docs/simulation/loadflow/configuration.md | 10 +- docs/simulation/loadflow/index.md | 6 +- docs/simulation/security/action-dsl.md | 30 +- docs/simulation/security/configuration.md | 10 +- docs/simulation/security/contingency-dsl.md | 12 +- docs/simulation/security/index.md | 12 +- docs/simulation/security/limit-reductions.md | 6 +- docs/simulation/sensitivity/configuration.md | 8 +- docs/simulation/sensitivity/index.md | 24 +- docs/simulation/shortcircuit/index.md | 2 +- docs/simulation/shortcircuit/inputs.md | 4 +- docs/simulation/shortcircuit/outputs.md | 2 +- docs/simulation/shortcircuit/parameters.md | 4 +- .../configuration/componentDefaultConfig.md | 2 +- .../import-export-parameters-default-value.md | 2 +- docs/user/configuration/index.md | 20 +- .../limit-violation-default-filter.md | 2 +- .../load-flow-action-simulator.md | 4 +- .../user/configuration/loadflow-validation.md | 4 +- docs/user/configuration/security-analysis.md | 4 +- docs/user/itools/action-simulator.md | 10 +- .../compare-security-analysis-results.md | 8 +- docs/user/itools/dynamic-security-analysis.md | 8 +- docs/user/itools/dynamic-simulation.md | 4 +- docs/user/itools/index.md | 6 +- docs/user/itools/loadflow-validation.md | 68 ++-- docs/user/itools/loadflow.md | 4 +- docs/user/itools/run-script.md | 2 +- docs/user/itools/security-analysis.md | 12 +- 58 files changed, 514 insertions(+), 514 deletions(-) diff --git a/docs/README.md b/docs/README.md index 1b0c2db5991..556c14f0395 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -These are the documentation sources for PowSybl core features. +These are the documentation sources for PowSyBl core features. Please keep them up to date with your developments. They are published on powsybl.readthedocs.io/ and pull requests are built and previewed automatically. @@ -27,8 +27,8 @@ sphinx-build -a . ../build-docs Then open `build-docs/index.html` in your browser. If you want to add links to another documentation, add the corresponding repository to the `conf.py` file. -In order to automatically get the version specified in the `pom.xml`, please use the same naming as the version: if you define the -Groovy version with ``, then use `groovy` as key. The specified URL should start with `https://` and end with `latest/` (the final `/` is mandatory). +To automatically get the version specified in the `pom.xml`, please use the same naming as the version: if you define the +Groovy version with ``, then use `groovy` as a key. The specified URL should start with `https://` and end with `latest/` (the final `/` is mandatory). For example, to add a link to the documentation of Sphinx, you need to add the following lines: ~~~python # This parameter might already be present, just add the new value @@ -38,7 +38,7 @@ intersphinx_mapping = { ~~~ Then in your documentation file, you can add links to PowSyBl-Core documentation. If you want to link to a whole page, -use one of the following example: +use one of the following examples: ~~~Markdown - {doc}`sphinx:usage/extensions/intersphinx` - {doc}`Intersphinx ` diff --git a/docs/data/timeseries.md b/docs/data/timeseries.md index cde68cf179d..206cf5e350e 100644 --- a/docs/data/timeseries.md +++ b/docs/data/timeseries.md @@ -12,7 +12,7 @@ in the framework, depending on the need: - [Irregular index](https://en.wikipedia.org/wiki/Unevenly_spaced_time_series): the time step size varies - Infinite index: the time series contains only two points, one at instant 0 and another at instant `Long.MAX_VALUE` - Metadata: a list of key/value string data -- Data chunks: an ordered list of data that will be associated to instants of the time index. The data chunks may be compressed or uncompressed. +- Data chunks: an ordered list of data that will be associated with instants of the time index. The data chunks may be compressed or uncompressed. An uncompressed JSON data chunk looks like: ```json @@ -24,7 +24,7 @@ An uncompressed JSON data chunk looks like: An uncompressed data chunk is modeled with a double (or String) array and an offset. It defines values associated to instants of the time index from `offset` to `offset + values.length`. -It is possible to compress the data chunks, using for example the [RLE](https://fr.wikipedia.org/wiki/Run-length_encoding). +It is possible to compress the data chunks, using, for example, the [RLE](https://fr.wikipedia.org/wiki/Run-length_encoding). The JSON serialization of compressed data chunks looks like: Output: ```json @@ -114,7 +114,7 @@ Here is the list of supported vector operations: In the Groovy DSL syntax, both `timeSeries['a']` and `ts['a']` are supported and are equivalent. To compare a time index vector to a literal date, the `time('2018-01-01T00:00:01Z')` function is available. For instance, the -following code create a time series of 0 and 1 values: +following code creates a time series of 0 and 1 values: ```groovy a = ts['dts'].time() < time('2018-01-01T00:00:01Z') ``` diff --git a/docs/grid_exchange_formats/ampl/index.md b/docs/grid_exchange_formats/ampl/index.md index 5376030ff21..4dfa82fd1ac 100644 --- a/docs/grid_exchange_formats/ampl/index.md +++ b/docs/grid_exchange_formats/ampl/index.md @@ -9,4 +9,4 @@ example.md The [AMPL](https://ampl.com/) (**A** **M**athematical **P**rogramming **L**anguage) format is an algebraic modeling language to describe and solve high-complexity problems for large-scale mathematical computing (i.e. large-scale optimization and scheduling-type problems). -IIDM networks can be converted in flat text files easy to read in AMPL, each of which describing one type of the network equipments (batteries, generators, loads, branches, buses, etc.). +IIDM networks can be converted in flat text files easy to read in AMPL, each of which describing one type of the network equipment (batteries, generators, loads, branches, buses, etc.). diff --git a/docs/grid_exchange_formats/cgmes/export.md b/docs/grid_exchange_formats/cgmes/export.md index a5ca33a8773..33c52979b80 100644 --- a/docs/grid_exchange_formats/cgmes/export.md +++ b/docs/grid_exchange_formats/cgmes/export.md @@ -1,7 +1,7 @@ # Export There are two main use-cases supported: - * Export IGM (Individual Grid Model) instance files. There is a single network and a unique CGMES modelling authority. + * Export IGM (Individual Grid Model) instance files. There is a single network and a unique CGMES modeling authority. * Export CGM (Common Grid Model) instance files. A network composed of multiple subnetworks, where each subnetwork is an IGM. In both cases, the metadata model information in the exported files is built from metadata information read from the input files and stored in IIDM or received through parameters. @@ -10,7 +10,7 @@ Information received through parameters takes precedence over information availa For a quick CGM export, the user may rely on the parameter **iidm.export.cgmes.cgm_export** to write in a single export multiple updated SSH files (one for each IGM) and a single SV for the whole common grid model. Specifics about this option are explained in the section [below](#cgm-common-grid-model-quick-export). If you need complete control over the exported files in a CGM scenario, you may prefer to iterate through the subnetworks and make multiple calls to the export function. This is described in detail in the section [below](#cgm-common-grid-model-manual-export). -Please note that when exporting equipment, PowSyBl always use the CGMES node/breaker level of detail, without considering the topology +Please note that when exporting equipment, PowSyBl always uses the CGMES node/breaker level of detail, without considering the topology level of the PowSyBl network. The user can specify the profiles to be exported using the parameter **iidm.export.cgmes.profiles**. The list of currently supported export instance files are: EQ, SSH, SV, TP. @@ -47,7 +47,7 @@ The filenames of the exported instance files will follow the pattern: The basename is determined from the parameters, or the basename of the export data source or the main network name. -As an example, you can export one of the test configurations that has been provided by ENTSO-E. It is available in the cgmes-conformity module of the powsybl-core repository. If you run the following code: +As an example, you can export one of the test configurations that have been provided by ENTSO-E. It is available in the cgmes-conformity module of the powsybl-core repository. If you run the following code: ```java Network cgmNetwork = Network.read(CgmesConformity1Catalog.microGridBaseCaseAssembled().dataSource()); @@ -76,7 +76,7 @@ where the updated SSH files will supersede the original ones, and the SV will co If you want to intervene in how the updated IGM SSH files or the CGM SV are exported, you can make multiple calls to the CGMES export function. -You can use following code for reference: +You can use the following code for reference: ```java Network cgmNetwork = Network.read(CgmesConformity1Catalog.microGridBaseCaseAssembled().dataSource()); @@ -145,7 +145,7 @@ And the file `manualExampleBasename_SV.xml` will contain: http://entsoe.eu/CIM/StateVariables/4/1 -myModellinAuthority +myModelingAuthority ... ``` @@ -180,8 +180,8 @@ PowSyBl [`Generator`](../../grid_model/network_subnetwork.md#generator) is expor #### Regulating control -If the network comes from a CIM-CGMES model and a generator has initially a `RegulatingControl`, it always has at export -too. Otherwise, a `RegulatingControl` is always exported for generators, except if it has no regulating capabilities because +If the network comes from a CIM-CGMES model and a generator initially has a `RegulatingControl`, it will still have one at export. +Otherwise, a `RegulatingControl` is always exported for generators, except if it has no regulating capabilities because $minQ = maxQ$. A `RegulatingControl` is exported with `RegulatingControl.mode` set to `RegulatingControlModeKind.reactivePower` when a @@ -213,10 +213,10 @@ PowSyBl [`ShuntCompensator`](../../grid_model/network_subnetwork.md#shunt-compen #### Regulating control -If the network comes from a CIM-CGMES model and a shunt compensator has initially a `RegulatingControl`, it always -has at export too. +If the network comes from a CIM-CGMES model and a shunt compensator initially has a `RegulatingControl`, it will still +have one at export. -A shunt compensator with local voltage control (i.e. the regulating terminal is the same of the terminal of connection) +A shunt compensator with local voltage control (i.e., the regulating terminal is the same of the terminal of connection) and no valid voltage target will not have any exported regulating control. In all other cases, a `RegulatingControl` is exported with `RegulatingControl.mode` set to `RegulatingControlModeKind.voltage`. @@ -226,10 +226,10 @@ PowSyBl [`StaticVarCompensator`](../../grid_model/network_subnetwork.md#static-v #### Regulating control -If the network comes from a CIM-CGMES model and a static VAR compensator has initially a `RegulatingControl`, it always -has at export too. +If the network comes from a CIM-CGMES model and a static VAR compensator initially has a `RegulatingControl`, it will still +have one at export. -A static VAR compensator which voltage control is local (i.e. the regulating terminal is the same of the terminal of +A static VAR compensator which voltage control is local (i.e., the regulating terminal is the same of the terminal of connection) and no valid voltage or reactive power target will not have any exported regulating control. A `RegulatingControl` is exported with `RegulatingControl.mode` set to `RegulatingControlModeKind.reactivePower` when @@ -252,7 +252,7 @@ PowSyBl [`Switch`](../../grid_model/network_subnetwork.md#breakerswitch) is expo ### ThreeWindingsTransformer -PowSyBl [`ThreeWindingsTransformer`](../../grid_model/network_subnetwork.md#three-windings-transformer) is exported as `PowerTransformer` with three `PowerTransformerEnds`. +PowSyBl [`ThreeWindingsTransformer`](../../grid_model/network_subnetwork.md#three-winding-transformer) is exported as `PowerTransformer` with three `PowerTransformerEnds`. #### Tap changer control @@ -272,13 +272,13 @@ when `PhaseTapChanger` `regulationMode` is set to `CURRENT_LIMITER`. ### TwoWindingsTransformer -PowSyBl [`TwoWindingsTransformer`](../../grid_model/network_subnetwork.md#two-windings-transformer) is exported as `PowerTransformer` with two `PowerTransformerEnds`. +PowSyBl [`TwoWindingsTransformer`](../../grid_model/network_subnetwork.md#two-winding-transformer) is exported as `PowerTransformer` with two `PowerTransformerEnds`. -Tap changer controls for two windings transformers are exported following the same rules explained in the previous section about three windings transformers. See [tap changer control](#tap-changer-control). +Tap changer controls for two-winding transformers are exported following the same rules explained in the previous section about three-winding transformers. See [tap changer control](#tap-changer-control). ### Voltage level -PowSybl [`VoltatgeLevel`](../../grid_model/network_subnetwork.md#voltage-level) is exported as `VoltageLevel`. +PowSyBl [`VoltageLevel`](../../grid_model/network_subnetwork.md#voltage-level) is exported as `VoltageLevel`. TODO details @@ -362,7 +362,7 @@ Optional property defining whether the transformers should be exported with the This property is set to `false` by default. **iidm.export.cgmes.export-load-flow-status** -Optional property that indicates whether the loadflow status (`converged` or `diverged`) should be +Optional property that indicates whether the load flow status (`converged` or `diverged`) should be written for the `TopologicalIslands` in the SV file. If `true`, the status will be computed by checking, for every bus, if the voltage and angle are valid, and if the bus is respecting Kirchhoff's first law. For the latter, we check that the sums of active power and reactive power at the bus are higher than a threshold defined by the properties @@ -380,7 +380,7 @@ Optional property to specify if the total mismatch left after power flow calcula This property is set to `true` by default. **iidm.export.cgmes.sourcing-actor** -Optional property allowing to specify a custom sourcing actor. If a Boundary set with reference data is provided for the export through the parameter `iidm.import.cgmes.boundary-location`, the value of this property will be used to look for the modelling authority set and the geographical region to be used in the export. +Optional property allowing to specify a custom sourcing actor. If a Boundary set with reference data is provided for the export through the parameter `iidm.import.cgmes.boundary-location`, the value of this property will be used to look for the modeling authority set and the geographical region to be used in the export. No default value is given. If this property is not given, the export process will still try to determine the sourcing actor from the IIDM network if it only contains one country. diff --git a/docs/grid_exchange_formats/cgmes/import.md b/docs/grid_exchange_formats/cgmes/import.md index 5a3cbaf6669..3ef15fd9534 100644 --- a/docs/grid_exchange_formats/cgmes/import.md +++ b/docs/grid_exchange_formats/cgmes/import.md @@ -5,13 +5,13 @@ The CIM-CGMES importer reads and converts a CIM-CGMES model to the PowSyBl grid - Convert CIM-CGMES data retrieved by SPARQL requests from the created triplestore to PowSyBl grid model The data in input CIM/XML files uses RDF (Resource Description Framework) syntax. In RDF, data is described making statements about resources using triplet expressions: (subject, predicate, object). -To describe the conversion from CGMES to PowSyBl we first introduce some generic considerations about the level of detail of the model (node/breaker or bus/branch), the identity of the equipments and equipment containment in substations and voltage levels. After that, the conversion for every CGMES relevant class is explained. Consistency checks and validations performed during the conversion are mentioned in the corresponding sections. +To describe the conversion from CGMES to PowSyBl, we first introduce some generic considerations about the level of detail of the model (node/breaker or bus/branch), the identity of the equipments and equipment containment in substations and voltage levels. After that, the conversion for every CGMES relevant class is explained. Consistency checks and validations performed during the conversion are mentioned in the corresponding sections. ## Levels of detail: node/breaker and bus/branch CGMES models defined at node/breaker level of detail will be mapped to PowSyBl node/breaker topology level. CGMES models defined at bus/branch level will be mapped to PowSyBl bus/breaker topology level. -For each equipment in the PowSyBl grid model it is necessary to specify how it should be connected to the network. +For each equipment in the PowSyBl grid model, it is necessary to specify how it should be connected to the network. If the model is specified at the bus/breaker level, a `Bus` must be specified for the equipment. @@ -21,7 +21,7 @@ Using the `Node` or `Bus` information, PowSyBl creates a `Terminal` that will be Some equipment, like switches, lines or transformers, have more than one point of connection to the Network. -In PowSyBl, a `Node` can have zero or one terminal. In CGMES, the `ConnectivityNode` objects may have more than one associated terminals. To be able to represent this in PowSyBl, the conversion process will automatically create internal connections between the PowSyBl nodes that represent equipment connections and the nodes created to map `ConnectivityNode` objects. +In PowSyBl, a `Node` can have zero or one terminal. In CGMES, the `ConnectivityNode` objects may have more than one associated terminal. To be able to represent this in PowSyBl, the conversion process will automatically create internal connections between the PowSyBl nodes that represent equipment connections and the nodes created to map `ConnectivityNode` objects. ## Identity of model equipments @@ -31,9 +31,9 @@ Terminals are used by CGMES and PowSyBl to define the points of connection of th ## Equipment containers: substations and voltage levels -The PowSyBl grid model establishes the substation as a required container of voltage levels and transformers (two and three windings transformers and phase shifters). Voltage levels are the required container of the rest network equipments, except for the AC and DC transmission lines that establish connections between substations and are associated directly to the network model. All buses at transformer ends should be kept at the same substation. +The PowSyBl grid model establishes the substation as a required container of voltage levels and transformers (two- and three-winding transformers and phase shifters). Voltage levels are the required container of the rest of the network equipment, except for the AC and DC transmission lines that establish connections between substations and are directly associated with the network model. All buses at the transformer ends should be kept in the same substation. -The CGMES model does not guarantee these hierarchical constraints, so the first step in the conversion process is to identify all the transformers with ends in different substations and all the breakers and switches with ends in different voltage levels. All the voltage levels connected by breakers or switches should be mapped to a single voltage level in the PowSyBl grid model. The first CGMES voltage level, in alphabetical order, will be the representative voltage level associated to the PowSyBl voltage level. The same criterion is used for substations, and the first CGMES substation will be the representative substation associated to the PowSyBl one. The joined voltage levels and substations information is used almost in every step of the mapping between CGMES and PowSyBl models, and it is recorded in the `Context` conversion class, that keeps data throughout the overall conversion process. +The CGMES model does not guarantee these hierarchical constraints, so the first step in the conversion process is to identify all the transformers with ends in different substations and all the breakers and switches with ends in different voltage levels. All the voltage levels connected by breakers or switches should be mapped to a single voltage level in the PowSyBl grid model. The first CGMES voltage level, in alphabetical order, will be the representative voltage level associated with the PowSyBl voltage level. The same criterion is used for substations, and the first CGMES substation will be the representative substation associated with the PowSyBl one. The joined voltage level and substation information is used in almost every step of the mapping between CGMES and PowSyBl models, and it is recorded in the `Context` conversion class, which keeps the data throughout the entire conversion process. ## Conversion from CGMES to PowSyBl grid model @@ -42,12 +42,12 @@ The following sections describe in detail how each supported CGMES network objec ### Substation For each substation (considering only the representative substation if they are connected by transformers) in the CGMES model a new substation is created in the PowSyBl grid model with the following attributes created as such: -- `Country` It is obtained from the `regionName` property as first option, from `subRegionName` as second option. Otherwise, is assigned to `null`. +- `Country` It is obtained from the `regionName` property as a first option, from `subRegionName` as second option. Otherwise, is assigned to `null`. - `GeographicalTags` It is obtained from the `SubRegion` property. ### VoltageLevel -As for substations, for each voltage level (considering only the representative voltage level if they are connected by switches) in the CGMES model a new voltage level is created in the PowSyBl grid model with the following attributes created as such: +As for substations, for each voltage level (considering only the representative voltage level if they are connected by switches) in the CGMES model, a new voltage level is created in the PowSyBl grid model with the following attributes created as such: - `NominalV` It is copied from the `nominalVoltage` property of the CGMES voltage level. - `TopologyKind` It will be `NODE_BREAKER` or `BUS_BREAKER` depending on the level of detail of the CGMES grid model. - `LowVoltageLimit` It is copied from the `lowVoltageLimit` property. @@ -105,7 +105,7 @@ For each `EnergySource` object in the CGMES model a new PowSyBl `Load` is create ### SvInjection -CMES uses `SvInjection` objects to report mismatches on calculated buses: they record the calculated bus injection minus the sum of the terminal flows. According to the documentation, the values will thus follow generator sign convention: positive sign means injection into the bus. Note that all the reference cases used for development follow load sign convention to report these mismatches, so we have decided to follow this load sign convention as a first approach. +CGMES uses `SvInjection` objects to report mismatches on calculated buses: they record the calculated bus injection minus the sum of the terminal flows. According to the documentation, the values will thus follow generator sign convention: positive sign means injection into the bus. Note that all the reference cases used for development follow load sign convention to report these mismatches, so we have decided to follow this load sign convention as a first approach. For each `SvInjection` in the CGMES network model a new PowSyBl `Load` with attributes created as such: - `P0`, `Q0` are set from `SvInjection.pInjection/qInjection`. @@ -124,7 +124,7 @@ an [`EquivalentBranch`](#equivalentbranch) or a [`PowerTransformer`](#powertrans Attributes of the PowSyBl generator or of the PowSyBl dangling line generation are created as such: - `MinP`/`MaxP` are copied from CGMES `minP`/`maxP` if defined, otherwise they are set to `-Double.MAX_VALUE`/`Double.MAX_VALUE`. - `TargetP`/`TargetQ` are set from `SSH` or `SV` values depending on which are defined. CGMES values for `p`/`q` are given with load sign convention, so a change in sign is applied when copying them to `TargetP`/`TargetQ`. -- `TargetV` The `regulationTarget` property is copied if it is not equal to zero. Otherwise, the nominal voltage associated to the connected terminal of the `equivalentInjection` is assigned. For CGMES Equivalent Injections the voltage regulation is allowed only at the point of connection. +- `TargetV` The `regulationTarget` property is copied if it is not equal to zero. Otherwise, the nominal voltage associated to the connected terminal of the `equivalentInjection` is assigned. For CGMES Equivalent Injections, the voltage regulation is allowed only at the point of connection. - `VoltageRegulatorOn` It is assigned to `true` if both properties, `regulationCapability` and `regulationStatus` are `true` and the terminal is connected. - `EnergySource` is set to `OTHER`. @@ -147,7 +147,7 @@ If the `ACLineSegment` has one side inside the boundary area and one side outsid If the `ACLineSegment` is mapped to a PowSyBl [`Line`](../../grid_model/network_subnetwork.md#line): - `R` is copied from CGMES `r` - `X` is copied from CGMES `x` -- `G1` is calculated as half of CMGES `gch` if defined, `0.0` otherwise +- `G1` is calculated as half of CGMES `gch` if defined, `0.0` otherwise - `G2` is calculated as half of CGMES `gch` if defined, `0.0` otherwise - `B1` is calculated as half of CGMES `bch` - `B2` is calculated as half of CGMES `bch` @@ -155,7 +155,7 @@ If the `ACLineSegment` is mapped to a PowSyBl [`Line`](../../grid_model/network_ If the `ACLineSegment` is mapped to an unpaired PowSyBl [`DanglingLine`](../../grid_model/network_subnetwork.md#dangling-line): - `R` is copied from CGMES `r` - `X` is copied from CGMES `x` -- `G` is copied from CMGES `gch` if defined, `0.0` otherwise +- `G` is copied from CGMES `gch` if defined, `0.0` otherwise - `B` is copied from CGMES `bch` - `PairingKey` is copied from the name of the `TopologicalNode` or the `ConnectivityNode` (respectively in `NODE-BREAKER` or `BUS-BRANCH`) inside boundaries - `P0` is copied from CGMES `P` of the terminal at boundary side @@ -164,10 +164,10 @@ If the `ACLineSegment` is mapped to an unpaired PowSyBl [`DanglingLine`](../../g If the `ACLineSegment` is mapped to a paired PowSyBl [`DanglingLine`](../../grid_model/network_subnetwork.md#dangling-line): - `R` is copied from CGMES `r` - `X` is copied from CGMES `x` -- `G1` is `0.0` is the dangling line is on side `ONE` of the Tie Line. If the dangling line Line is on side `TWO` of the Tie Line, it is copied from CGMES `gch` if defined, `0.0` otherwise. -- `G2` is `0.0` is the dangling line is on side `TWO` of the Tie Line. If the dangling line Line is on side `ONE` of the Tie Line, it is copied from CGMES `gch` if defined, `0.0` otherwise. -- `B1` is `0.0` is the dangling line is on side `ONE` of the Tie Line. If the dangling line Line is on side `TWO` of the Tie Line, it is copied from CGMES `bch`. -- `B2` is `0.0` is the dangling line is on side `TWO` of the Tie Line. If the dangling line Line is on side `ONE` of the Tie Line, it is copied from CGMES `bch`. +- `G1` is `0.0` is the dangling line is on side `ONE` of the Tie Line. If the dangling line is on side `TWO` of the Tie Line, it is copied from CGMES `gch` if defined, `0.0` otherwise. +- `G2` is `0.0` is the dangling line is on side `TWO` of the Tie Line. If the dangling line is on side `ONE` of the Tie Line, it is copied from CGMES `gch` if defined, `0.0` otherwise. +- `B1` is `0.0` is the dangling line is on side `ONE` of the Tie Line. If the dangling line is on side `TWO` of the Tie Line, it is copied from CGMES `bch`. +- `B2` is `0.0` is the dangling line is on side `TWO` of the Tie Line. If the dangling line is on side `ONE` of the Tie Line, it is copied from CGMES `bch`. - `PairingKey` is copied from the name of the `TopologicalNode` or the `ConnectivityNode` (respectively in `NODE-BREAKER` or `BUS-BRANCH`) inside boundaries ### EquivalentBranch @@ -262,8 +262,8 @@ An `ExternalNetworkinjection` is mapped to a PowSyBl [`Generator`](../../grid_mo Linear shunt compensators represent shunt compensators with banks or sections with equal admittance values. -A `LinearShuntCompensator` is mapped to a PowSybl [`ShuntCompensator`](../../grid_model/network_subnetwork.md#shunt-compensator) with `SectionCount` copied from CGMES SSH `sections` or CGMES `SvShuntCompensatorSections.sections`, depending on the import option. If none is defined, it is copied from CGMES `normalSections`. -The created PowSyBl shunt compensator is linear and its attributes are defined as described below: +A `LinearShuntCompensator` is mapped to a PowSyBl [`ShuntCompensator`](../../grid_model/network_subnetwork.md#shunt-compensator) with `SectionCount` copied from CGMES SSH `sections` or CGMES `SvShuntCompensatorSections.sections`, depending on the import option. If none is defined, it is copied from CGMES `normalSections`. +The created PowSyBl shunt compensator is linear, and its attributes are defined as described below: - `BPerSection` is copied from CGMES `bPerSection` if defined. Else, it is `Float.MIN_VALUE`. - `GPerSection` is copied from CGMES `gPerSection` if defined. Else, it is left undefined. - `MaximumSectionCount` is copied from CGMES `maximumSections`. @@ -272,7 +272,7 @@ The created PowSyBl shunt compensator is linear and its attributes are defined a ### NonlinearShuntCompensator -Non-linear shunt compensators represent shunt compensators with banks or section addmittance values that differs. +Non-linear shunt compensators represent shunt compensators with banks or section admittance values that differ. A `NonlinearShuntCompensator` is mapped to a PowSyBl [`ShuntCompensator`](../../grid_model/network_subnetwork.md#shunt-compensator) with `SectionCount` copied from CGMES SSH `sections` or CGMES `SvShuntCompensatorSections.sections`, depending on the import option. If none is defined, it is copied from CGMES `normalSections`. The created PowSyBl shunt compensator is non-linear and has as many `Sections` as there are `NonlinearShuntCompensatorPoint` associated with the `NonlinearShuntCompensator` it is mapped to. @@ -292,10 +292,10 @@ Power transformers represent electrical devices consisting of two or more couple #### PowerTransformer with two PowerTransformerEnds -If a `PowerTransformer` has two `PowerTransformerEnds`, both outside the boundary area, it is mapped to a PowSyBl [`TwoWindingsTransformer`](../../grid_model/network_subnetwork.md#two-windings-transformer). +If a `PowerTransformer` has two `PowerTransformerEnds`, both outside the boundary area, it is mapped to a PowSyBl [`TwoWindingsTransformer`](../../grid_model/network_subnetwork.md#two-winding-transformer). Please note that in this case, if `PowerTransformerEnds` are in different substations, the substations are merged into one. -If a `PowerTransformer` has two `PowerTransformerEnds`, both completely inside the boundary area, and if the boundary area is not imported, the `PowerTransformer` is ignored. Otherwise, it is mapped to a PowSyBl [`TwoWindingsTransformer`](../../grid_model/network_subnetwork.md#two-windings-transformer). +If a `PowerTransformer` has two `PowerTransformerEnds`, both completely inside the boundary area, and if the boundary area is not imported, the `PowerTransformer` is ignored. Otherwise, it is mapped to a PowSyBl [`TwoWindingsTransformer`](../../grid_model/network_subnetwork.md#two-winding-transformer). If the `PowerTransformer` has one `PowerTransformerEnd` inside the boundary area and the other outside the boundary area, the importer checks if another branch is connected to the same [`TopologicalNode`](#topologicalnode) in the boundary area. - If there is no other connected to this `TopologicalNode`, it is mapped to a PowSyBl [`DanglingLine`](../../grid_model/network_subnetwork.md#dangling-line). @@ -305,7 +305,7 @@ If the `PowerTransformer` has one `PowerTransformerEnd` inside the boundary area - If there are only two branches with their boundary terminal connected and in different `SubGeographicalRegion`, they will both be mapped to PowSyBl [`DanglingLines`](../../grid_model/network_subnetwork.md#dangling-line), which are part of the same PowSyBl [`TieLine`](../../grid_model/network_subnetwork.md#tie-line) and all other `EquivalentBranches` will be mapped to PowSyBl [`DanglingLines`](../../grid_model/network_subnetwork.md#dangling-line). - Otherwise, they will all be mapped to PowSyBl [`DanglingLines`](../../grid_model/network_subnetwork.md#dangling-line). -In every case, a `PowerTransformer` with two `PowerTransformerEnds` is mapped to an intermediary model that corresponds to a PowSyBl [`TwoWindingsTransformer`](../../grid_model/network_subnetwork.md#two-windings-transformer). +In every case, a `PowerTransformer` with two `PowerTransformerEnds` is mapped to an intermediary model that corresponds to a PowSyBl [`TwoWindingsTransformer`](../../grid_model/network_subnetwork.md#two-winding-transformer). For more information about this conversion, please look at the classes [`InterpretedT2xModel`](https://github.com/powsybl/powsybl-core/blob/main/cgmes/cgmes-conversion/src/main/java/com/powsybl/cgmes/conversion/elements/transformers/InterpretedT2xModel.java) and [`ConvertedT2xModel`](https://github.com/powsybl/powsybl-core/blob/main/cgmes/cgmes-conversion/src/main/java/com/powsybl/cgmes/conversion/elements/transformers/ConvertedT2xModel.java). @@ -316,7 +316,7 @@ If the `PowerTransformer` is finally mapped to a PowSyBl [`DanglingLine`](../../ #### PowerTransformer with three PowerTransformerEnds -A `PowerTransformer` with three `PowerTransformerEnds` is mapped to a PowSyBl [`ThreeWindingsTransformer`](../../grid_model/network_subnetwork.md#three-windings-transformer). +A `PowerTransformer` with three `PowerTransformerEnds` is mapped to a PowSyBl [`ThreeWindingsTransformer`](../../grid_model/network_subnetwork.md#three-winding-transformer). Please note that in this case, if `PowerTransformerEnds` are in different substations, the substations are merged into one. For more information about this conversion, please look at the classes [`InterpretedT3xModel`](https://github.com/powsybl/powsybl-core/blob/main/cgmes/cgmes-conversion/src/main/java/com/powsybl/cgmes/conversion/elements/transformers/InterpretedT3xModel.java) @@ -379,7 +379,7 @@ If the CGMES `Switch` is mapped to a PowSyBl [`DanglingLine`](../../grid_model/n ## Extensions -The CIM-CGMES format contains more information than what the `iidm` grid model needs for calculation. The additional data, that are needed to export a network in CIM-CGMES format, are stored in several extensions. +The CIM-CGMES format contains more information than what the `iidm` grid model needs for calculation. The additional data that are needed to export a network in CIM-CGMES format are stored in several extensions. ### CGMES control areas @@ -451,13 +451,13 @@ Optional property that defines the directory path where the CGMES importer can f This property can also be used at CGMES export if the network was not imported from a CGMES to indicate the boundary files that should be used for reference. **iidm.import.cgmes.convert-boundary** -Optional property that defines if the equipment located inside the boundary are imported as part of the network. Used for debugging purposes. `false` by default. +Optional property that defines if the equipment located inside the boundary is imported as part of the network. Used for debugging purposes. `false` by default. **iidm.import.cgmes.convert-sv-injections** Optional property that defines if `SvInjection` objects are converted to IIDM loads. `true` by default. **iidm.import.cgmes.create-active-power-control-extension** -Optional property that defines if active power control extensions are created for the converted generators. `true` by default. If `true`, the extension will created for the CGMES `SynchronousMachines` with the attribute `normalPF` defined. For these generators, the `normalPF` value will be saved as the `participationFactor` and the flag `participate` set to `true`. +Optional property that defines if active power control extensions are created for the converted generators. `true` by default. If `true`, the extension will be created for the CGMES `SynchronousMachines` with the attribute `normalPF` defined. For these generators, the `normalPF` value will be saved as the `participationFactor` and the flag `participate` set to `true`. **iidm.import.cgmes.create-busbar-section-for-every-connectivity-node** Optional property that defines if the CGMES importer creates an [IIDM Busbar Section](../../grid_model/network_subnetwork.md#busbar-section) for each CGMES connectivity node. Used for debugging purposes. `false` by default. @@ -481,7 +481,7 @@ Optional property that defines if IDs' and aliases' unicity is ensured during CG Optional property that defines if control areas must be imported or not. `true` by default. **iidm.import.cgmes.naming-strategy** -Optional property that defines which naming strategy is used to transform GMES identifiers to IIDM identifiers. Currently, all naming strategies assign CGMES Ids directly to IIDM Ids during import, without any transformation. The default value is `identity`. +Optional property that defines which naming strategy is used to transform CGMES identifiers to IIDM identifiers. Currently, all naming strategies assign CGMES Ids directly to IIDM Ids during import, without any transformation. The default value is `identity`. **iidm.import.cgmes.post-processors** Optional property that defines all the CGMES post-processors which will be activated after import. @@ -501,7 +501,7 @@ Optional property that defines if IIDM IDs must be obtained from the CGMES `mRID Optional property that defines if the whole CGMES model is stored in the imported IIDM network as an [extension](import.md#cgmes-model). The default value is `true`. **iidm.import.cgmes.store-cgmes-conversion-context-as-network-extension** -Optional property that defines if the CGMES conversion context will be stored as an extension of the IIDM output network. It is useful for external validation of the mapping made between CGMES and IIDM. Its default value is `false`. +Optional property that defines if the CGMES conversion context is stored as an extension of the IIDM output network. It is useful for external validation of the mapping made between CGMES and IIDM. Its default value is `false`. **iidm.import.cgmes.import-node-breaker-as-bus-breaker** Optional property that forces CGMES model to be in topology bus/breaker in IIDM. This is a key feature when some models do not have all the breakers to connect and disconnect equipments in IIDM. In bus/breaker topology, connect and disconnect equipment only rely on terminal statuses and not on breakers. Its default value is `false`. diff --git a/docs/grid_exchange_formats/cgmes/index.md b/docs/grid_exchange_formats/cgmes/index.md index 8cab44ba676..0faf82127ba 100644 --- a/docs/grid_exchange_formats/cgmes/index.md +++ b/docs/grid_exchange_formats/cgmes/index.md @@ -10,7 +10,7 @@ export.md examples.md ``` -The CGMES (**C**ommon **G**rid **M**odel **E**xchange **S**pecification) is an IEC technical specification (TS 61970-600-1, TS 61970-600-2) based on the IEC CIM (**C**ommon **I**nformation **M**odel) family of standards. It was developed to meet necessary requirements for TSO data exchanges in the areas of system development and system operation. In this scenario the agents (the Modelling Authorities) generate their Individual Grid Models (IGM) that can be assembled to build broader Common Grid Models (CGM). Boundaries between IGMs are well defined: the boundary data is shared between the modelling agents and contain all boundary points required for a given grid model exchange. +The CGMES (**C**ommon **G**rid **M**odel **E**xchange **S**pecification) is an IEC technical specification (TS 61970-600-1, TS 61970-600-2) based on the IEC CIM (**C**ommon **I**nformation **M**odel) family of standards. It was developed to meet the necessary requirements for TSO data exchanges in the areas of system development and system operation. In this scenario the agents (the Modelling Authorities) generate their Individual Grid Models (IGM) that can be assembled to build broader Common Grid Models (CGM). Boundaries between IGMs are well-defined: the boundary data is shared between the modeling agents and contain all boundary points required for a given grid model exchange. In CGMES, an electric power system model is described by data grouped in different subsets (profiles) and exchanged as CIM/XML files, with each file associated to a given profile. The profiles considered in PowSyBl are: - `EQ` Equipment. Contains data that describes the equipment present in the network and its physical characteristics. @@ -18,12 +18,12 @@ In CGMES, an electric power system model is described by data grouped in differe - `TP` Topology. Describe how the equipment is electrically connected. Contains the definition of power flow buses. - `SV` State Variables. Contains all the information required to describe a steady-state power flow solution over the network. - `EQBD` Equipment Boundary. Contains definitions of the equipment in the boundary. -- `TPBD` Topology Boundary. Topology information associated to the boundary. +- `TPBD` Topology Boundary. Topology information associated with the boundary. - `DL` Diagram Layout. Contains information about diagram positions. - `GL` Geographical Layout. Contains information about geographical positions. CGMES model connectivity can be defined at two different levels of detail: -`Node/breaker` This is the level of detail required for Operation. The `EQ` contains Connectivity Nodes where the conducting equipment are attached through its Terminals. All switching devices (breakers, disconnectors, ...) are modelled. The contents of the `TP` file must be the result of the topology processing over the graph defined by connectivity nodes and switching devices, taking into account its open/closed status. +`Node/breaker` This is the level of detail required for Operation. The `EQ` contains Connectivity Nodes where the conducting equipment is attached through its Terminals. All switching devices (breakers, disconnectors, ...) are modelled. The contents of the `TP` file must be the result of the topology processing over the graph defined by connectivity nodes and switching devices, taking into account its open/closed status. `Bus/branch` No Connectivity Nodes are present in the `EQ` file. The association of every equipment to a bus is defined directly in the `TP` file, that must be provided. diff --git a/docs/grid_exchange_formats/iidm/export.md b/docs/grid_exchange_formats/iidm/export.md index 25cebec2615..92a783b2d65 100644 --- a/docs/grid_exchange_formats/iidm/export.md +++ b/docs/grid_exchange_formats/iidm/export.md @@ -29,7 +29,7 @@ The default value is `NODE_BREAKER` to export all voltage levels in the same lev The `iidm.export.xml.throw-exception-if-extension-not-found` property is an optional property that defines whether the XIIDM exporter throws an exception if the network contains an unknown or unserializable extension or if it just ignores it. Its default value is `false`. **iidm.export.xml.extensions** -The `iidm.export.xml.extensions` property is an optional property that defines the list of extensions that we will be exported by the XIIDM exporter. By default all extensions will be exported. +The `iidm.export.xml.extensions` property is an optional property that defines the list of extensions that we will be exported by the XIIDM exporter. By default, all extensions will be exported. **iidm.export.xml.sorted** The `iidm.export.xml.sorted` property is an optional property that defines whether the XIIDM file generated by the XIIDM exporter will be sorted or not for some objects. @@ -47,7 +47,7 @@ The `iidm.export.xml.version` property is an optional property that defines the **iidm.export.xml.iidm-version-incompatibility-behavior** The `iidm.export.xml.iidm-version-incompatibility-behavior` property is an optional property that defines the behavior of the XIIDM exporter when there is a version incompatibility between the IIDM network and the XIIDM version in which the export is done. -There is two possible behaviors: +There are two possible behaviors: - `LOG_ERROR`: an error is logged when there is a version incompatibility - `THROW_EXCEPTION`: an exception is thrown when there is a version incompatibility By default, this behavior is set as `THROW_EXCEPTION` @@ -57,7 +57,7 @@ There is two possible behaviors: **iidm.export.xml.export-mode** The `iidm.export.xml.export-mode` property is an optional property that defines the export mode of the XIIDM exporter. The export mode can be: - `UNIQUE_FILE`: Exports the network and its extensions in a unique file. -- `EXTENSIONS_IN_ONE_SEPARATED_FILE`: Exports the network to a file and the extensions to another file. In this mode, if the network file name is `network.xiidm`, the extensions file name must be `network-ext.xiidm`. +- `EXTENSIONS_IN_ONE_SEPARATED_FILE`: Exports the network to a file and the extensions to another file. In this mode, if the network file name is `network.xiidm`, the extension file name must be `network-ext.xiidm`. - `ONE_SEPARATED_FILE_PER_EXTENSION_TYPE`: Exports the network to a file and each extension type to a separate file. In this mode, if the network file name is `network.xiidm`, each extension file name must be `network-extensionName.xiidm`. Example: if our network has two extensions `loadFoo` and `loadBar`, then the network will be exported to the `network.xiidm` file and `loadFoo` and `loadBar` will be exported respectively to `network-loadFoo.xiidm` and `network-loadBar.xiidm`. The default value for this parameter is `IidmImportExportMode.NO_SEPARATED_FILE_FOR_EXTENSIONS`. This property has been removed in v3.3.0. diff --git a/docs/grid_exchange_formats/iidm/import.md b/docs/grid_exchange_formats/iidm/import.md index b3e123c1912..16392f31df1 100644 --- a/docs/grid_exchange_formats/iidm/import.md +++ b/docs/grid_exchange_formats/iidm/import.md @@ -9,7 +9,7 @@ These properties can be defined in the configuration file in the [import-export- The `iidm.import.xml.throw-exception-if-extension-not-found` property is an optional property that defines if the XIIDM importer throws an exception while trying to import an unknown or undeserializable extension or if it just ignores it. Its default value is `false`. **iidm.import.xml.extensions** -The `iidm.import.xml.extensions` property is an optional property that defines the list of extensions that will be imported by the XIIDM importer. By default all extensions will be imported. +The `iidm.import.xml.extensions` property is an optional property that defines the list of extensions that will be imported by the XIIDM importer. By default, all extensions will be imported. ### Deprecated properties @@ -23,7 +23,7 @@ The `iidm.import.xml.import-mode` property is an optional property that defines Its possible values are : - `UNIQUE_FILE`: Imports the network and its extensions from a unique file. -- `EXTENSIONS_IN_ONE_SEPARATED_FILE`: Imports the network from a file and the extensions from another file. In this mode, if the network file name is network.xiidm, the extensions file name must be network-ext.xiidm. +- `EXTENSIONS_IN_ONE_SEPARATED_FILE`: Imports the network from a file and the extensions from another file. In this mode, if the network file name is network.xiidm, the extension file name must be network-ext.xiidm. - `ONE_SEPARATED_FILE_PER_EXTENSION_TYPE`: Imports the network from a file and each extension type from a separate file. In this mode, if the network file name is `network.xiidm`, each extension file name must be `network-extensionName.xiidm`. Example: if our network has two extensions `loadFoo` and `loadBar`, then the network will be imported from the `network.xiidm` file and `loadFoo` and `loadBar` will be imported respectively from `network-loadFoo.xiidm` and `network-loadBar.xiidm`. The default value of this parameter is `NO_SEPARATED_FILE_FOR_EXTENSIONS`. This property has been removed in v3.3.0. diff --git a/docs/grid_exchange_formats/iidm/index.md b/docs/grid_exchange_formats/iidm/index.md index b94416c5fb8..d90d736f70b 100644 --- a/docs/grid_exchange_formats/iidm/index.md +++ b/docs/grid_exchange_formats/iidm/index.md @@ -14,7 +14,7 @@ Several exchange formats result from this internal format: - JIIDM, which corresponds to a JSON export of IIDM, - BIIDM, which corresponds to a binary export (this is still a beta-feature). -Below are two export from a same network: +Below are two exports from the same network: - one XML export (XIIDM exchange format) - one JSON export (JIIDM exchange format) diff --git a/docs/grid_exchange_formats/index.md b/docs/grid_exchange_formats/index.md index 37dbd4b5507..4634f1463e3 100644 --- a/docs/grid_exchange_formats/index.md +++ b/docs/grid_exchange_formats/index.md @@ -17,7 +17,7 @@ or network simulation via different tools: check them out below. | [AMPL](ampl/index.md) | a data separated value format easy to parse with AMPL | ✘ | ✔ | \* Note that updated export is available, that is, export is possible if the file was imported with the same format. -For instance, if you import a UCTE-DEF file in powsybl you can update some elements and then export it back to UCTE-DEF +For instance, if you import a UCTE-DEF file in powsybl, you can update some elements and then export it back to UCTE-DEF format, but you cannot export to UCTE-DEF format a file imported from another format. ```{toctree} diff --git a/docs/grid_exchange_formats/matpower/import.md b/docs/grid_exchange_formats/matpower/import.md index 9203fcad62a..84fa4358d2d 100644 --- a/docs/grid_exchange_formats/matpower/import.md +++ b/docs/grid_exchange_formats/matpower/import.md @@ -1,8 +1,8 @@ # Import -There is a lot of Matpower open source cases available all over the internet. Most of the time, those cases are provided as a `.m` file. This is Matlab code and only Matlab can interpret this kind of data. PowSyBl converter can only import `.mat` file which is a binary serialization of Matlab case data structure created from `.m` file. +There are a lot of Matpower open source cases available all over the internet. Most of the time, those cases are provided as a `.m` file. This is Matlab code, and only Matlab can interpret this kind of data. PowSyBl converter can only import `.mat` file which is a binary serialization of Matlab case data structure created from `.m` file. ## Matpower cases conversions -To import a Matpower cases, they have to be converted to `.mat` files first. This can be done using Matlab of course, but it is also possible to use [Octave](https://www.gnu.org/software/octave/), an open source scientific programming language which is mostly compatible with Matlab. Matpower toolbox can be installed with Octave. +To import a Matpower cases, they have to be converted to `.mat` files first. This can be done using Matlab, but it is also possible to use [Octave](https://www.gnu.org/software/octave/), an open source scientific programming language which is mostly compatible with Matlab. Matpower toolbox can be installed with Octave. ### Octave and Matpower installation To install Octave, please follow the installation guide for your operating system, available on their [wiki](https://wiki.octave.org/Category:Installation). diff --git a/docs/grid_exchange_formats/psse/import.md b/docs/grid_exchange_formats/psse/import.md index aaa8ca1c675..fdfc85d0625 100644 --- a/docs/grid_exchange_formats/psse/import.md +++ b/docs/grid_exchange_formats/psse/import.md @@ -1,11 +1,11 @@ # Import The import module reads and converts a PSS®E power flow data file to the PowSyBl grid model. The current implementation supports RAW format for versions 33 and 35 and RAWX format for version 35. The import process is performed in three steps: -- Read input file. +- Read the input file. - Validate input data. - Convert input data into PowSyBl grid model. -First, input data is obtained by reading and parsing the input file and as result a PSS®E model is created in memory. This model can be viewed as a set of Java classes where each data block of the PSS®E model is associated with a specific Java class that describes all their attributes or data items. Then, some inconsistency checks are performed on this model. If the validation succeeds the PSS®E model is converted to a PowSyBl grid model. +First, input data is obtained by reading and parsing the input file, and as a result, a PSS®E model is created in memory. This model can be viewed as a set of Java classes where each data block of the PSS®E model is associated with a specific Java class that describes all their attributes or data items. Then, some inconsistency checks are performed on this model. If the validation succeeds, the PSS®E model is converted to a PowSyBl grid model. ## Options Parameters for the import can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) module. @@ -20,13 +20,13 @@ The `psse.import.ignore-base-voltage` property is an optional property that defi A PSS®E file specifies a Bus/Branch network model where typically there is a bus for each voltage level inside a substation and where substation objects are not explicitly defined. Breakers and switches were traditionally modeled as zero impedance lines with special identifiers. Since version 35 PSS®E supports explicit definition of substation data and switching devices at both system and substation level. However, this information is optional and may not be present in the case. -The PowSyBl grid model establishes the substation as a required container of voltage levels and equipments. The first step in the conversion process assigns a substation for each PSS®E bus, ensuring that all buses at transformer ends are kept in the same substation. +The PowSyBl grid model establishes the substation as a required container of voltage levels and equipment. The first step in the conversion process assigns a substation for each PSS®E bus, ensuring that all buses at transformer ends are kept in the same substation. The current conversion does not use explicit PSS®E substation information. Instead, buses are grouped using zero impedance branches and transformers as connectors. A new voltage level is created for each group of buses connected by zero impedance branches, and a new substation is created for the voltage levels connected by transformers. Explicit substations will be supported in future versions, allowing to represent the internal connectivity. -In the PowSyBl grid model all the network components are identified through a global and unique alphanumeric identifier (**Id**). Optionally, they may receive a name (**Name**). +In the PowSyBl grid model, all the network components are identified through a global and unique alphanumeric identifier (**Id**). Optionally, they may receive a name (**Name**). -For each substation the following attributes are defined: +For each substation, the following attributes are defined: - **Id** following the pattern `S` where `n` represents a consecutive integer number starting from 1. Every voltage level is assigned to its corresponding substation, with attributes: @@ -61,13 +61,13 @@ PSS®E supports loads with three different characteristics: Constant Power, Cons ### _Fixed Bus Shunt Data_ -Each _Fixed Bus Shunt Data_ record defines a PowSyBl shunt compensator with a linear model and a single section. It is possible to define multiple fixed shunts at the same bus. The PowSyBl shunt compensator is associated with its corresponding voltage level and has the following attributes: +Each _Fixed Bus Shunt Data_ record defines a PowSyBl shunt compensator with a linear model and a single section. It is possible to define multiple fixed shunts at the same bus. The PowSyBl shunt compensator is associated with its corresponding voltage level and has the following attributes: - **Id** according to the pattern `-SH` where `n` represents the PSS®E bus number (field `I` in the _Fixed Bus Shunt Data_ record) and `m` is the PSS®E alphanumeric shunt identifier (field `ID` in the _Fixed Bus Shunt Data_ record). - **ConnectableBus** PowSyBl bus identifier assigned to the PSS®E bus number (field `I` in the _Fixed Bus Shunt Data_ record). - **SectionCount** Always `1`. - **gPerSection** Positive sequence shunt (charging) conductance per section. It is defined as `GL` / (`vnom` *`vnom`), where `GL` is the active component of shunt admittance to ground, entered in MW at one per unit voltage (field `GL` in the _Fixed Bus Shunt Data_ record) and `vnom` is the nominal voltage of the corresponding voltage level. -- **bPerSection** Positive sequence shunt (charging) susceptance per section. It is defined as `BL` / (`vnom` *`vnom`), where `BL` is the reactive component of shunt admittance to ground, entered in MVAR at one per unit voltage (field `BL` in the _Fixed Bus Shunt Data_ record). +- **bPerSection** Positive sequence shunt (charging) susceptance per section. It is defined as `BL` / (`vnom` *`vnom`), where `BL` is the reactive component of shunt admittance to ground, entered in MVAR at one per-unit voltage (field `BL` in the _Fixed Bus Shunt Data_ record). - **MaximumSectionCount** Always `1`. The shunt compensator is connected to the ConnectableBus if fixed shunt status (field `STATUS` in the _Fixed Bus Shunt Data_ record) is `1` (In-service). @@ -75,7 +75,7 @@ The shunt compensator is connected to the ConnectableBus if fixed shunt status ( ### _Switched Shunt Data_ -In the PSS®E version 33 only one switched shunt element can be defined at each bus. Version 35 allows multiple switched shunts at the same bus, adding an alphanumeric switched shunt identifier. +In the PSS®E version 33, only one switched shunt element can be defined on each bus. Version 35 allows multiple switched shunts on the same bus, adding an alphanumeric switched shunt identifier. A switched shunt device may be a mix of reactors and capacitors; it is divided in blocks and steps: a block contains `n` steps of the same admittance. The steps and blocks can be adjusted to regulate a given magnitude: a voltage at a bus, a reactive power output or an admittance. Only voltage regulation is considered when mapping this equipment to PowSyBl. @@ -88,7 +88,7 @@ Each switched shunt record defines a PowSyBl shunt compensator with a non-linear - **SectionCount** Defined as the section count (section index + 1) where section `B` is closer to the initial switched shunt admittance (field `BINIT` in the _Switched Shunt Data_ record). - **TargetV** Voltage setpoint defined as `0.5` * (`VSWLO` + `VSWHI`) * `vnom`, where `VSWLO` is the controlled voltage lower limit (field `VSWLO` in the _Switched Shunt Data_ record) and `VSWHI` is the controlled voltage upper limit (field `VSWHI` in the _Switched Shunt Data_ record). - **TargetDeadband** defined as (`VSWHI` - `VSWLO`) * `vnom`. -- **RegulatingTerminal** Regulating terminal assigned to the bus where voltage is controlled by this switched shunt (field `SWREM` in version 33 or field `SWREG` in version 35, both in the _Switched Shunt Data_ record if they are not `0`. Otherwise field `I` in the _Switched Shunt Data_ record). +- **RegulatingTerminal** Regulating terminal assigned to the bus where voltage is controlled by this switched shunt (field `SWREM` in version 33 or field `SWREG` in version 35, both in the _Switched Shunt Data_ record if they are not `0`. Otherwise, field `I` in the _Switched Shunt Data_ record). - **VoltageRegulatorOn** defined as `true` if the control mode is not `0` (field `MODSW` in the _Switched Shunt Data_ record) and `TargetV` is greater than `0.0`. The shunt compensator is connected to the ConnectableBus if switched shunt status (field `STAT` in the _Switched Shunt Data_ record) is `1` (In-service). @@ -97,7 +97,7 @@ The sections of the PowSyBl shunt compensator non-linear model are defined accor The attributes of each section in the PowSyBl shunt compensator non-linear model are defined as: - **Section G** Positive sequence shunt (charging) conductance of this section. Always `0.0`. -- **Section B** Positive sequence shunt (charging) susceptance of this section. It is defined as `B` / (`vnom` *`vnom`), where `B` is the reactive component of shunt admittance to ground, entered in MVAR at one per unit voltage assigned to this section and `vnom` is the nominal voltage of the corresponding voltage level. +- **Section B** Positive sequence shunt (charging) susceptance of this section. It is defined as `B` / (`vnom` *`vnom`), where `B` is the reactive component of shunt admittance to ground, entered in MVAR at one per-unit voltage assigned to this section and `vnom` is the nominal voltage of the corresponding voltage level. When the adjustment method `ADJM` is `0`, the behaviour of the switched shunt can be mapped directly to the shunt compensator non-linear model with sections based on the switched shunt blocks/steps and its order in the PSS@E input record. A section is assigned to each step of the reactor and capacitor shunt blocks by accumulating the admittance of the corresponding steps that are in-service. Only the in-service switched shunt blocks are considered (field `SI` in version 35 of the _Switched Shunt Data_ record, always in-service in version 33). A section with 0.0 susceptance is added between sections assigned to reactor and capacitor blocks. @@ -115,7 +115,7 @@ Every _Generator Data_ single line record represents one generator. Multiple gen - **MinQ** Minimum generator reactive power. It is copied from PSS®E field `QB`. - **MaxQ** Maximum generator reactive power. It is copied from PSS®E field `QT`. - **TargetV** Voltage setpoint defined as `VS` * `vnom`, where `VS` is the regulated voltage (field `VS` in the _Generator Data_ record) and `vnom` is the nominal voltage of the corresponding voltage level. -- **RegulatingTerminal** Regulating terminal assigned to the bus where voltage is controlled by this generator (field `IREG` in the _Generator Data_ record if it is not `0`. Otherwise field `I` in the _Generator Data_ record). +- **RegulatingTerminal** Regulating terminal assigned to the bus where voltage is controlled by this generator (field `IREG` in the _Generator Data_ record if it is not `0`. Otherwise, field `I` in the _Generator Data_ record). - **VoltageRegulatorOn** defined as `true` if the type code of the associated bus is `2` or `3` (field `IDE` in the _Bus Data_ record) and `TargetV` is greater than `0.0` and `MaxQ` is greater than `MinQ`. The generator is connected to the ConnectableBus if generator status (field `STAT` in the _Generator Data_ record) is `1` (In-service). @@ -143,9 +143,9 @@ A set of current permanent limits is defined as `1000.0` * `rateMva` / (`sqrt(3. ### _Transformer Data_ -The _Transformer Data_ block defines two windings and three windings transformers. Two windings transformers have four line records, while three windings transformers have five line records. A `0` value in the field `K` of the _Transformer Data_ record first line is used to indicate that is a two windings transformer, otherwise is considered a three windings transformer. +The _Transformer Data_ block defines two- and three-winding transformers. Two-winding transformers have four line records, while three-winding transformers have five line records. A `0` value in the field `K` of the _Transformer Data_ record first line is used to indicate that is a two-winding transformer, otherwise is considered a three-winding transformer. -PSS@E two windings transformer records are mapped to two windings transformers in the PowSyBl grid model. They are associated with corresponding voltage levels inside the same substation and defined with the following attributes: +PSS@E two-winding transformer records are mapped to two-winding transformers in the PowSyBl grid model. They are associated with corresponding voltage levels inside the same substation and defined with the following attributes: - **Id** according to the pattern `T---

` where `n` represents the PSS®E bus `1` number (field `I` in the _Transformer Data_ record), `m` represents the bus `2` number (field `J` in the _Transformer Data_ record) and `p` is the circuit identifier (field `CKT` in the _Transformer Data_ record). - **ConnectableBus1** PowSyBl bus identifier assigned to the PSS®E bus `1` number (field `I` in the _Transformer Data_ record). @@ -158,7 +158,7 @@ PSS@E two windings transformer records are mapped to two windings transformers i - **X** Transmission reactance. - **G** Shunt conductance. - **B** Shunt susceptance. -- **TapChanger** Could be a ratio tap changer o a phase tap changer. +- **TapChanger** Could be a ratio tap changer or a phase tap changer. - **OperationalLimits** Current limits for both ends. The transformer is connected at both ends if the branch status (field `STAT` in the _Transformer Data_ record) is `1` (In-service) @@ -168,11 +168,11 @@ In PSS®E the transformer model allows to define a ratio and angle at the end `1 ![TwoWindingsTransformerModels](img/two-winding-transformer-model.svg){width="100%" align=center class="only-light"} ![TwoWindingsTransformerModels](img/dark_mode/two-winding-transformer-model.svg){width="100%" align=center class="only-dark"} -To express the PSS®E electric attributes of the transformer in the PowSyBl grid model the following conversions are performed: +To express the PSS®E electric attributes of the transformer in the PowSyBl grid model, the following conversions are performed: -- The first step is to define the complex impedance between windings (`Z`) by using the resistance and reactance (fields `R1-2` and `X1-2` in the _Transformer Data_ record), the winding base MVA (field `SBASE1-2` in the _Transformer Data_ record) and the system MVA base (field `SBASE` in the _Case Identification Data_ record) according to the code that defines the units in which the winding impedances `R1-2`, `X1-2` are specified (field `CZ` in the _Transformer Data_ record). Then the complex impedance (`Z`) is converted to engineering units using the nominal voltage of the voltage level at end `2` and the system MVA base. Finally it should be adjusted after fixing an ideal ratio at end `2` and moving the configured ratio to the end `1`. The obtained result is assigned to the transmission resistance and reactance of the PowSyBl transformer. +- The first step is to define the complex impedance between windings (`Z`) by using the resistance and reactance (fields `R1-2` and `X1-2` in the _Transformer Data_ record), the winding base MVA (field `SBASE1-2` in the _Transformer Data_ record) and the system MVA base (field `SBASE` in the _Case Identification Data_ record) according to the code that defines the units in which the winding impedances `R1-2`, `X1-2` are specified (field `CZ` in the _Transformer Data_ record). Then the complex impedance (`Z`) is converted to engineering units using the nominal voltage of the voltage level at end `2` and the system MVA base. Finally, it should be adjusted after fixing an ideal ratio at end `2` and moving the configured ratio to the end `1`. The obtained result is assigned to the transmission resistance and reactance of the PowSyBl transformer. -- The complex shunt admittance `Ysh` is calculated using the transformer magnetizing admittance connected to ground at bus `1` (fields `MAG1` and `MAG2` in the _Transformer Data_ record), the winding base MVA (field `SBASE1-2` in the _Transformer Data_ record), the system MVA base, the bus base voltage (field `BASKV` in the _Bus Data_ record) of the transformer bus `I` and the nominal (rated) winding `1` voltage base (field `NOMV1` in the _Transformer Data_ record) according to the magnetizing admittance code that defines the units in which `MAG1` and `MAG2` are specified (filed `CM` in the _Transformer Data_ record). The next step is to convert the complex `Ysh` to engineering units using the nominal voltage of the voltage level at end `2` and the system MVA base and finally the obtained value is assigned to the shunt conductance and susceptance of the PowSyBl transformer. The shunt conductance in the PowSyBl grid model is located after the ratio so is necessary to add a step correction by each different ratio in the tabular `tapChanger`. +- The complex shunt admittance `Ysh` is calculated using the transformer magnetizing admittance connected to ground at bus `1` (fields `MAG1` and `MAG2` in the _Transformer Data_ record), the winding base MVA (field `SBASE1-2` in the _Transformer Data_ record), the system MVA base, the bus base voltage (field `BASKV` in the _Bus Data_ record) of the transformer bus `I` and the nominal (rated) winding `1` voltage base (field `NOMV1` in the _Transformer Data_ record) according to the magnetizing admittance code that defines the units in which `MAG1` and `MAG2` are specified (filed `CM` in the _Transformer Data_ record). The next step is to convert the complex `Ysh` to engineering units using the nominal voltage of the voltage level at end `2` and the system MVA base and finally the obtained value is assigned to the shunt conductance and susceptance of the PowSyBl transformer. The shunt conductance in the PowSyBl grid model is located after the ratio, so is necessary to add a step correction by each different ratio in the tabular `tapChanger`. To define the `tapChanger` the first step is to calculate the complex ratio at end `1` and the ratio at end `2`. The ratio at end `1` is calculated using the winding ratio (field `WINDV1` in the _Transformer Data_ record), the nominal (rated) winding voltage base (field `NOMV1` in the _Transformer Data_ record) and the bus base voltage (field `BASKV` in the _Bus Data_ record) according to the code that defines the units in which the turns ratios are specified (field `CZ` in the _Transformer Data_ record). The angle at end `1` is copied from the winding phase shift angle (field `ANG1` in the _Transformer Data_ record). The ratio at end `2` is calculated in the same way as at end `1` but using the following fields (fields `WINDV2`, `NOMV1` in the _Transformer Data_ record) and the corresponding bus base voltage at bus `J` (field `BASKV` in the _Bus Data_ record).
Then a `tapChanger` at end `1` is defined by fixing one of the components of the complex ratio at end `1` and moving the other in each step using the number of tap positions available (field `NTP1` in the _Transformer Data_ record) and the upper and lower limits (fields `RMA1`, `RMI1` in the _Transformer Data_ record).
@@ -193,11 +193,11 @@ When the `tapChanger` is a `phaseTapChanger` and the transformer control mode (f - **RegulatingTerminal** Regulating terminal assigned to the bus where active power flow is controlled (field `CONT1` in the _Transformer Data_ record). - **RegulatingOn** defined as `true` if `TargetV` is greater than `0.0`. -A set of current operational limits is defined for the two windings transformer as `1000.0` * `rateMva` / (`sqrt(3.0)` * `vnom1`) at the end `1` and `1000.0` * `rateMva` / (`sqrt(3.0)` * `vnom2`) at the end `2` where `rateMva` is the first rating of the transformer (field `RATA1` in version 33 of the _Transformer Data_ record and field `RATE11` in version 35) and `vnom1` and `vnom2` are the nominal voltage of the associated voltage levels. +A set of current operational limits is defined for the two-winding transformer as `1000.0` * `rateMva` / (`sqrt(3.0)` * `vnom1`) at the end `1` and `1000.0` * `rateMva` / (`sqrt(3.0)` * `vnom2`) at the end `2` where `rateMva` is the first rating of the transformer (field `RATA1` in version 33 of the _Transformer Data_ record and field `RATE11` in version 35) and `vnom1` and `vnom2` are the nominal voltage of the associated voltage levels. -When a three windings transformer is modeled the two windings transformer steps should be followed for each leg of the transformer taking into account the following considerations: +When a three-winding transformer is modeled, the two-winding transformer steps should be followed for each leg of the transformer taking into account the following considerations: - The **Id** is defined according to the pattern `T----

` where `n` represents the PSS®E bus `1` number (field `I` in the _Transformer Data_ record), `m` represents the bus `2` number (field `J` in the _Transformer Data_ record), `o` represents the bus `3` number (field `K` in the _Transformer Data_ record) and `p` is the circuit identifier (field `CKT` in the _Transformer Data_ record). -- The three windings transformer is modeled in PowSyBl as three two windings transformers connected to an fictitious bus defined with a nominal base voltage and rated voltage of `1.0 kV` (star configuration).
+- The three-winding transformers are modeled in PowSyBl as three two-winding transformers connected to a fictitious bus defined with a nominal base voltage and rated voltage of `1.0 kV` (star configuration).
- In PSS®E the between windings transmission impedances `Z1-2`, `Z2-3` and `Z3-1` are specified in the input file. These impedances are generally supplied on a transformer data sheet or test report. The transmission impedances `Z1`, `Z2` and `Z3` of the star network equivalent model are related to them according to the following expressions (see [Modeling of Three-Winding Voltage Regulating Transformers for Positive Sequence Load Flow Analysis in PSS®E](https://static.dc.siemens.com/datapool/us/SmartGrid/docs/pti/2010July/PDFS/Modeling%20of%20Three%20Winding%20Voltage%20Regulating%20Transformers.pdf)): @@ -215,9 +215,9 @@ When a three windings transformer is modeled the two windings transformer steps `Z3 = 0.5 * (Z2-3 + Z3-1 - Z1-2)` -- All the shunt admittances of the three windings transformer in the PSS®E model are assigned to the winding `1`. There is not shunt admittance at windings `2` and `3`. -- Each winding can have a complex ratio and a `ratioTapChanger` or `phaseTapChanger` with its corresponding control, always at end `1`. The current PowSyBl version only supports one enabled control by three windings transformer so if there is more than one enabled only the first (winding `1`, winding `2`, winding `3`) is kept enabled, the rest are automatically disabled. -- In three windings transformers the status attribute (field `STAT` in the _Transformer Data_ record) could be `0` that means all the windings disconnected, `1` for all windings connected, `2` for only the second winding disconnected, `3` for the third winding disconnected and `4` for the first winding disconnected. +- All the shunt admittances of the three-winding transformers in the PSS®E model are assigned to the winding `1`. There is no shunt admittance at windings `2` and `3`. +- Each winding can have a complex ratio and a `ratioTapChanger` or `phaseTapChanger` with its corresponding control, always at end `1`. The current PowSyBl version only supports one enabled control by three-winding transformers so if there is more than one enabled only the first (winding `1`, winding `2`, winding `3`) is kept enabled, the rest are automatically disabled. +- In three-winding transformers the status attribute (field `STAT` in the _Transformer Data_ record) could be `0` that means all the windings disconnected, `1` for all windings connected, `2` for only the second winding disconnected, `3` for the third winding disconnected and `4` for the first winding disconnected. ![ThreeWindingsTransformerModels](img/three-winding-transformer-model.svg){width="100%" align=center class="only-light"} ![ThreeWindingsTransformerModels](img/dark_mode/three-winding-transformer-model.svg){width="100%" align=center class="only-dark"} diff --git a/docs/grid_exchange_formats/psse/index.md b/docs/grid_exchange_formats/psse/index.md index 78610792497..89366b28c49 100644 --- a/docs/grid_exchange_formats/psse/index.md +++ b/docs/grid_exchange_formats/psse/index.md @@ -12,6 +12,6 @@ PSS®E uses different types of files to exchange data about the network. One of The RAW file has multiple groups of records (data blocks), with each group containing a particular type of data needed in power flow. The last record of each data block is a record specifying a value of zero to indicate the end of the category. -Each record in a data block contains a set of data items separated by a comma or one or more blanks where alphanumeric attributes must be enclosed in single quotes. As many of the data items specified in the RAW file have a default value only the specific information needed should be defined in the record. +Each record in a data block contains a set of data items separated by a comma or one or more blanks where alphanumeric attributes must be enclosed in single quotes. As many of the data items specified in the RAW file have a default value, only the specific information needed should be defined in the record. -In PSS®E version 35 a new RAWX file format (Extensible Power Flow Data File) based on JSON has been introduced. It will be the standard text-based data format for PSS®E power flow data exchange. The RAWX files contain two types of data objects: Parameter Sets and Data Tables. A Parameter Set has an array with field names and a single array with field values. A Data Table has an array with field names an and array of records, each record being an array of field values. The field names array indicates the order and subset of fields for which data is provided in the data arrays. +In PSS®E version 35, a new RAWX file format (Extensible Power Flow Data File) based on JSON has been introduced. It will be the standard text-based data format for PSS®E power flow data exchange. The RAWX files contain two types of data objects: Parameter Sets and Data Tables. A Parameter Set has an array with field names and a single array with field values. A Data Table has an array with field names an and array of records, each record being an array of field values. The field names array indicates the order and subset of fields for which data is provided in the data arrays. diff --git a/docs/grid_exchange_formats/ucte/export.md b/docs/grid_exchange_formats/ucte/export.md index bcf6fae2a79..355f7ee2815 100644 --- a/docs/grid_exchange_formats/ucte/export.md +++ b/docs/grid_exchange_formats/ucte/export.md @@ -8,4 +8,4 @@ These properties can be defined in the configuration file in the [import-export- **ucte.export.naming-strategy** The `ucte.export.naming-strategy` property is an optional property that defines the naming strategy to be used for UCTE export. -Its default value is `Default`, which corresponds to an implementation that expects the network elements' ID to be totally compatible with UCTE-DEF norm (e.g. a network initially imported from a UCTE-DEF file), and throws an exception if any network element does not respect the norm. It does not do any ID modification. +Its default value is `Default`, which corresponds to an implementation that expects the network elements' ID to be totally compatible with UCTE-DEF norm (e.g., a network initially imported from a UCTE-DEF file), and throws an exception if any network element does not respect the norm. It does not do any ID modification. diff --git a/docs/grid_exchange_formats/ucte/format_specification.md b/docs/grid_exchange_formats/ucte/format_specification.md index a3a489c7a39..6b1b5c9c846 100644 --- a/docs/grid_exchange_formats/ucte/format_specification.md +++ b/docs/grid_exchange_formats/ucte/format_specification.md @@ -1,17 +1,17 @@ # Format specification -The [UCTE-DEF](https://cimug.ucaiug.org/Groups/Model%20Exchange/UCTE-format.pdf) (UCTE **D**ata **E**xchange **F**ormat) format is an exchange format specified by the UCTE, for the exchange of grid model among its members. The data refer to load flow and three-phase short-circuit studies and describe the interconnected extra high voltage network. The data are contained in an unformatted standard US ASCII file. The file is divided into 7 different blocks: +The [UCTE-DEF](https://cimug.ucaiug.org/Groups/Model%20Exchange/UCTE-format.pdf) (UCTE **D**ata **E**xchange **F**ormat) format is an exchange format specified by the UCTE, for the exchange of grid model among its members. The data refer to load flow and three-phase short-circuit studies and describe the interconnected extra high-voltage network. The data are contained in an unformatted standard US ASCII file. The file is divided into 7 different blocks: - Comments (C) - Nodes (N) - Lines (L) -- Two windings transformers (T) -- Two windings transformers regulation (RR) -- Two windings transformers special description (TT) +- Two-winding transformers (T) +- Two-winding transformers regulation (RR) +- Two-winding transformers special description (TT) - Exchange powers (E) -Each block is introduced by a key line consisting of the two characters `##` and of the character given above in brackets. The end of a block is given by the next key line or the end of the file. The information of the each block is written in lines and the contents are separated by a blank (empty space). +Each block is introduced by a key line consisting of the two characters `##` and of the character given above in brackets. The end of a block is given by the next key line or the end of the file. The information of each block is written in lines, and the contents are separated by a blank (empty space). -The grid is described in Bus/Branch topology, and only few types of equipments are supported (nodal injections, AC line, two windings transformer). Fictitious nodes are located at the electric middle of each tie line. The defined X-nodes are binding for all users. +The grid is described in Bus/Branch topology, and only a few types of equipment are supported (nodal injections, AC line, two-winding transformer). Fictitious nodes are located at the electric middle of each tie line. The defined X-nodes are binding for all users. ## File name convention The UCTE-DEF format use the following file name convention: `___.uct` with: @@ -23,7 +23,7 @@ The UCTE-DEF format use the following file name convention: `__< - `SN`: Snapshots - `RE`: Reference - `LT`: Long-term reference - - `01`...`23`: Intra-day ahead congenstion forecast. The value is the number of hours separating the case date and the generation date. + - `01`...`23`: Intra-day ahead congestion forecast. The value is the number of hours separating the case date and the generation date. - `w`: day of the week, starting with 1 for Monday - `cc`: The ISO country-code for national datasets, `UC` for UCTE-wide merged datasets without X nodes and `UX` for UCTE-wide merged datasets with X nodes - `v`: version number starting with 0 diff --git a/docs/grid_exchange_formats/ucte/import.md b/docs/grid_exchange_formats/ucte/import.md index c65ec452bc0..f2a1bd3f3a9 100644 --- a/docs/grid_exchange_formats/ucte/import.md +++ b/docs/grid_exchange_formats/ucte/import.md @@ -5,7 +5,7 @@ Then, some inconsistency checks are performed on this model. Finally, the UCTE grid model is converted into an IIDM grid model. The UCTE parser provided by PowSyBl does not support the blocks `##TT` and `##E` providing respectively a special -description of the two windings transformers and the scheduled active power exchange between countries. +description of the two-winding transformers and the scheduled active power exchange between countries. Those blocks are ignored during the parsing step. @@ -33,20 +33,20 @@ The default value is an empty list. For more details see further below about [ar ## Inconsistency checks -Once the UCTE grid model is created in memory, a consistency check is performed on the different elements (nodes, lines, two windings transformers and regulations). +Once the UCTE grid model is created in memory, a consistency check is performed on the different elements (nodes, lines, two-winding transformers and regulations). In the tables below, we summarize the inconsistency checks performed on the network for each type of equipment. -For the sake of clarity we use notations that are made explicit before each table. +For the sake of clarity, we use notations that are made explicit before each table. ### Nodes with active or reactive power generation Notations: - $P$: active power generation, in MW - $Q$: reactive power generation, in MVar -- $minP$: minimum permissible active power generation, in MW -- $maxP$: maximum permissible active power generation, in MW -- $minQ$: minimum permissible reactive power generation, in MVar -- $maxQ$: maximum permissible reactive power generation, in MVar +- $minP$: minimum permissible active power generation in MW +- $maxP$: maximum permissible active power generation in MW +- $minQ$: minimum permissible reactive power generation in MVar +- $maxQ$: maximum permissible reactive power generation in MVar - $Vreg$: voltage regulation, which can be enabled or disabled - $Vref$: voltage reference, in V @@ -73,7 +73,7 @@ Notations: | $maxQ > 9999$ | $maxQ = 9999$ | | $minQ < -9999$ | $minQ = -9999$ | -### Lines or two-windings transformers +### Lines or two-winding transformers Notations: - $X$: reactance in $\Omega$ @@ -104,16 +104,16 @@ The UCTE file name is parsed to extract metadata required to initialize the IIDM ### Node conversion There is no equivalent [voltage level](../../grid_model/network_subnetwork.md#voltage-level) or [substation](../../grid_model/network_subnetwork.md#substation) concept in the UCTE-DEF format, -so we have to create substations and voltage levels from the nodes description and the topology. +so we have to create substations and voltage levels from the node description and the topology. Two nodes are in the same substation if they have the same geographical spot (the 1st-6th character of the node code) -or are connected by a two windings transformer, a coupler or a low impedance line. -Two nodes are in the same voltage level if their code only differ by the 8th character (busbars identifier). +or are connected by a two-winding transformer, a coupler or a low-impedance line. +Two nodes are in the same voltage level if their code only differs by the eighth character (busbars identifier). **Note:** We do not create a substation, a voltage level or a bus for X-nodes. They are converted to [dangling lines](../../grid_model/network_subnetwork.md#dangling-line). For nodes with a valid active or reactive load, a [load](../../grid_model/network_subnetwork.md#load) is created. -It's ID is equal to the ID of the bus post-fixed by `_load`. +Its ID is equal to the ID of the bus post-fixed by `_load`. The `P0` and `Q0` are equal to the active load and the reactive load of the UCTE node. -For those with a valid generator, a [generator](../../grid_model/network_subnetwork.md#generator) is created. It's ID is equal to the ID of the bus post-fixed by `_generator`. +For those with a valid generator, a [generator](../../grid_model/network_subnetwork.md#generator) is created. Its ID is equal to the ID of the bus post-fixed by `_generator`. The power plant type is converted to an [energy source]() value (see the mapping table below for the matching). **Mapping table for power plant types:** @@ -140,10 +140,10 @@ as properties: - the order code is stored in the `orderCode` property - the element name is stored in the `elementName` property -The lines connected between two real nodes are converted into a [AC line](../../grid_model/network_subnetwork.md#line), except if its impedance is too small (e.g. smaller than `0.05`). +The lines connected between two real nodes are converted into an [AC line](../../grid_model/network_subnetwork.md#line), except if its impedance is too small (e.g. smaller than `0.05`). In that particular case, the line is considered as a busbar coupler, and a [switch](../../grid_model/network_subnetwork.md#breakerswitch) is created. -The susceptance of the UCTE line is splitted in two, to initialize `B1` and `B2` with equal values. -If the current limits is defined, a permanent limit is created for both ends of the line. +The susceptance of the UCTE line is split in two, to initialize `B1` and `B2` with equal values. +If the current limits are defined, a permanent limit is created for both ends of the line. The element name of the UCTE line is stored in the `elementName` property. The lines connected between a read node and an X-node are converted into a [dangling line](../../grid_model/network_subnetwork.md#dangling-line). @@ -151,13 +151,13 @@ In IIDM, a dangling line is a line segment connected to a constant load. The sum of the active load and generation (rep. reactive) is computed to initialize the `P0` (resp. `Q0`) of the dangling line. The element name of the UCTE line is stored in the `elementName` property and the geographical name of the X-node is stored in the `geographicalName` property. -### Two windings transformer conversion -The two windings transformers connected between two real nodes are converted into a [two windings transformer](../../grid_model/network_subnetwork.md#two-windings-transformer). -If the current limits is defined, a permanent limit is created only for the second side. +### Two-winding transformer conversion +The two-winding transformers connected between two real nodes are converted into a [two-winding transformer](../../grid_model/network_subnetwork.md#two-winding-transformer). +If the current limits are defined, a permanent limit is created only for the second side. The element name of the transformer is stored in the `elementName` property and the nominal power is stored in the `nominalPower` property. -If a two windings transformer is connected between a real node and an X-node, a fictitious intermediate voltage level is created, -with a single bus called an Y-node. This new voltage level is created in the same substation than the real node. +If a two-winding transformer is connected between a real node and an X-node, a fictitious intermediate voltage level is created, +with a single bus called a Y-node. This new voltage level is created in the same substation as the real node. The transformer is created between the real node and the new Y-node, and the X-node is converted into a dangling line. The only difference with a classic X-node conversion, is that the electrical characteristic are hold by the transformer and set to `0` for the dangling line, except for the reactance that is set to $0.05\space\Omega$. @@ -211,8 +211,8 @@ Each country present results in the creation of an Area in the IIDM model with: - Area **Boundaries**: all DanglingLines in the Country By default, all Area Boundaries are flagged as AC, because the UCTE-DEF format does not have any HVDC explicit description. -In order to specify which boundaries should be considered as DC in the conversion, you may supply a list of X-nodes IDs in the +To specify which boundaries should be considered as DC in the conversion, you may supply a list of X-nodes IDs in the [`ucte.import.areas-dc-xnodes` option](#ucteimportareas-dc-xnodes). -**Note:** Creating areas for German sub-regions / TSOs is not supported today (D2, D4, D7, D8). +**Note:** Creating areas for German subregions / TSOs is not supported today (D2, D4, D7, D8). Let us know if you have this use case by entering an issue in our GitHub. We also welcome contributions. diff --git a/docs/grid_exchange_formats/ucte/index.md b/docs/grid_exchange_formats/ucte/index.md index a08671e8ea2..d6cb7fbc4c4 100644 --- a/docs/grid_exchange_formats/ucte/index.md +++ b/docs/grid_exchange_formats/ucte/index.md @@ -9,6 +9,6 @@ export.md The [**U**nion for the **C**o-ordination of **T**ransmission of **E**lectricity](https://www.ucte.org), created in 1951, coordinated the operation and development of the electricity transmission grid for the Continental European synchronously operated transmission grid, thus providing a reliable platform to all participants of the Internal Electricity Market and beyond. -In 1999, UCTE re-defined itself as an association of TSOs in the context of the Internal Energy Market. Building on its experience with recommendations, UCTE turned to make its technical standards. These standards became indispensable for the reliable international operation of the high voltage grids which are all working at one “heart beat”: the 50 Hz UCTE frequency related to the nominal balance between generation and the electricity demand of some 500 million people in one of the biggest electrical synchronous interconnections worldwide. +In 1999, UCTE re-defined itself as an association of TSOs in the context of the Internal Energy Market. Building on its experience with recommendations, UCTE turned to make its technical standards. These standards became indispensable for the reliable international operation of the high-voltage grids which are all working at one “heart beat”: the 50Hz UCTE frequency related to the nominal balance between generation and the electricity demand of some 500 million people in one of the biggest electrical synchronous interconnections worldwide. -On 1 July 2009 UCTE was wound up. All operational tasks were transferred to ENTSO-E. +On 1 July 2009, UCTE was wound up. All operational tasks were transferred to ENTSO-E. diff --git a/docs/grid_features/extraction.md b/docs/grid_features/extraction.md index 4311c74f293..92a77f5086a 100644 --- a/docs/grid_features/extraction.md +++ b/docs/grid_features/extraction.md @@ -4,8 +4,8 @@ This module is used to extract a portion of a network on an area of interest def ## Define an area of interest -The network reduction is relying on a `NetworkPredicate` instance, to define an area of interest (i.e. a list of equipments to keep in the network after the reduction). -The equipments outside this area are removed and the lines, transformers and HVDC lines connecting voltage levels inside and outside this area will be replaced by injections (loads or dangling lines, depending on the implementation). +The network reduction is relying on a `NetworkPredicate` instance, to define an area of interest (i.e., a list of equipments to keep in the network after the reduction). +The equipments outside this area are removed, and the lines, transformers and HVDC lines connecting voltage levels inside and outside this area will be replaced by injections (loads or dangling lines, depending on the implementation). Before doing the reduction, one has to define the area of interest, using the `com.powsybl.iidm.reducer.NetworkPredicate` interface. This interface declares two methods: @@ -94,9 +94,9 @@ PowSyBl provides a default implementation of this interface, but you can provide The `com.powsybl.iidm.reducer.DefaultNetworkReducer` class is the PowSyBl implementation of the `NetworkReducer` interface. -It replaces the lines in the _border_ group by [loads](../grid_model/network_subnetwork.md#load) or [dangling lines](../grid_model/network_subnetwork.md#dangling-line) depending on the [options](#options), the two windings transformers and the HVDC lines by [loads](../grid_model/network_subnetwork.md#load). +It replaces the lines in the _border_ group by [loads](../grid_model/network_subnetwork.md#load) or [dangling lines](../grid_model/network_subnetwork.md#dangling-line) depending on the [options](#options), the two-winding transformers and the HVDC lines by [loads](../grid_model/network_subnetwork.md#load). -The three windings transformers are replaced by a [load](../grid_model/network_subnetwork.md#load) if only one connected voltage level is kept. If two out of three connected voltage levels are kept, the third one is automatically added by the `DefaultNetworkReducer` to the voltage levels to keep. +The three-winding transformers are replaced by a [load](../grid_model/network_subnetwork.md#load) if only one connected voltage level is kept. If two out of three connected voltage levels are kept, the third one is automatically added by the `DefaultNetworkReducer` to the voltage levels to keep. #### Replacement @@ -111,7 +111,7 @@ However, the operational limits and extensions from the original branch are not ##### Replacements by dangling lines The dangling line created in place of a line has the same ID and name as the replaced line. The resistance and reactance of the dangling line are equals to half of the resistance and reactance of the replaced line (we consider that the line is cut in the middle). -The conductance and susceptance are set to the $G_1$ and $B_1$ or to $G_2$ and $B_2$ depending on which side is kept in the network. +The conductance and susceptance are set to the $G_1$ and $B_1$ or to $G_2$ and $B_2$, depending on which side is kept in the network. The $P_0$ and $Q_0$ are set to the $P$ and $Q$ of the corresponding terminal, depending on which side is kept in the network. If the line is disconnected, $P_0$ and $Q_0$ are set to `NaN`. The connectivity information (node or bus depending on the voltage level topology) is kept. @@ -141,9 +141,9 @@ ReductionOptions options = new ReductionOptions() #### Observers -The `com.powsybl.iidm.reducer.NetworkReducerObserver` is an interface that allows to be notified each time an `Identifiable` is removed or replaced. This interface provides several methods, one per `Identifiable` sub class managed by the `DefaultNetworkReducer` implementation. There are 2 types of events: -- a _replace_ event, when an AC line, a two or three windings transformer or an HVDC line is replaced by a load or a danging line -- a _remove_ event, when a substation, a voltage level, a line, a two or three windings transformer or an HVDC line is removed. +The `com.powsybl.iidm.reducer.NetworkReducerObserver` is an interface that allows to be notified each time an `Identifiable` is removed or replaced. This interface provides several methods, one per `Identifiable` subclass managed by the `DefaultNetworkReducer` implementation. There are 2 types of events: +- a _replace_ event, when an AC line, a two or three-winding transformer or an HVDC line is replaced by a load or a danging line +- a _remove_ event, when a substation, a voltage level, a line, a two or three-winding transformer or an HVDC line is removed. ```java public interface NetworkReducerObserver { @@ -243,7 +243,7 @@ $> ./itools convert-network --input-file /home/user/input.xiidm ``` ### Observers -This example shows how to implement the `NetworkReducerObserver` and log information each time an equipment is replaced. +This example shows how to implement the `NetworkReducerObserver` and log information each time the equipment is replaced. ```java NetworkReducerObserver observer = new DefaultNetworkReducerObserver() { diff --git a/docs/grid_features/import_post_processor.md b/docs/grid_features/import_post_processor.md index 64c695dcf50..ec19a6825cb 100644 --- a/docs/grid_features/import_post_processor.md +++ b/docs/grid_features/import_post_processor.md @@ -38,7 +38,7 @@ println "Network " + network.getId() + " (" + network.getSourceFormat()+ ") is i ``` ## LoadFlow post-processor -Mathematically speaking, a [load flow](../simulation/loadflow/index) result is fully defined by the complex voltages at each node. The consequence is that most load flow algorithms converge very fast if they are initialized with voltages. As a result, it happens that load flow results include only voltages and not flows on branches. This post-processors computes the flows given the voltages. The equations (Kirchhoff law) used are the same as the one used in the [load flow validation](../user/itools/loadflow-validation.md#load-flow-results-validation) to compute $P_1^{\text{calc}}$, $Q_1^{\text{calc}}$, $P_2^{\text{calc}}$, $Q_2^{\text{calc}}$ for branches and $P_3^{\text{calc}}$, $Q_3^{\text{calc}}$ in addition for three-windings transformers. +Mathematically speaking, a [load flow](../simulation/loadflow/index) result is fully defined by the complex voltages at each node. The consequence is that most load flow algorithms converge very fast if they are initialized with voltages. As a result, it happens that load flow results include only voltages and not flows on branches. This post-processors computes the flows given the voltages. The equations (Kirchhoff law) used are the same as the one used in the [load flow validation](../user/itools/loadflow-validation.md#load-flow-results-validation) to compute $P_1^{\text{calc}}$, $Q_1^{\text{calc}}$, $P_2^{\text{calc}}$, $Q_2^{\text{calc}}$ for branches and $P_3^{\text{calc}}$, $Q_3^{\text{calc}}$ in addition for three-winding transformers. To use this post-processor, add the `com.powsybl:powsybl-loadflow-results-completion` to your classpath and enable it setting the `postProcessors` property of the `import` module. @@ -56,7 +56,7 @@ import: ``` -**Note:** This post-processor rely on the [load flow results completion]() module. +**Note:** This post-processor relies on the [load flow results completion]() module. ## Geographical data import post-processor @@ -72,7 +72,7 @@ Using the links in the table below, you can obtain the RTE data CSV files, to be | Aerial lines | [https://odre.opendatasoft.com/explore/dataset/lignes-aeriennes-rte-nv/export/](https://odre.opendatasoft.com/explore/dataset/lignes-aeriennes-rte-nv/export/) | | Underground lines | [https://odre.opendatasoft.com/explore/dataset/lignes-souterraines-rte-nv/export/](https://odre.opendatasoft.com/explore/dataset/lignes-souterraines-rte-nv/export/) | -(To download these files, you should first accept the usage conditions of the ODRÉ website, which can be found - in French only - at the bottom of the pages, and the Etalab Open License v2.0, available in English [here](https://www.etalab.gouv.fr/wp-content/uploads/2018/11/open-licence.pdf).) +(To download these files, you should first accept the usage conditions of the ODRÉ website, which can be found—in French only—at the bottom of the pages, and the Etalab Open License v2.0, available in English [here](https://www.etalab.gouv.fr/wp-content/uploads/2018/11/open-licence.pdf).)
diff --git a/docs/grid_features/loadflow_validation.md b/docs/grid_features/loadflow_validation.md index aac90676b4d..3a5cb4989ad 100644 --- a/docs/grid_features/loadflow_validation.md +++ b/docs/grid_features/loadflow_validation.md @@ -14,7 +14,7 @@ $$\begin{equation} \end{equation}$$ ## Branches -Lines and two windings transformers are converted into classical PI models: +Lines and two-winding transformers are converted into classical PI models: ``` V1*exp(j*theta1) rho1*exp(j*alpha1) r+j*x rho2*exp(j*alpha2) V2*exp(j*theta2) @@ -36,19 +36,19 @@ Lines and two windings transformers are converted into classical PI models: - $(g_1, b_1)$ and $(g_2, b_2)$: Complex shunt impedance on each side (S). - $(r, x)$: Complex series impedance $(\Omega)$. -Thanks to Kirchhoff laws (see the [line](../grid_model/network_subnetwork.md#line) and [2-winding transformer](../grid_model/network_subnetwork.md#two-windings-transformer) documentation), estimations of powers are computed according to the voltages and the characteristics of the branch: +Thanks to Kirchhoff laws (see the [line](../grid_model/network_subnetwork.md#line) and [2-winding transformer](../grid_model/network_subnetwork.md#two-winding-transformer) documentation), estimations of powers are computed according to the voltages and the characteristics of the branch: $(P_1^{calc}, Q_1^{calc}, P_2^{calc}, Q_2^{calc}) = f(\text{Voltages}, \text{Characteristics})$ -## Three-windings transformers -To be implemented, based on a conversion into 3 two-windings transformers. +## Three-winding transformers +To be implemented, based on a conversion into 3 two-winding transformers. ## Generators ### Active power There may be an imbalance between the sum of generator active power setpoints $\text{targetP}$ on one side and consumption -and losses on the other side, after the load flow optimization process. Note that, if it is possible to modify the setpoints during the computation -(for example if the results were computed by an Optimal Power Flow and not a Power Flow), there should be no imbalance left. +and losses on the other side, after the load flow optimization process. Note that if it is possible to modify the setpoints during the computation +(for example, if the results were computed by an Optimal Power Flow and not a Power Flow), there should be no imbalance left. In case of an imbalance between the sum of generator active power setpoints $\text{targetP}$ on one side and consumption and losses on the other side, the generation $P$ of some units has to be adjusted. @@ -101,7 +101,7 @@ A shunt is expected to generate reactive power according to the number of activa $\left| Q + \text{#sections} * B V^2 \right| < \epsilon$ ## Static VAR Compensators -Static VAR Compensators behave like generators producing 0 active power except that their reactive bounds are expressed +Static VAR Compensators behave like generators producing zero active power except that their reactive bounds are expressed in susceptance, so that they are voltage dependent. $targetP = 0$ MW @@ -123,7 +123,7 @@ To be done. ## Transformers with a ratio tap changer -Transformers with a ratio tap changer have a tap with a finite discrete number of position that allows to change their transformer ratio. +Transformers with a ratio tap changer have a tap with a finite discrete number of positions that allows to change their transformer ratio. Let's assume that the logic is based on deadband: if the deviation between the measurement and the setpoint is higher than the deadband width, the tap position is increased or decreased by one unit. diff --git a/docs/grid_model/additional.md b/docs/grid_model/additional.md index 448c3dd24b7..cc504bf09fb 100644 --- a/docs/grid_model/additional.md +++ b/docs/grid_model/additional.md @@ -68,11 +68,11 @@ generator.newReactiveCapabilityCurve() ## Loading Limits [![Javadoc](https://img.shields.io/badge/-javadoc-blue.svg)](https://javadoc.io/doc/com.powsybl/powsybl-core/latest/com/powsybl/iidm/network/LoadingLimits.html) -Some equipment have operational limits regarding the current, active power or apparent power value, corresponding to the equipment's physical limitations (related to heating). +Some equipment has operational limits regarding the current, active power or apparent power value, corresponding to the equipment's physical limitations (related to heating). Loading limits can be declined into active power limits (in MW), apparent power limits (in kVA) and current limits (in A). They may be set for [lines](./network_subnetwork.md#line), -[dangling lines](./network_subnetwork.md#dangling-line), [two windings transformers](./network_subnetwork.md#two-windings-transformer) and [three windings transformers](./network_subnetwork.md#three-windings-transformer). The active power limits are in absolute value. +[dangling lines](./network_subnetwork.md#dangling-line), [two-winding transformers](./network_subnetwork.md#two-winding-transformer) and [three-winding transformers](./network_subnetwork.md#three-winding-transformer). The active power limits are in absolute value. Loading limits are defined by one permanent limit and any number of temporary limits (zero or more). The permanent limit sets the current, active power or apparent power absolute value under which the equipment can safely @@ -83,16 +83,16 @@ A temporary limit thus has an **acceptable duration**. The component on which the current limits are applied can safely remain between the preceding limit (it could be another temporary limit or a permanent limit) and this limit for a duration up to the acceptable duration. -Please look at this scheme to fully understand the modelling (the following example shows current limits but this modelling is valid for all loading limits): +Please look at this scheme to fully understand the modeling (the following example shows current limits, but this modeling is valid for all loading limits): ![Loading limits model](img/current-limits.svg){width="50%" align=center class="only-light"} ![Loading limits model](img/dark_mode/current-limits.svg){width="50%" align=center class="only-dark"} -Note that, following this modelling, in general the last temporary limit (the higher one in value) should be infinite with an acceptable duration different from zero, except for tripping current modeling where the last temporary limit is infinite with an acceptable duration equal to zero. If temporary limits are modeled, the permanent limit becomes mandatory. +Note that, following this modeling, in general, the last temporary limit (the higher one in value) should be infinite with an acceptable duration different from zero, except for tripping current modeling where the last temporary limit is infinite with an acceptable duration equal to zero. If temporary limits are modeled, the permanent limit becomes mandatory. (limit-group-collection)= ### Limit group collection -In network development studies or in an operational context (CGMES), we can have a set of operational limits according to the season (winter vs summer for example), the time of the day (day vs night) etc. +In network development studies or in an operational context (CGMES), we can have a set of operational limits according to the season (winter vs summer, for example), the time of the day (day vs night) etc. In PowSyBl, users can store a collection of limits: - Active power limits, apparent power limits and current limits are gathered into an `OperationalLimitsGroup` object. This group has an `id`. - Lines and transformers are associated with a collection of `OperationalLimitsGroup` (one collection per side/leg). @@ -151,11 +151,11 @@ CurrentLimits currentLimits = network.getDanglingLine("DL").newCurrentLimits() ## Phase tap changer [![Javadoc](https://img.shields.io/badge/-javadoc-blue.svg)](https://javadoc.io/doc/com.powsybl/powsybl-core/latest/com/powsybl/iidm/network/PhaseTapChanger.html) -A phase tap changer can be added to either [two windings transformers](./network_subnetwork.md#two-windings-transformer) or [three windings transformers' legs](./network_subnetwork.md#three-windings-transformer-leg). +A phase tap changer can be added to either [two-winding transformers](./network_subnetwork.md#two-winding-transformer) or [three-winding transformers' legs](./network_subnetwork.md#three-winding-transformer-leg). **Specifications** -A phase tap changer is described by a set of tap positions (or steps) within which the transformer or transformer leg can operate. Additionally to that set of steps, it is necessary to specify: +A phase tap changer is described by a set of tap positions (or steps) within which the transformer or transformer leg can operate. Additionally, to that set of steps, it is necessary to specify: - the lowest tap position - the highest tap position - the position index of the current tap (which has to be within the highest and lowest tap position bounds) @@ -184,7 +184,7 @@ Each step of a phase tap changer has the following attributes: **Example** -This example shows how to add a phase tap changer to a two windings transformer: +This example shows how to add a phase tap changer to a two-winding transformer: ```java twoWindingsTransformer.newPhaseTapChanger() .setLowTapPosition(-1) @@ -224,11 +224,11 @@ twoWindingsTransformer.newPhaseTapChanger() ## Ratio tap changer [![Javadoc](https://img.shields.io/badge/-javadoc-blue.svg)](https://javadoc.io/doc/com.powsybl/powsybl-core/latest/com/powsybl/iidm/network/RatioTapChanger.html) -A ratio tap changer can be added to either [two windings transformers](./network_subnetwork.md#two-windings-transformer) or [three windings transformers' legs](./network_subnetwork.md#three-windings-transformer-leg). +A ratio tap changer can be added to either [two-winding transformers](./network_subnetwork.md#two-winding-transformer) or [three-winding transformers' legs](./network_subnetwork.md#three-winding-transformer-leg). **Specifications** -A ratio tap changer is described by a set of tap positions (or steps) within which the transformer or transformer leg can operate (or be operated offload). Additionally to that set of steps, it is necessary to specify: +A ratio tap changer is described by a set of tap positions (or steps) within which the transformer or transformer leg can operate (or be operated offload). Additionally, to that set of steps, it is necessary to specify: - the lowest tap position - the highest tap position - the position index of the current tap (which has to be within the highest and lowest tap position bounds) @@ -252,7 +252,7 @@ Each step of a ratio tap changer has the following attributes: **Example** -This example shows how to add a ratio tap changer to a two windings transformer: +This example shows how to add a ratio tap changer to a two-winding transformer: ```java twoWindingsTransformer.newRatioTapChanger() .setLowTapPosition(-1) diff --git a/docs/grid_model/extensions.md b/docs/grid_model/extensions.md index 54519106dce..363b38a1fb1 100644 --- a/docs/grid_model/extensions.md +++ b/docs/grid_model/extensions.md @@ -2,10 +2,10 @@ # Grid model extensions The grid model contains enough data to basically describe supported components and run power flow computations, but it may not be sufficient for more complex studies. -The extensions are a way to add additional structured data to an equipment to extend its features. +The extensions are a way to add additional structured data to a piece of equipment to extend its features. The extensions can be attached to any objects of a network or to the network itself. -Some extensions are mono-variant meaning the data are identical for all the variants of the network. However, some of them are multi-variants to allow a different value for each variant of the network. It's typically the case for the [LoadDetail](#load-detail) extension that give the distribution of the constant part and the thermo-sensitive part of a consumption. +Some extensions are mono-variant, meaning the data are identical for all the variants of the network. However, some of them are multi-variants to allow a different value for each variant of the network. It's typically the case for the [LoadDetail](#load-detail) extension that give the distribution of the constant part and the thermosensitive part of the consumption. Note that some extensions provided by PowSyBl aren't supported in the [persistent implementation of IIDM](../../developer/repositories/powsybl-network-store-server.md). @@ -39,7 +39,7 @@ This extension is provided by the `com.powsybl:powsybl-iidm-extensions` module. (branch-observability-extension)= ## Branch observability -This extension models branches' flows' observability on both sides, obtained after a state estimation. +This extension models branch flow observability on both sides, obtained after a state estimation. | Attribute | Type | Unit | Required | Default value | Description | |------------|----------------------|------|----------|---------------|---------------------------------------------------------| @@ -62,7 +62,7 @@ This extension is provided by the `com.powsybl:powsybl-iidm-extensions` module. (busbar-section-position-extension)= ## Busbar section position -This extension gives positions information about a busbar section. The `busbarIndex` gives the position of the busbar section relatively to other busbars. The `sectionIndex` gives the position of the busbar section within the corresponding busbar. Note that a busbar is a set of busbar sections. Hence, the sections of a same busbar should have the same busbar index. The busbar indices induce an order of busbars within the voltage level, which usually reflects the busbars physical relative positions. Similarly, the section indices induce an order of sections of a same busbar, which usually reflects their physical relative position. +This extension gives positions information about a busbar section. The `busbarIndex` gives the position of the busbar section relative to other busbar sections. The `sectionIndex` gives the position of the busbar section within the corresponding busbar. Note that a busbar is a set of busbar sections. Hence, the sections of the same busbar should have the same busbar index. The busbar indices induce an order of busbars within the voltage level, which usually reflects the busbars physical relative positions. Similarly, the section indices induce an order of sections of the same busbar, which usually reflects their physical relative position. (connectable-position-extension)= ## Connectable position @@ -72,7 +72,7 @@ This extension gives positions information about a busbar section. The `busbarIn (coordinated-reactive-control-extension)= ## Coordinated reactive control -Some generators can be coordinated to control reactive power in a point of the network. This extension is used to configure the percent of reactive coordinated control that comes from a generator. This extension is attached to a [generator](network_subnetwork.md#generator). +Some generators can be coordinated to control reactive power in a point of the network. This extension is used to configure the percentage of reactive-coordinated control that comes from a generator. This extension is attached to a [generator](network_subnetwork.md#generator). | Attribute | Type | Unit | Required | Default value | Description | |-----------|-----------------|------|----------|---------------|-----------------------------------------------| @@ -85,14 +85,14 @@ generator.newExtension(CoordinatedReactiveControlAdder.class) .add(); ``` -Please note that the sum of the $qPercent$ values of the generators coordinating a same point of the network must be 100. +Please note that the sum of the $qPercent$ values of the generators coordinating the same point of the network must be 100. This extension is provided by the `com.powsybl:powsybl-iidm-extensions` module. (discrete-measurements-extensions)= ## Discrete measurements -This extension is used to store discrete measurements (such as tap positions, switch positions etc.) collected in substations. +This extension is used to store discrete measurements (such as tap positions, switch positions, etc.) collected in substations. | Attribute | Type | Unit | Required | Default value | Description | |----------------------|---------------------------------|------|----------|---------------|------------------------------------------------------| @@ -131,7 +131,7 @@ $$P = P0 + k~(ph1 - ph2)$$ (hvdc-operator-active-power-range-extension)= ## HVDC operator active power range -This extension enables to replace the operational limits of an DC line in AC emulation. In that case, the VSC converter stations min active power and max active power are not used. +This extension enables to replace the operational limits of a DC line in AC emulation. In that case, the VSC converter stations min active power and max active power are not used. (generator-enstoe-category-extension)= ## Generator ENTSO-E category @@ -141,7 +141,7 @@ This extension enables to replace the operational limits of an DC line in AC emu (generator-short-circuit)= ## Generator short-circuit -This extension models the generators data used for short-circuit calculations. Depending on the type of short-circuit study to be +This extension models the generator data used for short-circuit calculations. Depending on the type of short-circuit study to be performed, either the transient or the sub-transient reactance should be filled. The reactance of the step-up transformer should be filled if the generator has a transformer that is not directly modeled in the network. @@ -186,7 +186,7 @@ The code is similar for every identifiable. (injection-observability-extension)= ## Injection observability -This extension models injections' flows' observability, obtained after a state estimation. +This extension models injection flow observability, obtained after a state estimation. | Attribute | Type | Unit | Required | Default value | Description | |-----------|----------------------|------|----------|---------------|---------------------------------------------| @@ -248,7 +248,7 @@ S_{Ci_{Load}}=S_{C}=P_{C}+j.Q_{C} \\ \end{align} $$ -But for a balanced load flow, the constant power load $P$ and $Q$ refer to the positive sequence load. Given that, in balanced conditions, the load for zero and negative sequences should always be zero. However, in real life, power loads are better defined in the ABC three phases representation. The load extension addresses this issue keeping the default behavior for balanced conditions. +But for a balanced load flow, the constant power load $P$ and $Q$ refer to the positive sequence load. Given that, in balanced conditions, the load for zero and negative sequences should always be zero. However, in real life, power loads are better defined in the ABC three-phase representation. The load extension addresses this issue keeping the default behavior for balanced conditions. Balanced load flow conditions: @@ -292,14 +292,14 @@ S_{Ci_{Load}}=P_{Load}+j.Q_{Load} \\ \end{align} $$ -| Attribute | Type | Unit | Required | Default value | Description | -| --------- | ---- | ---- | -------- | ------------- | ----------- | -| deltaPa | double | MW | No | 0 | The unbalanced part of the active power setpoint at phase A (balanced parts for each phase are described by its active power setpoint $P0$ and its reactive power setpoint $Q0$) | -| deltaQa | double | MVar | No | 0 | The unbalanced part of the reactive power setpoint at phase A | -| deltaPb | double | MW | No | 0 | The unbalanced part of the active power setpoint at phase B | -| deltaQb | double | MVar | No | 0 | The unbalanced part of the reactive power setpoint at phase B | -| deltaPc | double | MW | No | 0 | The unbalanced part of the active power setpoint at phase C | -| deltaQc | double | MVar | No | 0 | The unbalanced part of the reactive power setpoint at phase C | +| Attribute | Type | Unit | Required | Default value | Description | +|-----------|--------|------|----------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| deltaPa | double | MW | No | 0 | The unbalanced part of the active power setpoint at phase A (balanced parts for each phase are described by its active power setpoint $P0$ and its reactive power setpoint $Q0$) | +| deltaQa | double | MVar | No | 0 | The unbalanced part of the reactive power setpoint at phase A | +| deltaPb | double | MW | No | 0 | The unbalanced part of the active power setpoint at phase B | +| deltaQb | double | MVar | No | 0 | The unbalanced part of the reactive power setpoint at phase B | +| deltaPc | double | MW | No | 0 | The unbalanced part of the active power setpoint at phase C | +| deltaQc | double | MVar | No | 0 | The unbalanced part of the reactive power setpoint at phase C | Here is how to add a load detail extension to a load: ```java @@ -316,8 +316,8 @@ This extension is provided by the `com.powsybl:powsybl-iidm-extensions` module. (load-detail-extension)= ## Load detail A load is described by its active power setpoint $P0$ and its reactive power setpoint $Q0$. This extension is used to detail : -- In the total amount of active power what is fixed and what is time-dependant (also called variable). The time-dependant part can be adjusted for production equals consumption. -- In the total amount of reactive power what is fixed and what is time-dependant (also called variable). +- In the total amount of active power what is fixed and what is time-dependent (also called variable). The time-dependent part can be adjusted for production equals consumption. +- In the total amount of reactive power what is fixed and what is time-dependent (also called variable). | Attribute | Type | Unit | Required | Default value | Description | |-----------------------|--------|------|----------|---------------|---------------------------------------------------------------------| @@ -374,7 +374,7 @@ three-winding transformers, HVDC line and a dangling line. The status could be: ## Reference Priority This extension is attached to a Generator, or a BusBarSection or a Load and is used to define the angle reference bus of -a power flow calculation, i.e. which bus will be used with a zero voltage angle. +a power flow calculation, i.e. which bus will be used with a zero-voltage angle. Use this extension before a computation to force the reference bus selection. The support of this feature by Load Flow implementations may vary. For example, the [OpenLoadFlow](../simulation/powerflow/openlf.md) implementation today supports Reference Priorities on generators only when this feature is activated. @@ -422,7 +422,7 @@ This extension is provided by the `com.powsybl:powsybl-iidm-api` module. (remote-reactive-power-control-extension)= ## Remote reactive power control -This extensions is used for generators with a remote reactive control. +This extension is used for generators with a remote reactive control. | Attribute | Type | Unit | Required | Default value | Description | |--------------------|------------|------|----------|---------------|----------------------------------------------------| @@ -481,10 +481,10 @@ station.newExtension(SubstationPositionAdder.class) .add(); ``` -(three-windings-transformer-phase-angle-clock-extension)= -## Three-windings transformer phase angle clock +(three-winding-transformer-phase-angle-clock-extension)= +## Three-winding transformer phase angle clock -This extension is used to model the Vector Group of a three windings transformer. The phase angle clock could be modeled at leg 2, leg 3 or both legs 2 and 3 and of a three windings transformer (network side). The voltage phase angle displacement is represented with clock hours. The valid values are `0` to `11`. This extension is attached to a [three windings transformer](network_subnetwork.md#three-windings-transformer). +This extension is used to model the Vector Group of a three-winding transformer. The phase angle clock could be modeled at leg 2, leg 3 or both legs 2 and 3 and of a three-winding transformer (network side). The voltage phase angle displacement is represented with clock hours. The valid values are `0` to `11`. This extension is attached to a [three-winding transformer](network_subnetwork.md#three-winding-transformer). | Attribute | Type | Unit | Required | Default value | Description | |---------------------|------------|-------|----------|---------------|-----------------------------------------------| @@ -500,10 +500,10 @@ transformer.newExtension(ThreeWindingsTransformerPhaseAngleClock.class) This extension is provided by the `com.powsybl:powsybl-iidm-extensions` module. -(three-windings-transformer-to-be-estimated-extension)= -## Three-windings transformer to be estimated +(three-winding-transformer-to-be-estimated-extension)= +## Three-winding transformer to be estimated -This extension is used to indicate if a three-winding transformer tap changer is to be estimated during a state estimation, i.e. if its tap position should be an output of the state estimation. +This extension is used to indicate if a three-winding transformer tap changer is to be estimated during a state estimation, i.e., if its tap position should be an output of the state estimation. * The three-winding transformer model offers the possibility to have up to 3 ratio tap changers and up to 3 phase tap changers. Each tap changer can be estimated or not. * If a tap changer is not to be estimated, it should not be changed during a state estimation (its tap position is merely an input of the state estimation). @@ -529,10 +529,10 @@ transformer.newExtension(ThreeWindingsTransformerToBeEstimatedAdder.class) .add(); ``` -(two-windings-transformer-phase-angle-clock-extension)= -## Two-windings transformer phase angle clock +(two-winding-transformer-phase-angle-clock-extension)= +## Two-winding transformer phase angle clock -This extension is used to model the Vector Group of a two windings transformer. The phase angle clock is modeled at side 2 of a two windings transformer. The voltage phase angle displacement is represented with clock hours. The valid values are 0 to 11. This extension is attached to a [two windings transformer](network_subnetwork.md#two-windings-transformer). +This extension is used to model the Vector Group of a two-winding transformer. The phase angle clock is modeled at side 2 of a two-winding transformer. The voltage phase angle displacement is represented with clock hours. The valid values are 0 to 11. This extension is attached to a [two-winding transformer](network_subnetwork.md#two-winding-transformer). | Attribute | Type | Unit | Required | Default value | Description | |-----------------|------------|-------|----------|---------------|--------------------------------------| @@ -546,10 +546,10 @@ transformer.newExtension(TwoWindingsTransformerPhaseAngleClockAdder.class) This extension is provided in the module `com.powsybl:powsybl-iidm-extensions`. -(two-windings-transformer-to-be-estimated-extension)= -## Two-windings transformer to be estimated +(two-winding-transformer-to-be-estimated-extension)= +## Two-winding transformer to be estimated -This extension is used to indicate if a two-winding transformer tap changer is to be estimated during a state estimation, i.e. if its tap position should be an output of the state estimation. +This extension is used to indicate if a two-winding transformer tap changer is to be estimated during a state estimation, i.e., if its tap position should be an output of the state estimation. * A two-winding transformer has a ratio tap changer and/or a phase tap changer. Each tap changer can be estimated or not. * If a tap changer is not to be estimated, it should not be changed during a state estimation (its tap position is merely an input of the state estimation). diff --git a/docs/grid_model/index.md b/docs/grid_model/index.md index 30e37971a04..c8dccbba5d6 100644 --- a/docs/grid_model/index.md +++ b/docs/grid_model/index.md @@ -10,7 +10,7 @@ going_further.md Powsybl features are strongly based on an internal grid model initially developed under the iTesla project, a research project funded by the [European Union 7th Framework programme](https://cordis.europa.eu/project/id/283012) (FP7). The grid model is known as `iidm` (iTesla Internal Data Model). One of the iTesla outputs was a toolbox designed to support the decision-making process of power system operation from two-days ahead to real time. The `iidm` grid model was at the center of the toolbox. -To build an electrical network model, the substations must be defined first. The equipment of a substation (busbar sections, switches, buses, loads, generators, shunt compensators, static VAR compensators, HVDC converters stations, etc.) are grouped in voltage levels. Transformers present in a substation connect its different voltage levels. Transmission lines (AC and DC) connect the substations. +To build an electrical network model, the substations must be defined first. The equipment of a substation (busbar sections, switches, buses, loads, generators, shunt compensators, static VAR compensators, HVDC converters stations, etc.) is grouped in voltage levels. Transformers present in a substation connect its different voltage levels. Transmission lines (AC and DC) connect the substations. The grid model allows a full representation of the substation connectivity where all the switching devices and busbar sections are defined, this topology is called node/breaker view. Automated topology calculation allows for the calculation of the network bus/breaker view as well as the network bus view. diff --git a/docs/grid_model/network_subnetwork.md b/docs/grid_model/network_subnetwork.md index 876dc5ec418..93fc2b1d287 100644 --- a/docs/grid_model/network_subnetwork.md +++ b/docs/grid_model/network_subnetwork.md @@ -1,16 +1,16 @@ # Network and subnetwork -In the following sections the different network components are described in terms of their main attributes and electrotechnical representation. The attributes shared by all the network components are described in the next table: +In the following sections, the different network components are described in terms of their main attributes and electrotechnical representation. The attributes shared by all the network components are described in the next table: -| Attribute | Description | -| --------- | ----------- | -| $Id$ | Unique Id assigned to each network component | -| $Name$ | Human readable identifier (not necessary unique) | -| $Fictitious$ | To identify non-physical network components | -| $Aliases$ | Additional unique identifiers associated with each network component | -| $Properties$ | To add additional data items to network components | +| Attribute | Description | +|--------------|----------------------------------------------------------------------| +| $Id$ | Unique Id assigned to each network component | +| $Name$ | Human readable identifier (not necessary unique) | +| $Fictitious$ | To identify non-physical network components | +| $Aliases$ | Additional unique identifiers associated with each network component | +| $Properties$ | To add additional data items to network components | -All equipment and the network itself are identified by a unique identifier which is the only required attribute. They can have a human-readable name. offer the possibility of adding additional unique identifiers to each component. An alias can be qualified to indicate what it corresponds to. +All equipment and the network itself are identified by a unique identifier which is the only required attribute. They can have a human-readable name. Offers the possibility of adding additional unique identifiers to each component. An alias can be qualified to indicate what it corresponds to. Properties allow associating additional arbitrary data items under the general schema of pairs ``. @@ -31,10 +31,10 @@ In the PowSyBl grid model, the Network contains [substations](#substation), whic **Characteristics** -| Attribute | Description | -| --------- | ----------- | -| $SourceFormat$ | Source format of the imported network model | -| $CaseDate$ | Date and time of the target network that is being modeled | +| Attribute | Description | +|--------------------|-------------------------------------------------------------------------| +| $SourceFormat$ | Source format of the imported network model | +| $CaseDate$ | Date and time of the target network that is being modeled | | $ForecastDistance$ | Number of minutes between the network generation date and the case date | The `SourceFormat` attribute is a required attribute that indicates the origin of the network model automatically set by the [importers](../grid_exchange_formats/index.md). If the case date and the forecast distance cannot be found in the case file, the network is considered as a snapshot: the case date is set to the current date, and the forecast distance is set to `0`. @@ -49,11 +49,11 @@ A substation represents a specific geographical location with equipment grouped **Characteristics** -| Attribute | Description | -| --------- |---------------------------------------------------------------------| -| $Country$ | To specify in which country the substation is located | -| $GeographicalTags$ | They make it possible to accurately locate the substation | -| $TSO$ | To track to which Transmission System Operator the substation belongs | +| Attribute | Description | +|--------------------|-----------------------------------------------------------------------| +| $Country$ | To specify in which country the substation is located | +| $GeographicalTags$ | They make it possible to accurately locate the substation | +| $TSO$ | To track to which Transmission System Operator the substation belongs | All three attributes are optional. @@ -68,12 +68,12 @@ A voltage level contains equipment with the same nominal voltage. Two voltage le **Characteristics** -| Attribute | Unit | Description | -| --------- | ---- | ----------- | -| $NominalVoltage$ | kV | Nominal base voltage | -| $LowVoltageLimit$ | kV | Low voltage limit magnitude | -| $HighVoltageLimit$ | kV | High voltage limit magnitude | -| $TopologyKind$ | | Level of connectivity detail | +| Attribute | Unit | Description | +|--------------------|------|------------------------------| +| $NominalVoltage$ | kV | Nominal base voltage | +| $LowVoltageLimit$ | kV | Low voltage limit magnitude | +| $HighVoltageLimit$ | kV | High voltage limit magnitude | +| $TopologyKind$ | | Level of connectivity detail | **Specifications** @@ -81,7 +81,7 @@ Only `NominalVoltage` and `TopologyKind` are required. The connectivity in each voltage level of the network can be defined at one of two levels: `node/breaker` or `bus/breaker`. The connectivity level can be different in each voltage level of the model. -In `node/breaker` the connectivity is described with the finest level of detail and can provide an exact field representation. This level could be described as a graph structure where the vertices are `Nodes` and the edges are `Switches` (breakers, disconnectors) or internal connections. Each equipment is associated to one `Node` (busbar sections, loads, generators, ..), two `Nodes` (transmission lines, two-windings transformers, ...) or three `Nodes` (three-windings transformers). Each `Node` can only have one associated equipment. `Nodes` do not have an alphanumeric `Id` or `Name`, they are identified by an integer. +In `node/breaker` the connectivity is described with the finest level of detail and can provide an exact field representation. This level could be described as a graph structure where the vertices are `Nodes` and the edges are `Switches` (breakers, disconnectors) or internal connections. Each equipment is associated to one `Node` (busbar sections, loads, generators, ..), two `Nodes` (transmission lines, two-winding transformers, ...) or three `Nodes` (three-winding transformers). Each `Node` can only have one associated equipment. `Nodes` do not have an alphanumeric `Id` or `Name`, they are identified by an integer. Using `bus/breaker` the voltage level connectivity is described with a coarser level of detail. In this case the vertices of the graph are `Buses`, defined explicitly by the user. A `Bus` has an `Id`, and may have a `Name`. Each equipment defines the bus or buses to which it is connected. `Switches` can be defined between buses. @@ -92,7 +92,7 @@ The following diagram represents an example voltage level with two busbars separ ![VoltageLevel](img/voltage-level.svg){width="100%" align=center class="only-light"} ![VoltageLevel](img/dark_mode/voltage-level.svg){width="100%" align=center class="only-dark"} -When defining the model, the user has to specify how the different equipment connect to the network. If the voltage level is built at node/breaker level, the user has to specify a `Node` when adding equipment to the model. If the user is building using bus/breaker level, the `Bus` of the equipment must be specified. Using this information, the model creates a `Terminal` that will be used to manage the point of connection of the equipment to the network. +When defining the model, the user has to specify how the different pieces of equipment connect to the network. If the voltage level is built at node/breaker level, the user has to specify a `Node` when adding equipment to the model. If the user is building using bus/breaker level, the `Bus` of the equipment must be specified. Using this information, the model creates a `Terminal` that will be used to manage the point of connection of the equipment to the network. **Available extensions** @@ -111,14 +111,14 @@ Area boundaries can be terminals of equipments or `Boundary` objects from [dangl The area type is used to distinguish between various area concepts of different granularity. For instance: control areas, bidding zones, countries... -A [voltage level](#voltage-level) can belong to several areas, as long as all areas are of different type. +A [voltage level](#voltage-level) can belong to several areas, as long as all areas are of a different type. -The area boundaries define how interchange are to be calculated for the area. +The area boundaries define how interchange is to be calculated for the area. Area interchange is calculated by summing the active power flows across the area boundaries and can be obtained for AC part only (considering only AC boundaries), for DC part only (considering only DC boundaries) and in total (AC+DC). -Note that if the Area has no boundary explicitly defined, the interchange is considered 0 MW. +Note that if the Area has no boundary explicitly defined, the interchange is considered 0MW. -For area types that are meant to be used for area interchange control, e.g. in Load Flow simulations, the interchange target of the area can be specified as an input for the simulation. +For area types that are meant to be used for area interchange control, e.g., in Load Flow simulations, the interchange target of the area can be specified as an input for the simulation. All area interchange values use the load sign convention: positive values indicate that the area is importing, negative values that the area is exporting. @@ -153,7 +153,7 @@ which are then separated for AC and DC parts. ## Generator [![Javadoc](https://img.shields.io/badge/-javadoc-blue.svg)](https://javadoc.io/doc/com.powsybl/powsybl-core/latest/com/powsybl/iidm/network/Generator.html) -A generator is an equipment that injects or consumes active power, and injects or consumes reactive power. It may be used as a controller to hold a voltage or reactive target somewhere in the network, not necessarily directly where it is connected. In that specific case, the voltage or reactive power control is remote. +A generator is a piece of equipment that injects or consumes active power, and injects or consumes reactive power. It may be used as a controller to hold a voltage or reactive target somewhere in the network, not necessarily directly where it is connected. In that specific case, the voltage or reactive power control is remote. ![GeneratorSignConvention](img/generator-sign-convention.svg){width="50%" align=center class="only-light"} ![GeneratorSignConvention](img/dark_mode/generator-sign-convention.svg){width="50%" align=center class="only-dark"} @@ -176,7 +176,7 @@ A generator is an equipment that injects or consumes active power, and injects o **Specifications** -The values `MinP`, `MaxP` and `TargetP` are required. The minimum active power output can not be greater than the maximum active power output. `TargetP` must be inside this active power limits. `RatedS` specifies the nameplate apparent power rating for the unit, it is optional and should be a positive value if it is defined. The [reactive limits](./additional.md#reactive-limits) of the generator are optional, if they are not given the generator is considered with unlimited reactive power. Reactive limits can be given as a pair of [min/max values](./additional.md#min-max-reactive-limits) or as a [reactive capability curve](./additional.md#reactive-capability-curve). +The values `MinP`, `MaxP` and `TargetP` are required. The minimum active power output cannot be greater than the maximum active power output. `TargetP` must be inside this active power limits. `RatedS` specifies the nameplate apparent power rating for the unit, it is optional and should be a positive value if it is defined. The [reactive limits](./additional.md#reactive-limits) of the generator are optional, if they are not given the generator is considered with unlimited reactive power. Reactive limits can be given as a pair of [min/max values](./additional.md#min-max-reactive-limits) or as a [reactive capability curve](./additional.md#reactive-capability-curve). The `VoltageRegulatorOn` attribute is required. It voltage regulation is enabled, then `TargetV` and `RegulatingTerminal` must also be defined. If the voltage regulation is disabled, then `TargetQ` is required. `EnergySource` is optional, it can be: `HYDRO`, `NUCLEAR`, `WIND`, `THERMAL`, `SOLAR` or `OTHER`. @@ -204,10 +204,10 @@ A load is a passive equipment representing a delivery point that consumes or pro **Characteristics** -| Attribute | Unit | Description | -| --------- | ---- | ----------- | -| $P0$ | MW | The active power setpoint | -| $Q0$ | MVar | The reactive power setpoint | +| Attribute | Unit | Description | +|-----------|------|-----------------------------| +| $P0$ | MW | The active power setpoint | +| $Q0$ | MVar | The reactive power setpoint | **Specifications** @@ -254,16 +254,16 @@ In the grid model, loads comprise the following metadata: ## Battery [![Javadoc](https://img.shields.io/badge/-javadoc-blue.svg)](https://javadoc.io/doc/com.powsybl/powsybl-core/latest/com/powsybl/iidm/network/Battery.html) -A battery on the electric grid is an energy storage device that is either capable of capturing energy from the grid or of injecting it into the grid. The electric energy on the grid side is thus transformed into chemical energy on the battery side and vice versa. The power flow is bidirectional and it is controlled via a power electronic converter. +A battery on the electric grid is an energy storage device that is either capable of capturing energy from the grid or of injecting it into the grid. The electric energy on the grid side is thus transformed into chemical energy on the battery side and vice versa. The power flow is bidirectional, and it is controlled via a power electronic converter. **Characteristics** -| Attribute | Unit | Description | -| --------- | ---- | ----------- | -| $P0$ | MW | The Constant active power | -| $Q0$ | MVar | The Constant reactive power | -| $MinP$ | MW | The Minimal active power | -| $MaxP$ | MW | The Maximum active power | +| Attribute | Unit | Description | +|-----------|------|-----------------------------| +| $P0$ | MW | The Constant active power | +| $Q0$ | MVar | The Constant reactive power | +| $MinP$ | MW | The Minimal active power | +| $MaxP$ | MW | The Maximum active power | **Available extensions** @@ -278,12 +278,12 @@ A battery on the electric grid is an energy storage device that is either capabl ## Dangling line [![Javadoc](https://img.shields.io/badge/-javadoc-blue.svg)](https://javadoc.io/doc/com.powsybl/powsybl-core/latest/com/powsybl/iidm/network/DanglingLine.html) -A network may be connected to other networks for which a full description is not available or unwanted. In this case, a boundary line exists between the two networks. In the network of interest, that connection could be represented through a dangling line, which represents the part of that boundary line which is located in it. A dangling line is thus a passive or active component that aggregates a line chunk and a constant power injection, in passive-sign convention. The active and reactive power set points are fixed: the injection represents the power flow that would occur through the connection, were the other network fully described. +A network may be connected to other networks for which a full description is not available or unwanted. In this case, a boundary line exists between the two networks. In the network of interest, that connection could be represented through a dangling line, which represents the part of that boundary line which is located in it. A dangling line is thus a passive or active component that aggregates a line chunk and a constant power injection in passive-sign convention. The active and reactive power set points are fixed: the injection represents the power flow that would occur through the connection, were the other network fully described. ![Dangling line model](img/dangling-line.svg){width="50%" align=center class="only-light"} ![Dangling line model](img/dark_mode/dangling-line.svg){width="50%" align=center class="only-dark"} -A generation part, at boundary side can also be modeled, with a constant active power injection and a constant reactive power injection if the generation part of the dangling line is out of voltage regulation or a voltage target if the regulation is enabled. This fictitious generator can only regulate voltage locally: the regulating terminal can not be set, it is necessary the boundary side of the dangling line. Limits are modeled through $MinP$ and $MaxP$ for active power limits and through [reactive limits](./additional.md#reactive-limits). This generation part is optional. The generation part of the dangling line follows the classical generator sign convention. +A generation part, at boundary side can also be modeled with a constant active power injection and a constant reactive power injection if the generation part of the dangling line is out of voltage regulation or a voltage target if the regulation is enabled. This fictitious generator can only regulate voltage locally: the regulating terminal cannot be set, it is necessary for the boundary side of the dangling line. Limits are modeled through $MinP$ and $MaxP$ for active power limits and through [reactive limits](./additional.md#reactive-limits). This generation part is optional. The generation part of the dangling line follows the classical generator sign convention. Resulting flows at the dangling line terminal all follow the same passive-sign convention, either for the injection part or for the generation part. @@ -291,26 +291,26 @@ Dangling lines are key objects for merging networks. Merging will be described s **Characteristics** -| Attribute | Unit | Description | -| --------- | ---- | ----------- | -| $P0$ | MW | The active power setpoint | -| $Q0$ | MVar | The reactive power setpoint | -| $R$ | $\Omega$ | The series resistance | -| $X$ | $\Omega$ | The series reactance | -| $G$ | S | The shunt conductance | -| $B$ | S | The shunt susceptance | +| Attribute | Unit | Description | +|-----------|----------|-----------------------------| +| $P0$ | MW | The active power setpoint | +| $Q0$ | MVar | The reactive power setpoint | +| $R$ | $\Omega$ | The series resistance | +| $X$ | $\Omega$ | The series reactance | +| $G$ | S | The shunt conductance | +| $B$ | S | The shunt susceptance | Optional: -| Attribute | Unit | Description | -| --------- | ---- | ----------- | -| $MinP$ | MW | Minimum generation part active power output | -| $MaxP$ | MW | Maximum generation part active power output | -| $ReactiveLimits$ | MVar | Operational limits of the generation part (P/Q/V diagram) | -| $TargetP$ | MW | The active power target | -| $TargetQ$ | MVAr | The reactive power target | -| $TargetV$ | kV | The voltage target | -| $VoltageRegulatorOn$ | | True if the generation part regulates voltage | +| Attribute | Unit | Description | +|----------------------|------|-----------------------------------------------------------| +| $MinP$ | MW | Minimum generation part active power output | +| $MaxP$ | MW | Maximum generation part active power output | +| $ReactiveLimits$ | MVar | Operational limits of the generation part (P/Q/V diagram) | +| $TargetP$ | MW | The active power target | +| $TargetQ$ | MVAr | The reactive power target | +| $TargetV$ | kV | The voltage target | +| $VoltageRegulatorOn$ | | True if the generation part regulates voltage | **Specifications** @@ -318,10 +318,10 @@ Optional: - $R$, $X$, $G$ and $B$ correspond to a fraction of the original line and have to be consistent with the declared length of the dangling line. -In case the line is a boundary, a pairing key $pairingKey$ (in previous network versions $UcteXnodeCode$) is defined besides the characteristics of the table. It is a key to match two dangling lines and reconstruct the full boundary line, for both UCTE or CIM-CGMES formats. +In case the line is a boundary, a pairing key $pairingKey$ (in previous network versions $UcteXnodeCode$) is defined beside the characteristics of the table. It is a key to match two dangling lines and reconstruct the full boundary line for both UCTE or CIM-CGMES formats. A dangling line has a `Boundary` object that emulates a terminal located at boundary side. A dangling line is a connectable -with a single terminal located on network side, but sometimes we need state variables such as active or reactive powers on +with a single terminal located on the network side, but sometimes we need state variables such as active or reactive powers on the other side, voltage angle and voltage magnitude at fictitious boundary bus. Note that $P$, $Q$, $V$ and $Angle$ at boundary are automatically computed using information from the terminal of the dangling line. @@ -353,54 +353,54 @@ Shunt compensators follow a passive-sign convention: **Characteristics** -| Attribute | Unit | Description | -| --------- | ---- |------------ | -| $MaximumSectionCount$ | - | The maximum number of sections that may be switched on | -| $SectionCount$ | - | The current number of sections that are switched on | -| $B$ | S | The susceptance of the shunt compensator in its current state | -| $G$ | S | The conductance of the shunt compensator in its current state | -| $TargetV$ | kV | The voltage target | -| $TargetDeadband$ | kV | The deadband used to avoid excessive update of controls | -| $RegulatingTerminal$ | - | Associated node or bus for which voltage is to be regulated | -| $VoltageRegulatorOn$ | - | True if the shunt compensator regulates voltage | +| Attribute | Unit | Description | +|-----------------------|------|---------------------------------------------------------------| +| $MaximumSectionCount$ | - | The maximum number of sections that may be switched on | +| $SectionCount$ | - | The current number of sections that are switched on | +| $B$ | S | The susceptance of the shunt compensator in its current state | +| $G$ | S | The conductance of the shunt compensator in its current state | +| $TargetV$ | kV | The voltage target | +| $TargetDeadband$ | kV | The deadband used to avoid excessive update of controls | +| $RegulatingTerminal$ | - | Associated node or bus for which voltage is to be regulated | +| $VoltageRegulatorOn$ | - | True if the shunt compensator regulates voltage | - For Linear Shunt Compensators -| Attribute | Unit | Description | -| --------- | ---- |------------ | -| $bPerSection$ | S | The Positive sequence shunt (charging) susceptance per section | -| $gPerSection$ | S | The Positive sequence shunt (charging) conductance per section | +| Attribute | Unit | Description | +|---------------|------|----------------------------------------------------------------| +| $bPerSection$ | S | The Positive sequence shunt (charging) susceptance per section | +| $gPerSection$ | S | The Positive sequence shunt (charging) conductance per section | -We expect $bPerSection$ to be a non zero value. The disconnected status of the linear shunt compensator can be modeled by setting the $SectionCount$ attribute to zero. +We expect $bPerSection$ to be a non-zero value. The disconnected status of the linear shunt compensator can be modeled by setting the $SectionCount$ attribute to zero. -- For Non Linear Shunt Compensators +- For Non-Linear Shunt Compensators -| Attribute | Unit | Description | -| --------- |---------------------|------------ | +| Attribute | Unit | Description | +|------------|---------------------|-------------------------------------------------------| | $Sections$ | [Section](#section) | The Partition of all the shunt compensator's sections | ### Section -| Attribute | Unit | Description | -| --------- | ---- |------------ | -| $B$ | S | The accumulated positive sequence shunt (charging) susceptance of the section if this section and all the previous ones are activated | -| $G$ | S | The accumulated positive sequence shunt (charging) conductance of the section if this section and all the previous ones are activated | +| Attribute | Unit | Description | +|-----------|------|---------------------------------------------------------------------------------------------------------------------------------------| +| $B$ | S | The accumulated positive sequence shunt (charging) susceptance of the section if this section and all the previous ones are activated | +| $G$ | S | The accumulated positive sequence shunt (charging) conductance of the section if this section and all the previous ones are activated | -$B$ and $G$ attributes can be equal zero, but the disconnected status of the non linear shunt compensator can be modeled by setting the $SectionCount$ attribute to zero. The section which $SectionCount$ equal to $1$ is the first effective section, and it would be more efficient to affect it a non zero susceptance. +$B$ and $G$ attributes can be equal zero, but the disconnected status of the non-linear shunt compensator can be modeled by setting the $SectionCount$ attribute to zero. The section which $SectionCount$ equal to $1$ is the first effective section, and it would be more efficient to affect it a non-zero susceptance. **Specifications** - A section of a shunt compensator is an individual capacitor or reactor. - A value of bPerSection positive means it is modeling a capacitor, an equipment that injects reactive + A positive value of bPerSection means that it models a capacitor, a device that injects reactive power into the bus. - A value of bPerSection negative means a reactor, an equipment that can absorb excess reactive power + A negative value of bPerSection means a reactor, a device that can absorb excess reactive power from the network. - The current section count is expected to be greater than one and lesser or equal to the maximum section count. - Regulation for shunt compensators does not necessarily model automation, it can represent human actions on the network - e.g. an operator activating or deactivating a shunt compensator). However, it can of course be integrated on a power flow + e.g. an operator activating or deactivating a shunt compensator). However, it can be integrated on a power flow calculation or not, depending on what is wanted to be shown. -- In case of a capacitor, the value for its Q will be negative. -- In case of a reactor, the value for its Q will be positive. +- In the case of a capacitor, the value for its Q will be negative. +- In the case of a reactor, the value for its Q will be positive. **Available extensions** @@ -421,22 +421,22 @@ Static VAR compensators follow a passive-sign convention: **Characteristics** -| Attribute | Unit | Description | -| --------- | ---- | ----------- | -| $Bmin$ | S | The minimum susceptance | -| $Bmax$ | S | The maximum susceptance | -| $VoltageSetpoint$ | kV | The voltage setpoint | +| Attribute | Unit | Description | +|-------------------------|------|-----------------------------| +| $Bmin$ | S | The minimum susceptance | +| $Bmax$ | S | The maximum susceptance | +| $VoltageSetpoint$ | kV | The voltage setpoint | | $ReactivePowerSetpoint$ | MVar | The reactive power setpoint | **Specifications** -- $Bmin$ and $Bmax$ are the susceptance bounds of the static VAR compensator. Reactive power output of a static VAR compensator is limited by the maximum and the minimum susceptance values. The min/max reactive power of a static VAR compensator are determined by: +- $Bmin$ and $Bmax$ are the susceptance bounds of the static VAR compensator. Reactive power output of a static VAR compensator is limited by the maximum and the minimum susceptance values. The min/max reactive power of a static VAR compensator is determined by: $$Qmin = -Bmin \times V^2$$ $$Qmax = -Bmax \times V^2$$ - where $V$ is the voltage of the bus that connects the static VAR compensator to the network. Even if the regulating terminal is remote, only the local voltage has to be considered to retrive the minimum and the maximum amouts of reactive power. Reactive limits can be handled in an approximative way using the nominal voltage of the connected bus. + where $V$ is the voltage of the bus that connects the static VAR compensator to the network. Even if the regulating terminal is remote, only the local voltage has to be considered to retrieve the minimum and the maximum amount of reactive power. Reactive limits can be handled in an approximate way using the nominal voltage of the connected bus. - The voltage setpoint is required when the regulation mode is set to `VOLTAGE`. - The reactive power setpoint is required when the regulation mode is set to `REACTIVE_POWER`. @@ -447,7 +447,7 @@ In IIDM the static VAR compensator also comprises some metadata: - `VOLTAGE` - `REACTIVE_POWER` - `OFF` - Note that it is different from the generators' regulation definition, which is only done through a boolean. `OFF` is equivalent to a disconnected equipment. + Note that it is different from the generator regulation definition, which is only done through a boolean. `OFF` is equivalent to a disconnected element. - The regulating terminal, which can be local or remote: it is the specific connection point on the network where the setpoint is measured. **Available extensions** @@ -480,7 +480,7 @@ y_2 & = & g_2 +j. b_2 \end{align*} $$ -The equations of the line, in complex notations, are as follow: +The equations of the line, in complex notations, are as follows: $$ \begin{align*} @@ -499,14 +499,14 @@ $$ **Characteristics** -| Attribute | Unit | Description | -| --------- | ---- | ----------- | -| $R$ | $\Omega$ | The series resistance | -| $X$ | $\Omega$ | The series reactance | -| $G1$ | S | The first side shunt conductance | -| $B1$ | S | The first side shunt susceptance | -| $G2$ | S | The second side shunt conductance | -| $B2$ | S | The second side shunt susceptance | +| Attribute | Unit | Description | +|-----------|----------|-----------------------------------| +| $R$ | $\Omega$ | The series resistance | +| $X$ | $\Omega$ | The series reactance | +| $G1$ | S | The first side shunt conductance | +| $B1$ | S | The first side shunt susceptance | +| $G2$ | S | The second side shunt conductance | +| $B2$ | S | The second side shunt susceptance | **Metadata** @@ -534,30 +534,30 @@ $G2$ (resp. $B2$) is equal to the second dangling line's $G2$ (resp. $B2$). **Characteristics** -| Attribute | Unit | Description | -| --------- | ---- | ----------- | -| $R$ | $\Omega$ | The series resistance | -| $X$ | $\Omega$ | The series reactance | -| $G1$ | S | The first side shunt conductance | -| $B1$ | S | The first side shunt susceptance | -| $G2$ | S | The second side shunt conductance | -| $B2$ | S | The second side shunt susceptance | +| Attribute | Unit | Description | +|-----------|----------|-----------------------------------| +| $R$ | $\Omega$ | The series resistance | +| $X$ | $\Omega$ | The series reactance | +| $G1$ | S | The first side shunt conductance | +| $B1$ | S | The first side shunt susceptance | +| $G2$ | S | The second side shunt conductance | +| $B2$ | S | The second side shunt susceptance | A tie line is not a connectable. It is just a container of two underlying dangling lines with the same pairing key. When connected together, each dangling line `P0` and `Q0` (and generation part if present) is ignored: only global tie line characteristics are used to compute flow. Removing a tie line leads to two free dangling lines, with an optional update of `P0` and `Q0` to match the flows in the global network context. ## Transformers -(two-windings-transformer)= -### Two windings transformer +(two-winding-transformer)= +### Two-winding transformer [![Javadoc](https://img.shields.io/badge/-javadoc-blue.svg)](https://javadoc.io/doc/com.powsybl/powsybl-core/latest/com/powsybl/iidm/network/TwoWindingsTransformer.html) -A two windings power transformer is connected to two voltage levels (side 1 and side 2) that belong to a same substation. -Two windings transformers are modeled with the following equivalent $\Pi$ model: +A two-winding power transformer is connected to two voltage levels (side 1 and side 2) that belong to the same substation. +Two winding transformers are modeled with the following equivalent $\Pi$ model: ![Power line model](img/two-winding-transformer-model.svg){width="50%" align=center class="only-light"} ![Power line model](img/dark_mode/two-winding-transformer-model.svg){width="50%" align=center class="only-dark"} -With the series impedance $z$ and the shunt admittance $y$ and the voltage ratio $\rho$ and the angle difference $\alpha$ and potentially parameters from the current step of a [ratio tap changer](./additional.md#ratio-tap-changer) and/or a [phase tap changer](./additional.md#phase-tap-changer), we have: +With the series impedance $z$ and the shunt admittance $y$ and the voltage ratio $\rho$ and the angle difference $\alpha$ and potential parameters from the current step of a [ratio tap changer](./additional.md#ratio-tap-changer) and/or a [phase tap changer](./additional.md#phase-tap-changer), we have: $$ \begin{array}{lcl} @@ -574,7 +574,7 @@ I_{0} & = & \dfrac{I_{1}}{\rho e^{-j\alpha}}\\ \end{array} $$ -Using the above notation, the equations of the two windings transformer, in complex notations, are as follow: +Using the above notation, the equations of the two-winding transformers, in complex notations, are as follows: $$ \left(\begin{array}{c} @@ -591,20 +591,20 @@ $$ **Characteristics** -| Attribute | Unit | Description | -| --------- | ---- | ----------- | -| $R_{nom}$ | $\Omega$ | The nominal series resistance at the side 2 of the transformer | -| $X_{nom}$ | $\Omega$ | The nominal series reactance at the side 2 of the transformer | -| $G_{nom}$ | S | The nominal magnetizing conductance at the side 2 of the transformer | -| $B_{nom}$ | S | The nominal magnetizing susceptance at the side 2 of the transformer | -| $V_{1\ nom}$ | kV | The rated voltage at side 1 | -| $V_{2\ nom}$ | kV | The rated voltage at side 2 | -| $RatedS$ | MVA | The normal apparent power | +| Attribute | Unit | Description | +|--------------|----------|----------------------------------------------------------------------| +| $R_{nom}$ | $\Omega$ | The nominal series resistance at the side 2 of the transformer | +| $X_{nom}$ | $\Omega$ | The nominal series reactance at the side 2 of the transformer | +| $G_{nom}$ | S | The nominal magnetizing conductance at the side 2 of the transformer | +| $B_{nom}$ | S | The nominal magnetizing susceptance at the side 2 of the transformer | +| $V_{1\ nom}$ | kV | The rated voltage at side 1 | +| $V_{2\ nom}$ | kV | The rated voltage at side 2 | +| $RatedS$ | MVA | The normal apparent power | **Specifications** -- A [ratio tap changer](./additional.md#ratio-tap-changer) and/or a [phase tap changer](./additional.md#phase-tap-changer) can be associated with a two windings power transformer. -- For a two windings transformer, the normal apparent power shall be identical at both sides 1 and 2. +- A [ratio tap changer](./additional.md#ratio-tap-changer) and/or a [phase tap changer](./additional.md#phase-tap-changer) can be associated with a two-winding power transformer. +- For a two-winding transformer, the normal apparent power shall be identical at both sides 1 and 2. **Available extensions** @@ -617,17 +617,17 @@ $$ - [Two-windings Transformer Phase Angle Clock](extensions.md#two-windings-transformer-phase-angle-clock) - [Two-windings Transformer To Be Estimated](extensions.md#two-windings-transformer-to-be-estimated) -(three-windings-transformer)= -### Three windings transformer +(three-winding-transformer)= +### Three-winding transformer [![Javadoc](https://img.shields.io/badge/-javadoc-blue.svg)](https://javadoc.io/doc/com.powsybl/powsybl-core/latest/com/powsybl/iidm/network/ThreeWindingsTransformer.html) -A three windings power transformer is connected to three voltage levels (side 1, side 2 and side 3) that belong to the +A three-winding power transformer is connected to three voltage levels (side 1, side 2 and side 3) that belong to the same substation. We usually have: - Side 1 as the primary side (side with the highest rated voltage) - Side 2 as the secondary side (side with the medium rated voltage) - Side 3 as the tertiary side (side with the lowest rated voltage) -A three windings transformer is modeled with three legs, where every leg model is electrically equivalent to a two windings transformer. +A three-winding transformer is modeled with three legs, where every leg model is electrically equivalent to a two-winding transformer. For each leg, the network bus is at side 1 and the star bus is at side 2. ![Line model](img/three-winding-transformer-model.svg){width="50%" align=center class="only-light"} @@ -641,7 +641,7 @@ For each leg, the network bus is at side 1 and the star bus is at side 2. **Specifications** -- A [ratio tap changer](./additional.md#ratio-tap-changer) and/or a [phase tap changer](./additional.md#phase-tap-changer) can be associated to all three sides of a three windings power transformer. +- A [ratio tap changer](./additional.md#ratio-tap-changer) and/or a [phase tap changer](./additional.md#phase-tap-changer) can be associated to all three sides of a three-winding power transformer. Only one tap changer (either ratio or phase tap changer) is allowed to be regulating on the equipment at a given time. **Available extensions** @@ -654,18 +654,18 @@ For each leg, the network bus is at side 1 and the star bus is at side 2. - [Three-windings Transformer Phase Angle Clock](extensions.md#three-windings-transformer-phase-angle-clock) - [Three-windings Transformer To Be Estimated](extensions.md#three-windings-transformer-to-be-estimated) -#### Three windings transformer leg +#### Three-winding transformer leg **Characteristics** -| Attribute | Unit | Description | -| --------- | ---- | ----------- | -| $R$ | $\Omega$ | The nominal series resistance specified at the voltage of the leg | -| $X$ | $\Omega$ | The nominal series reactance specified at the voltage of the leg | -| $G$ | S | The nominal magnetizing conductance specified at the voltage of the leg | -| $B$ | S | The nominal magnetizing susceptance specified at the voltage of the leg | -| $RatedU$ | kV | The rated voltage | -| $RatedS$ | MVA | The normal apparent power | +| Attribute | Unit | Description | +|-----------|----------|-------------------------------------------------------------------------| +| $R$ | $\Omega$ | The nominal series resistance specified at the voltage of the leg | +| $X$ | $\Omega$ | The nominal series reactance specified at the voltage of the leg | +| $G$ | S | The nominal magnetizing conductance specified at the voltage of the leg | +| $B$ | S | The nominal magnetizing susceptance specified at the voltage of the leg | +| $RatedU$ | kV | The rated voltage | +| $RatedS$ | MVA | The normal apparent power | **Specifications** @@ -679,16 +679,16 @@ An HVDC line is connected to the DC side of two HVDC converter stations, either **Characteristics** -| Attribute | Unit | Description | -| --------- | ---- | ----------- | -| $R$ | $\Omega$ | The resistance of the HVDC line | -| $NominalV$ | kV | The nominal voltage | -| $ActivePowerSetpoint$ | MW | The active power setpoint | -| $MaxP$ | MW | The maximum active power | +| Attribute | Unit | Description | +|-----------------------|----------|---------------------------------| +| $R$ | $\Omega$ | The resistance of the HVDC line | +| $NominalV$ | kV | The nominal voltage | +| $ActivePowerSetpoint$ | MW | The active power setpoint | +| $MaxP$ | MW | The maximum active power | **Specifications** -- The HVDC line operation depends on a converters mode, which indicates the flow direction. In the specification it is thus mandatory to define `ConvertersMode`, which can be: +- The HVDC line operation depends on a converter mode, which indicates the flow direction. In the specification it is thus mandatory to define `ConvertersMode`, which can be: - `SIDE_1_RECTIFIER_SIDE_2_INVERTER`: the flow goes from side 1 to side 2 - `SIDE_1_INVERTER_SIDE_2_RECTIFIER`: the flow goes from side 2 to side 1 @@ -709,16 +709,16 @@ Electronic converters for HVDC are divided into two main categories: line-commut **Characteristics** -| Attribute | Type | Unit | Required | Default value | Description | -| --------- | ---- | ---- | -------- | ------------- | ----------- | -| HvdcType | `HvdcType` | - | yes | - | The HVDC type | -| LossFactor | float | % | yes | - | The loss factor | +| Attribute | Type | Unit | Required | Default value | Description | +|------------|------------|------|----------|---------------|-----------------| +| HvdcType | `HvdcType` | - | yes | - | The HVDC type | +| LossFactor | float | % | yes | - | The loss factor | The LossFactor should be greater than 0. **Specifications** -The HVDC type, `LCC` or `VSC`, determines if the Converter Station is a LCC Converter Station or a VSC Converter Station. +The HVDC type, `LCC` or `VSC`, determines if the Converter Station is an LCC Converter Station or a VSC Converter Station. The positive loss factor `LossFactor` is used to model the losses during the conversion. In case of: - A rectifier operation (conversion from AC to DC), we have @@ -745,9 +745,9 @@ An LCC converter station is made with electronic switches that can only be turne **Characteristics** -| Attribute | Unit | Description | -| --------- | ---- | ----------- | -| $PowerFactor$ | % | Ratio between the active power $P$ and the apparent power $S$. | +| Attribute | Unit | Description | +|---------------|------|----------------------------------------------------------------| +| $PowerFactor$ | % | Ratio between the active power $P$ and the apparent power $S$. | **Available extensions** @@ -763,23 +763,23 @@ A VSC converter station is made with switching devices that can be turned both o - Current direction changes to change the power direction - Store energy capacitively - Use semiconductors which can turn on or off by control action -- Turn-off is independant of external circuit +- Turn-off is independent of external circuit **Characteristics** -| Attribute | Unit | Description | -| --------- | ---- | ----------- | -| $VoltageSetpoint$ | kV | The voltage setpoint for regulation | +| Attribute | Unit | Description | +|-------------------------|------|--------------------------------------------| +| $VoltageSetpoint$ | kV | The voltage setpoint for regulation | | $ReactivePowerSetpoint$ | MVar | The reactive power setpoint for regulation | **Specifications** - The voltage setpoint (in kV) is required if the voltage regulator is on for the VSC station. - The reactive power setpoint (in MVar) is required if the voltage regulator is off for the VSC station. A positive value of $ReactivePowerSetpoint$ means an injection into the bus, thus a negative value at the corresponding terminal (which is in passive-sign convention). -- A set of reactive limits can be associated to a VSC converter station. All the reactive limits modelings available in the library are described [here](./additional.md#reactive-limits). +- A set of reactive limits can be associated to a VSC converter station. All the reactive limits modeling available in the library are described [here](./additional.md#reactive-limits). **Metadata** -- The participation to regulation (through a boolean) +- The participation in regulation (through a boolean) **Available extensions** diff --git a/docs/index.md b/docs/index.md index 82cbef6adea..99e78d718d6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,7 +2,7 @@ # PowSyBl Core PowSyBl (Power System Blocks) is an open source library written in Java, -dedicated to electrical grid modelling, simulation and visualisation, licensed under the [Mozilla Public License version 2.0](https://www.mozilla.org/en-US/MPL/2.0/). +dedicated to electrical grid modeling, simulation and visualisation, licensed under the [Mozilla Public License version 2.0](https://www.mozilla.org/en-US/MPL/2.0/). It is part of [LF Energy](https://www.lfenergy.org/), an open source foundation focused on energy sector, hosted within The Linux Foundation. PowSyBl is used through Python scripts using the library [Pypowsybl](https://powsybl.readthedocs.io/projects/pypowsybl/en/stable/), but also diff --git a/docs/simulation/dynamic/configuration.md b/docs/simulation/dynamic/configuration.md index 8b63b29d849..1e2b522e8d9 100644 --- a/docs/simulation/dynamic/configuration.md +++ b/docs/simulation/dynamic/configuration.md @@ -1,7 +1,7 @@ # Configuration ## Implementation -If you have several implementation in your classpath, you need to choose which implementation to use in your configuration file with the `default-impl-name` property. +If you have several implementations in your classpath, you need to choose which implementation to use in your configuration file with the `default-impl-name` property. Each implementation is identified by its name, that may be unique in the classpath: - use "DynaWaltz" to use powsybl-dynawo implementation diff --git a/docs/simulation/dynamic/index.md b/docs/simulation/dynamic/index.md index 61a4d237caa..465c4bbcf96 100644 --- a/docs/simulation/dynamic/index.md +++ b/docs/simulation/dynamic/index.md @@ -43,9 +43,9 @@ For the moment, the only way to monitor dynamic variables of the simulation in o The outputs of a dynamic simulation are: - the updated static network (which may have been topologically modified depending on the events or automatons defined as inputs) - the different results of the dynamic simulation: - - some curves, asked for by the user to track the evolution of specific variables throughout the simulation + - some curves asked for by the user to track the evolution of specific variables throughout the simulation - some aggregated data regarding constraints, like a security analysis output - - timelines, that contain the list of events that occurred during the dynamic simulation, be them planned beforehand through events, or not + - timelines that contain the list of events that occurred during the dynamic simulation, be them planned beforehand through events, or not - logs about the execution of the dynamic simulator ## Implementations diff --git a/docs/simulation/dynamic_security/configuration.md b/docs/simulation/dynamic_security/configuration.md index 494a99c2748..df40b7077bc 100644 --- a/docs/simulation/dynamic_security/configuration.md +++ b/docs/simulation/dynamic_security/configuration.md @@ -1,7 +1,7 @@ # Configuration ## Implementation -If you have several implementation in your classpath, you need to choose which implementation to use in your configuration file with the `default-impl-name` property. +If you have several implementations in your classpath, you need to choose which implementation to use in your configuration file with the `default-impl-name` property. Each implementation is identified by its name, that may be unique in the classpath: - use "DynaWaltz" to use powsybl-dynawo implementation @@ -20,7 +20,7 @@ dynamic-security-analysis: ## Parameters The `dynamic-security-analysis-default-parameters` module is used every time a dynamic security analysis is run. It defines the default values for the most common parameters a `com.powsybl.security.dynamic.DynamicSecurityAnalysis` implementation should be able to handle. -In addition to its own set of parameter, the dynamic security analysis reuse [dynamic simulation parameters](../dynamic/parameters.md). +In addition to its own set of parameters, the dynamic security analysis reuses [dynamic simulation parameters](../dynamic/parameters.md). You may configure some generic parameters for all implementations: ```yaml diff --git a/docs/simulation/dynamic_security/index.md b/docs/simulation/dynamic_security/index.md index c2c1bb8151d..3db2a273947 100644 --- a/docs/simulation/dynamic_security/index.md +++ b/docs/simulation/dynamic_security/index.md @@ -5,15 +5,15 @@ configuration.md ``` -The dynamic security analysis is a [security analysis](../security/index.md) using dynamic models associated with static equipments of the network. +The dynamic security analysis is a [security analysis](../security/index.md) using dynamic models associated with static equipment of the network. ## Inputs ### Dynamic models mapping The dynamic models mapping is exactly the same [mapping](../dynamic/index.md#dynamic-models-mapping) used for a dynamic simulation. -### Others inputs -Beside dynamic models mapping, the dynamic security analysis requires the same [inputs as the standard one](../security/index.md#inputs). +### Other inputs +Besides dynamic models mapping, the dynamic security analysis requires the same [inputs as the standard one](../security/index.md#inputs). ## Outputs The dynamic security analysis produces the same outputs as the standard one. All outputs can be found [here](../security/index.md#outputs). diff --git a/docs/simulation/loadflow/configuration.md b/docs/simulation/loadflow/configuration.md index 97ac8f2cf96..43558efe00d 100644 --- a/docs/simulation/loadflow/configuration.md +++ b/docs/simulation/loadflow/configuration.md @@ -117,16 +117,16 @@ The `shuntCompensatorVoltageControlOn` property is an optional property that def The default value is `false`. **connectedComponentMode** -The `connectedComponentMode` property is an optional property that defines if the power flow has to be computed over all connected component (choose `ALL` mode) or just on the main connected component (choose `MAIN` mode). +The `connectedComponentMode` property is an optional property that defines if the power flow has to be computed over all connected components (choose `ALL` mode) or just on the main connected component (choose `MAIN` mode). The default value of this parameter is `MAIN`. **twtSplitShuntAdmittance** -The `twtSplitShuntAdmittance` property is an optional property that defines whether the shunt admittance is split at each side of the serie impedance for transformers. +The `twtSplitShuntAdmittance` property is an optional property that defines whether the shunt admittance is split at each side of the series impedance for transformers. The default value is `false`. **dcUseTransformerRatio** -The `dcUseTransformerRatio` property is an optional property that defines if ratio of transformers should be used in the -flow equations in a DC power flow. +The `dcUseTransformerRatio` property is an optional property that defines if the ratio of transformers should be used in +the flow equations in a DC power flow. The default value of this parameter is `true`. **dcPowerFactor** @@ -134,6 +134,6 @@ The `dcPowerFactor` property is an optional property that defines the power fact The default value is `1.0`. ### Specific parameters -Some implementation use specific parameters that can be defined in the configuration file or in the JSON parameters file: +Some implementations use specific parameters that can be defined in the configuration file or in the JSON parameters file: - [PowSyBl OpenLoadFlow](TODO) - [DynaFlow](TODO) \ No newline at end of file diff --git a/docs/simulation/loadflow/index.md b/docs/simulation/loadflow/index.md index 5f0d49c2995..eab082913b3 100644 --- a/docs/simulation/loadflow/index.md +++ b/docs/simulation/loadflow/index.md @@ -11,8 +11,8 @@ configuration.md A load flow is a numerical analysis of the flow of electric power in an interconnected system, where that system is considered to be in normal steady-state operation. Load flow studies are important for planning future expansion of power systems as well as in determining the best operation of existing systems. The principal outputs obtained from -the load flow study is the magnitude and phase angle of the voltage at each bus, and the active and reactive power -flowing in each line, the current is computed from both of them. In this page we will go into some details about what +the load flow study are the magnitude and phase angle of the voltage at each bus, and the active and reactive power +flowing in each line; the current is computed from both of them. In this page we will go into some details about what are the inputs and outputs of a load flow simulation, what is expected from a load flow result, how the load flow validation feature works, what load flow implementations are compatible with the generic interface, and how to configure it for the different implementations. @@ -35,7 +35,7 @@ only some of them (`Partially Converged` status), or for none of them (`Failed` not relevant for a specific implementation), the selected reference bus (voltage angle reference), the selected slack buses (the buses at which the power balance has been done), active power mismatch at slack buses, and amount of distributed active power (zero MW if slack distribution is disabled). -- Metrics regarding the computation. Depending on the load flow implementation the content of these metrics may vary. +- Metrics regarding the computation. Depending on the load flow implementation, the content of these metrics may vary. - Logs in a simulator specific format. ## Implementations diff --git a/docs/simulation/security/action-dsl.md b/docs/simulation/security/action-dsl.md index 49202a6831c..215a24cd1d7 100644 --- a/docs/simulation/security/action-dsl.md +++ b/docs/simulation/security/action-dsl.md @@ -1,14 +1,14 @@ # Action DSL -The action DSL is a domain specific language written in groovy for the creation of a strategy to solve violations, used in [security analyses with remedial actions](index.md#operator-strategies). This strategy is constituted of a set of [contingencies](contingency-dsl.md), a set of modification on the network called **actions**, and a set of rules to determine in which circumstances to apply the actions. +The action DSL is a domain-specific language written in groovy for the creation of a strategy to solve violations, used in [security analyses with remedial actions](index.md#operator-strategies). This strategy is constituted of a set of [contingencies](contingency-dsl.md), a set of modification on the network called **actions**, and a set of rules to determine in which circumstances to apply the actions. ## Contingencies -The contingencies are defined in the same way that is described in the [contingency DSL](contingency-dsl.md). Are supported: -- N-1 contingencies that triggers a single equipment at a time +The contingencies are defined in the same way described in the [contingency DSL](contingency-dsl.md). Are supported: +- N-1 contingencies that trigger a single piece of equipment at a time - N-K contingencies that triggers multiple equipments at a time -- busbar contingencies that triggers a [busbar section](../../grid_model/network_subnetwork.md#busbar-section), a N-K contingency that triggers all the equipments connected to that busbar section. +- busbar contingencies that trigger a [busbar section](../../grid_model/network_subnetwork.md#busbar-section), a N-K contingency that triggers all the equipment connected to that busbar section. ## Actions -The actions are modifications that could be made on the network to solve a security issue. It could be topology modification like opening or closing a switch, setpoints modification, tap position modification. PowSyBl provides a set of predefined actions, but this possibilities are infinite as you can create custom actions or groovy scripts. +The actions are modifications that could be made on the network to solve a security issue. It could be topology modification like opening or closing a switch, setpoint modification, tap position modification. PowSyBl provides a set of predefined actions, but this possibility is infinite as you can create custom actions or groovy scripts. An action is constituted of: - a unique identifier to reference this action in the [rules](#rules) @@ -26,7 +26,7 @@ action('actionID') { ``` ### Opening / Closing a switch -Topology changes are usually used to reduce the intensity on a AC branch. The following snippet shows how to create an action that opens the switch `SW1` and another one to close it. +Topology changes are usually used to reduce the intensity on an AC branch. The following snippet shows how to create an action that opens the switch `SW1` and another one to close it. ```groovy action('open-switch-SW1') { description "Open switch SW1" @@ -43,7 +43,7 @@ action('close-switch-SW1') { } ``` -Note that it's possible to open or close several switch at a time: +Note that it's possible to open or close several switches at a time: ```groovy action('open-SW1-and-SW2') { tasks { @@ -169,7 +169,7 @@ load-flow-based-phase-shifter-optimizer: ``` ### Scripting -The `script` task allow you to execute groovy code to modify the network. You can access to the network and the computation manager, using the `network` and `computationManager` variables. With this task, possibilities are unlimited as you have a complete access to the IIDM API. +The `script` task allow you to execute groovy code to modify the network. You can access to the network and the computation manager, using the `network` and `computationManager` variables. With this task, possibilities are unlimited as you have complete access to the IIDM API. ```groovy action('custom-action') { description "Disconnect LOAD1 and LOAD2, open the coupler COUPLER and change the setpoints of LOAD3" @@ -191,7 +191,7 @@ The rules are the most important in this DSL: they define the activation criteri - a unique identifier - an optional description to explain the purpose of the rule - an activation criteria -- a list of actions to applied if the activation criteria is verified +- a list of actions to be applied if the activation criteria is verified - an optional life count to limit the number of times a rule can be verified and its actions applied ### Activation criteria @@ -205,13 +205,13 @@ rule('rule-ID') { } ``` -**Note:** The activation criteria is evaluated during the simulation. If you want to save the initial value of a network's variable, you should declare a global variable at the beginning of your script. +**Note:** The activation criteria are evaluated during the simulation. If you want to save the initial value of a network's variable, you should declare a global variable at the beginning of your script. #### Network binding -The network binding adds keywords in the DSL to get equipments by their IDs. At the moment, the following keywords are supported: +The network binding adds keywords in the DSL to get equipment by their IDs. At the moment, the following keywords are supported: - `line`: to retrieve a [line](../../grid_model/network_subnetwork.md#line) -- `transformer`: to retrieve a [two windings transformer](../../grid_model/network_subnetwork.md#two-windings-transformer) -- `branch`: to retrieve a [line](../../grid_model/network_subnetwork.md#line), a [tie line](../../grid_model/network_subnetwork.md#tie-line) or a [two windings transformer](../../grid_model/network_subnetwork.md#two-windings-transformer) +- `transformer`: to retrieve a [two-winding transformer](../../grid_model/network_subnetwork.md#two-winding-transformer) +- `branch`: to retrieve a [line](../../grid_model/network_subnetwork.md#line), a [tie line](../../grid_model/network_subnetwork.md#tie-line) or a [two-winding transformer](../../grid_model/network_subnetwork.md#two-winding-transformer) - `generator`: to retrieve a [generator](../../grid_model/network_subnetwork.md#generator) - `load`: to retrieve a [load](../../grid_model/network_subnetwork.md#load) - `_switch` and `switch_` to retrieve a [switch](../../grid_model/network_subnetwork.md#breakerswitch) @@ -222,7 +222,7 @@ The network binding adds keywords in the DSL to get equipments by their IDs. At #### Predefined functions The following predefined functions are available and can be used in the `when` statement: -- `actionTaken`: returns `true` if the given action has already be applied +- `actionTaken`: returns `true` if the given action has already been applied - `contingencyOccured`: returns `true` if a contingency is currently simulated, and `false` if the N state is simulated - `loadingRank`: returns the rank of a given branch among a list of branches regarding their overload level - `mostLoaded`: returns the ID of the most loaded branch among a list of branches @@ -274,7 +274,7 @@ action('change-tap-position') { rule('example3') { description "If LINE1 and LINE2 are overloaded then change the PST tap position" when allOverloaded(["LINE1", "LINE2"]) - apply 'change-tap-postition' + apply 'change-tap-position' } ``` diff --git a/docs/simulation/security/configuration.md b/docs/simulation/security/configuration.md index 1ca9a5bf677..9b9ae14f546 100644 --- a/docs/simulation/security/configuration.md +++ b/docs/simulation/security/configuration.md @@ -8,13 +8,13 @@ The user can provide parameters to define which violations must be raised after a contingency, if the violation was already present in the pre-contingency state (`IncreasedViolationsParameters`). **flow-proportional-threshold** -After a contingency, only flow violations (either current, active power or apparent power violations) that have increased in proportion by more than a threshold value compared to the pre-contingency state are listed in the limit violations. The other ones are filtered. The threshold value is unitless and should be positive. This method gets the flow violation proportional threshold. The default value is 0.1, meaning that only violations that have increased by more than 10% appear in the limit violations. +After a contingency, only flow violations (either current, active power or apparent power violations) that have increased in proportion by more than a threshold value, compared to the pre-contingency state, are listed in the limit violations. The other ones are filtered. The threshold value is unitless and should be positive. This method gets the flow violation proportional threshold. The default value is 0.1, meaning that only violations that have increased by more than 10% appear in the limit violations. **low-voltage-proportional-threshold** -After a contingency, only low-voltage violations that have increased by more than the proportional threshold compared to the pre-contingency state, are listed in the limit violations, the other ones are filtered. This method gets the low voltage violation proportional threshold (unitless, should be positive). The default value is 0.0, meaning that only violations that have increased by more than 0.0 % appear in the limit violations (note that for low-voltage violation, it means that the voltage in the post-contingency state is lower than the voltage in the pre-contingency state). +After a contingency, only low-voltage violations that have increased by more than the proportional threshold compared to the pre-contingency state, are listed in the limit violations, the other ones are filtered. This method gets the low-voltage violation proportional threshold (unitless, should be positive). The default value is 0.0, meaning that only violations that have increased by more than 0.0 % appear in the limit violations (note that for low-voltage violation, it means that the voltage in the post-contingency state is lower than the voltage in the pre-contingency state). **low-voltage-absolute-threshold** -After a contingency, only low-voltage violations that have increased by more than an absolute threshold compared to the pre-contingency state, are listed in the limit violations, the other ones are filtered. This method gets the low voltage violation absolute threshold (in kV, should be positive). The default value is 0.0, meaning that only violations that have increased by more than 0.0 kV appear in the limit violations (note that for low-voltage violation, it means that the voltage in the post-contingency state is lower than the voltage in the pre-contingency state). +After a contingency, only low-voltage violations that have increased by more than an absolute threshold compared to the pre-contingency state, are listed in the limit violations, the other ones are filtered. This method gets the low-voltage violation absolute threshold (in kV, should be positive). The default value is 0.0, meaning that only violations that have increased by more than 0.0 kV appear in the limit violations (note that for low-voltage violation, it means that the voltage in the post-contingency state is lower than the voltage in the pre-contingency state). **high-voltage-proportional-threshold** Same as before but for high-voltage violations. @@ -24,10 +24,10 @@ Same as before but for high-voltage violations. (violation-filtering)= ### Violations filtering -The violations listed in the results can be filtered to consider only certain type of violations, to consider only few voltage levels or to limit the geographical area by filtering equipments by countries. Check out the documentation of the [limit-violation-default-filter](../../user/configuration/limit-violation-default-filter.md) configuration module. +The violations listed in the results can be filtered to consider only a certain type of violations, to consider only a few voltage levels or to limit the geographical area by filtering equipment by countries. Check out the documentation of the [limit-violation-default-filter](../../user/configuration/limit-violation-default-filter.md) configuration module. **Example** -Using the following configuration, the results will contain only voltage violations for equipments in France or Belgium: +Using the following configuration, the results will contain only voltage violations for equipment in France or Belgium: ```yaml limit-violation-default-filter: countries: diff --git a/docs/simulation/security/contingency-dsl.md b/docs/simulation/security/contingency-dsl.md index 3f301c37725..542c67464f0 100644 --- a/docs/simulation/security/contingency-dsl.md +++ b/docs/simulation/security/contingency-dsl.md @@ -1,14 +1,14 @@ # Contingency DSL -The contingency DSL is a domain specific language written in groovy for the creation of a contingency list, used in [security analyses](./index.md) or [sensitivity analyses](../sensitivity/index). At the moment, it's possible to simulate the loss of a generator, a static VAR compensator, a shunt, a power line, a power transformer, a HVDC line or a busbar section. +The contingency DSL is a domain specific language written in groovy for the creation of a contingency list, used in [security analyses](./index.md) or [sensitivity analyses](../sensitivity/index). At the moment, it's possible to simulate the loss of a generator, a static VAR compensator, a shunt, a power line, a power transformer, an HVDC line or a busbar section. ## N-1 contingency -A N-1 contingency is a contingency that triggers a single equipment at a time. +A N-1 contingency is a contingency that triggers a single piece of equipment at a time. ```groovy contingency('contingencyID') { equipments 'equipmentID' } ``` -where the `contingencyID` is the identifier of the contingency and the `equipmentID` is the identifier of a supported equipment. If the equipment doesn't exist or is not supported, an error will occur. +where the `contingencyID` is the identifier of the contingency and the `equipmentID` is the identifier of a supported piece of equipment. If the equipment doesn't exist or is not supported, an error will occur. ## N-K contingency A N-K contingency is a contingency that triggers several equipments at a time. The syntax is the same as for the N-1 contingencies, except that you have to pass a list of equipments' IDs. @@ -31,7 +31,7 @@ contingency('contingency2') { ``` ## Automatic contingency list -As the DSL is written in Groovy, it's possible to write more complex script. For example, it's possible to iterate over the equipments of the network to generate the contingency list. The network is accessible using the `network` variable. +As the DSL is written in Groovy, it's possible to write a more complex script. For example, it's possible to iterate over the equipment of the network to generate the contingency list. The network is accessible using the `network` variable. The following example creates a N-1 contingency for each line of the network. We use the ID of the lines as identifier for the contingencies. ```groovy @@ -42,7 +42,7 @@ for (l in network.lines) { } ``` -It's also possible to filter the lines, for example to consider on the border lines: +It's also possible to filter the lines, for example, to consider on the boundary lines: ```groovy import com.powsybl.iidm.network.Country @@ -105,7 +105,7 @@ network.generatorStream ``` ## Configuration -To provide contingencies list using this DSL, you have to add the following lines to your configuration file: +To provide a contingency list using this DSL, you have to add the following lines to your configuration file: **YAML configuration:** ```yaml diff --git a/docs/simulation/security/index.md b/docs/simulation/security/index.md index 34d67a7cb2f..2de6edf9cfb 100644 --- a/docs/simulation/security/index.md +++ b/docs/simulation/security/index.md @@ -9,10 +9,10 @@ action-dsl.md limit-reductions.md ``` -The security analysis is a simulation that check violations on a network. These checks can be done on the base case or after a contingency, with or without remedial actions. A security analysis can monitor network states, in pre-contingency state, after a contingency and after a remedial action. +The security analysis is a simulation that checks violations on a network. These checks can be done on the base case or after a contingency, with or without remedial actions. A security analysis can monitor network states, in pre-contingency state, after a contingency and after a remedial action. -There is a violation if the computed value is greater than the maximum allowed value. Depending on the equipments, the violations can have different types: -- Current, active power and apparent power: this kind of violation can be detected on a branch (line, two windings transformer, tie line) or on a three windings transformer, if the computed value is greater than its [permanent limit](../../grid_model/additional.md#loading-limits) or one of its [temporary limits](../../grid_model/additional.md#loading-limits). +There is a violation if the computed value is greater than the maximum allowed value. Depending on the equipment, the violations can have different types: +- Current, active power and apparent power: this kind of violation can be detected on a branch (line, two-winding transformer, tie line) or on a three-winding transformer, if the computed value is greater than its [permanent limit](../../grid_model/additional.md#loading-limits) or one of its [temporary limits](../../grid_model/additional.md#loading-limits). - Voltage: this kind of violation can be detected on a bus or a bus bar section, if the computed voltage is out of the low-high voltage limits of a [voltage level](../../grid_model/network_subnetwork.md#voltage-level). - Voltage angle: this kind of violation can be detected if the voltage angle difference between the buses associated to two terminals is out of the low-high voltage angle limits defined in the network. @@ -48,7 +48,7 @@ Remedial actions are actions that are applied when limit violations occur. Suppo Remedial actions can be *preventive* or *curative*: - preventive: these actions are implemented before the violation occurs, for example if the flow of a monitored line is between `90%` and `100%`. Use contingency context `NONE` for that. -- curative: these actions are implemented after a violation occurs, for example if the flow of the monitored line is greater than `100%`. +- curative: these actions are implemented after a violation occurs, for example, if the flow of the monitored line is greater than `100%`. ### Conditions Actions are applied if a condition is met. The conditions can be diversified and extended in the future: @@ -63,7 +63,7 @@ An operator strategy is applied in pre-contingency or after a contingency, depen An operator strategy groups a condition and a list of remedial actions. ### State monitors -A stateMonitor allows to get information about branch, bus and three-winding transformers on the network after a security analysis computation. Contingency context allows to specify if the information asked are about pre-contingency state or post-contingency state with a contingency id or both. For example: +A stateMonitor allows getting information about branch, bus and three-winding transformers on the network after a security analysis computation. Contingency context allows to specify if the information asked are about pre-contingency state or post-contingency state with a contingency id or both. For example: - If we want information about a branch after security analysis on contingency `c1`, the contingencyContext will contain the contingencyId `c1`, contextType `SPECIFIC` and the state monitor will contain the id of the branch. - If we want information about a branch in pre-contingency state, the contingencyContext will contain a null contingencyId, contextType `NONE` and the state monitor will contain the id of the branch. - If we want information about a branch in pre-contingency state and after security analysis on contingency `c1`, the contingencyContext will contain contingencyId `c1`, contextType `ALL` and the state monitor will contain the id of the branch. @@ -84,7 +84,7 @@ You can find more details about limit reductions [here](./limit-reductions). ## Outputs ### Pre-contingency results -The violations are detected on the network at state N, meaning before a contingency occurred. This determines a reference for the simulation. For each violation, we get the ID of the overloaded equipment, the limit type (`CURRENT`, `ACTIVE_POWER`, `APPARENT_POWER`, `LOW_VOLTAGE` or `HIGH_VOLTAGE`, `LOW_VOLTAGE_ANGLE` or `HIGH_VOLTAGE_ANGLE`), the acceptable value and the computed value. For branches and three windings transformers, we also have the side where the violation has been detected. +The violations are detected on the network at state N, meaning before a contingency occurred. This determines a reference for the simulation. For each violation, we get the ID of the overloaded equipment, the limit type (`CURRENT`, `ACTIVE_POWER`, `APPARENT_POWER`, `LOW_VOLTAGE` or `HIGH_VOLTAGE`, `LOW_VOLTAGE_ANGLE` or `HIGH_VOLTAGE_ANGLE`), the acceptable value and the computed value. For branches and three-winding transformers, we also have the side where the violation has been detected. The pre-contingency results also contain the network results based on given state monitors. A network result groups branch results, bus results and three-winding transformer results. All elementary results are fully extendable. diff --git a/docs/simulation/security/limit-reductions.md b/docs/simulation/security/limit-reductions.md index def6d026978..6e14189bd33 100644 --- a/docs/simulation/security/limit-reductions.md +++ b/docs/simulation/security/limit-reductions.md @@ -9,7 +9,7 @@ Each limit reduction has its own criteria specifying for which limits and under - the type of limit (current, active power or apparent power) - the use case: for monitoring only or also for applying remedial actions - the contingency context (pre-contingency, after a specific contingency or after all contingencies, etc.) -- the network elements targeted by the reduction (branches, three-windings transformers, ...), which can be described by the following criteria: +- the network elements targeted by the reduction (branches, three-winding transformers, ...), which can be described by the following criteria: - a set of their ids; - their countries; - their nominal voltages. @@ -65,7 +65,7 @@ The network elements whose limits will be affected by the limit reductions can b - one or two countries (respectively for elements with one or two substations); - their nominal voltages, by defining an interval for each of the voltage levels. -If no network elements is specified, the limit reduction applies to all of them. +If no network elements are specified, the limit reduction applies to all of them. ### Limit duration criteria @@ -85,5 +85,5 @@ Duration criteria can be optionally specified. It contains: When no duration criteria are present, the reduction is applied to all permanent and temporary limits. -When several duration criteria are specified, the limit reductions applies to each one. +When several duration criteria are specified, the limit reductions apply to each one. For instance, if both criteria `PERMANENT` and (`TEMPORARY` ; `EQUALITY`: 600) are defined, the limit reduction will apply to permanent limits and 600 s limits. diff --git a/docs/simulation/sensitivity/configuration.md b/docs/simulation/sensitivity/configuration.md index 67a6d712d2b..276a64566e5 100644 --- a/docs/simulation/sensitivity/configuration.md +++ b/docs/simulation/sensitivity/configuration.md @@ -16,7 +16,7 @@ Use "OpenLoadFlow" to use PowSyBl OpenLoadFlow's sensitivity analysis implementa **flowFlowSensitivityValueThreshold** -The `flowFlowSensitivityValueThreshold` is the threshold under which sensitivity values having variable type among +The `flowFlowSensitivityValueThreshold` is the threshold under which sensitivity values having a variable type among `INJECTION_ACTIVE_POWER`, `INJECTION_REACTIVE_POWER` and `HVDC_LINE_ACTIVE_POWER` and function type among `BRANCH_ACTIVE_POWER_1/2/3`, `BRANCH_REACTIVE_POWER_1/2/3` and `BRANCH_CURRENT_1/2/3` will be filtered from the analysis results. The default value is 0.0. @@ -28,12 +28,12 @@ The `voltageVoltageSensitivityValueThreshold` is the threshold under which sensi **flowVoltageSensitivityValueThreshold** -The `flowVoltageSensitivityValueThreshold` is the threshold under which sensitivity values having variable type among +The `flowVoltageSensitivityValueThreshold` is the threshold under which sensitivity values having a variable type among `INJECTION_REACTIVE_POWER` and function type among `BUS_VOLTAGE`, or variable type among `BUS_TARGET_VOLTAGE` and function type among `BRANCH_REACTIVE_POWER_1/2/3`, `BRANCH_CURRENT_1/2/3` or `BUS_REACTIVE_POWER` will be filtered from the analysis results. The default value is 0.0. **angleFlowSensitivityValueThreshold** -The `angleFlowSensitivityValueThreshold` is the threshold under which sensitivity values having variable type among -`TRANSFORMER_PHASE` and `TRANSFORMER_PHASE_1/2/3` and function type among `BRANCH_ACTIVE_POWER_1/2/3`, `BRANCH_REACTIVE_POWER_1/2/3` +The `angleFlowSensitivityValueThreshold` is the threshold under which sensitivity values having a variable type among +`TRANSFORMER_PHASE` and `TRANSFORMER_PHASE_1/2/3` and a function type among `BRANCH_ACTIVE_POWER_1/2/3`, `BRANCH_REACTIVE_POWER_1/2/3` and `BRANCH_CURRENT_1/2/3` will be filtered from the analysis results. The default value is 0.0. \ No newline at end of file diff --git a/docs/simulation/sensitivity/index.md b/docs/simulation/sensitivity/index.md index 9709a764ebe..d5729117a1c 100644 --- a/docs/simulation/sensitivity/index.md +++ b/docs/simulation/sensitivity/index.md @@ -14,7 +14,7 @@ The sensitivity analysis module is dedicated to computing the linearized impact A sensitivity value is the numerical estimation of the partial derivative of the observed function with respect to the variable of impact. The sensitivity analysis can also be seen as the computation of partial derivatives on the network model. -For example, it may be used to know, among a group of selected lines, which are the most impacted by a change in a generator production or a change of tap on a phase tap changer. The user story about [RSC capacity calculation](https://www.powsybl.org/pages/documentation/user/user-stories/capacity_calculation_rsc.html) provides an example of application of the sensitivity analysis. +For example, it may be used to know among a group of selected lines, which are the most impacted by a change in a generator production or a change of tap on a phase tap changer. The user story about [RSC capacity calculation](https://www.powsybl.org/pages/documentation/user/user-stories/capacity_calculation_rsc.html) provides an example of application of the sensitivity analysis. (sensitivity-analysis-inputs)= ## Inputs @@ -25,10 +25,10 @@ The first input for the sensitivity analysis module is an IIDM network. (sensitivity-factors)= ### Sensitivity factors Aside from providing an input network, it is necessary to specify which equipments are going to be studied: -- what impacted equipments are selected to be monitored (lines for example) +- what impacted equipment is selected to be monitored (lines, for example) - according to a change on which equipment (a generator's production or a group of generator's production, or the tap position of a phase tap changer, etc.) -It is also necessary to specify which quantity is being observed: the active power or the current on the monitored equipments, the voltage at a bus. +It is also necessary to specify which quantity is being observed: the active power or the current on the monitored equipment, the voltage of a bus. This set of information constitutes the sensitivity factors (`SensitivityFactor`). These factors correspond to the definition of the expected partial derivatives to be extracted from the input network. @@ -41,19 +41,19 @@ A standard sensitivity analysis input thus comprises a list of sensitivity facto A sensitivity variable represents a change on an equipment or on a group of equipments. The supported variable types are: - Use `INJECTION_ACTIVE_POWER` to model a change on active production of a generator or on a group of generators, on the active consumption of a load or on a group of loads or on GLSK (for Generation and Load Shift keys) that describes a linear combination of active power injection shifts on generators and loads. The variable increase is in MW. - Use `INJECTION_REACTIVE_POWER` to model a change on reactive production of a generator or on the reactive consumption of a load. The variable increase is in MVar. -- Use `TRANSFORMER_PHASE` to model the change of the tap position of a phase tap changer of a two windings transformer. The increase is in degree. -- Use `BUS_TARGET_VOLTAGE` to model an increase of the voltage target of a generator, a static var compensator, a two or three windings transformer, a shunt compensator or a VSC converter station. The increase is in KV. +- Use `TRANSFORMER_PHASE` to model the change of the tap position of a phase tap changer of a two-winding transformer. The increase is in degree. +- Use `BUS_TARGET_VOLTAGE` to model an increase of the voltage target of a generator, a static var compensator, a two or three-winding transformer, a shunt compensator or a VSC converter station. The increase is in KV. - Use `HVDC_LINE_ACTIVE_POWER` to model the change of the active power set point of an HVDC line. The increase is in MW. -- Use `TRANSFORMER_PHASE_1`, `TRANSFORMER_PHASE_2` or `TRANSFORMER_PHASE_3` to model the change of the tap position of a phase tap changer of a three windings transformer that contains several phase tap changers. +- Use `TRANSFORMER_PHASE_1`, `TRANSFORMER_PHASE_2` or `TRANSFORMER_PHASE_3` to model the change of the tap position of a phase tap changer of a three-winding transformer that contains several phase tap changers. The supported sensitivity function types, related to the equipment to monitor, are: -- Use `BRANCH_ACTIVE_POWER_1` and `BRANCH_ACTIVE_POWER_2` if you want to monitor the active power in MW of a network branch (lines, two windings transformer, dangling lines, etc.). Use 1 for side 1 and 2 for side 2. In case of a three windings transformer, use `BRANCH_ACTIVE_POWER_3` to monitor the active power in MW of the leg 3 (network side). -- Use `BRANCH_REACTIVE_POWER_1` and `BRANCH_REACTIVE_POWER_2` if you want to monitor the reactive power in MVar of a network branch (lines, two-winding transformer, dangling lines, etc.). Use 1 for side 1 and 2 for side 2. In case of a three-winding transformer, use `BRANCH_REACTIVE_POWER_3` to monitor the reactive power in MVar of the leg 3 (network side). -- Use `BRANCH_CURRENT_1` and `BRANCH_CURRENT_2` if you want to monitor the current in A of a network branch (lines, two windings transformer, dangling lines, etc.). Use 1 for side 1 and use 2 for side 2. In case of a three windings transformer, use `BRANCH_CURRENT_3` to monitor the current in A of the leg 3 (network side). +- Use `BRANCH_ACTIVE_POWER_1` and `BRANCH_ACTIVE_POWER_2` if you want to monitor the active power in MW of a network branch (lines, two-winding transformer, dangling lines, etc.). Use 1 for side 1 and 2 for side 2. In case of a three-winding transformer, use `BRANCH_ACTIVE_POWER_3` to monitor the active power in MW of leg 3 (network side). +- Use `BRANCH_REACTIVE_POWER_1` and `BRANCH_REACTIVE_POWER_2` if you want to monitor the reactive power in MVar of a network branch (lines, two-winding transformer, dangling lines, etc.). Use 1 for side 1 and 2 for side 2. In case of a three-winding transformer, use `BRANCH_REACTIVE_POWER_3` to monitor the reactive power in MVar of leg 3 (network side). +- Use `BRANCH_CURRENT_1` and `BRANCH_CURRENT_2` if you want to monitor the current in A of a network branch (lines, two-winding transformer, dangling lines, etc.). Use 1 for side 1 and use 2 for side 2. In case of a three-winding transformer, use `BRANCH_CURRENT_3` to monitor the current in A of leg 3 (network side). - `BUS_VOLTAGE` if you want to monitor the voltage in KV of a specific network bus. - `BUS_REACTIVE_POWER` if you want to monitor the reactive power injection in MVar of a specific network bus. -A sensitivity variable can group some equipments and has to be modeled as a variable set. In a `SensitivityVariableSet`, we have a list of individual variables, each one with a weight (called `WeightedSensitivityVariable`). We use variable sets to model what it commonly called GLSK. +A sensitivity variable can group some equipment and has to be modeled as a variable set. In a `SensitivityVariableSet`, we have a list of individual variables, each one with a weight (called `WeightedSensitivityVariable`). We use variable sets to model what it commonly called GLSK. #### How to provide the sensitivity factors input @@ -79,7 +79,7 @@ The sensitivity factors may be created directly through Java code, or be provide ### Contingencies The sensitivity analysis may also take, optionally, a list of contingencies as an input. When contingencies are provided, the sensitivity values -shall be calculated on the network at state N, but also after the application of each contingency. The contingencies are provided in the same way than for the [security analysis](../security/index.md/). This then constitutes a systematic sensitivity analysis. +shall be calculated on the network at state N, but also after the application of each contingency. The contingencies are provided in the same way as for the [security analysis](../security/index.md/). This then constitutes a systematic sensitivity analysis. ```json { @@ -96,7 +96,7 @@ shall be calculated on the network at state N, but also after the application of } ``` -At the moment the only available sensitivity simulator officially compatible with PowSyBl is the one available through OpenLoadFlow. In this case, the network is provided only once in state N, and then all the calculations are done successively by modifying the Jacobian matrix directly in the solver based on the contingencies input. The network is thus loaded only once, which improves performance. +At the moment, the only available sensitivity simulator officially compatible with PowSyBl is the one available through OpenLoadFlow. In this case, the network is provided only once in state N, and then all the calculations are done successively by modifying the Jacobian matrix directly in the solver based on the contingency input. The network is thus loaded only once, which improves performance. (sensitivity-analysis-outputs)= ## Outputs diff --git a/docs/simulation/shortcircuit/index.md b/docs/simulation/shortcircuit/index.md index c0cef7a2267..1055ba7e108 100644 --- a/docs/simulation/shortcircuit/index.md +++ b/docs/simulation/shortcircuit/index.md @@ -1,7 +1,7 @@ # Short-circuit analysis When a short circuit occurs in a network, the currents on equipment can be so high that they exceed their rated values. -Simulating faults on the network is important to verify that the short circuits are well detected and do not damage the equipments. +Simulating faults on the network is important to verify that the short circuits are well detected and do not damage the equipment. The short-circuit API allows the calculation of currents and voltages on a network after a fault. A first implementation of the API is available in [powsybl-incubator](https://github.com/powsybl/powsybl-incubator/tree/main/simulator/short-circuit). diff --git a/docs/simulation/shortcircuit/inputs.md b/docs/simulation/shortcircuit/inputs.md index 9fc4f09de2e..7c2af287911 100644 --- a/docs/simulation/shortcircuit/inputs.md +++ b/docs/simulation/shortcircuit/inputs.md @@ -16,7 +16,7 @@ The attributes to fill of a `BusFault` are: | Attribute | Type | Unit | Required | Default value | Description | |------------|----------------|------|----------|-------------------------|---------------------------------------------------------------------------------------------------------| | id | String | - | yes | - | The id of the fault | -| elementId | String | - | yes | - | The id of the bus on which the fault will be simulated (bus/view topology) | +| elementId | String | - | yes | - | The id of the bus on which the fault will be simulated (bus/view topology) | | r | double | Ω | no | 0 | The fault resistance to ground | | x | double | Ω | no | 0 | The fault reactance to ground | | connection | ConnectionType | - | no | `ConnectionType.SERIES` | The way the resistance and reactance of the fault are connected to the ground: in series or in parallel | @@ -25,7 +25,7 @@ The attributes to fill of a `BusFault` are: The attributes to fill of a `BranchFault` are: | Attribute | Type | Unit | Required | Default value | Description | -|----------------------|----------------|------|----------|----------------------- |---------------------------------------------------------------------------------------------------------| +|----------------------|----------------|------|----------|-------------------------|---------------------------------------------------------------------------------------------------------| | id | String | - | yes | - | The id of the fault | | elementId | String | - | yes | - | The id of the branch on which the fault will be simulated | | r | double | Ω | no | 0 | The fault resistance to ground | diff --git a/docs/simulation/shortcircuit/outputs.md b/docs/simulation/shortcircuit/outputs.md index 09549a4a682..9192bd85043 100644 --- a/docs/simulation/shortcircuit/outputs.md +++ b/docs/simulation/shortcircuit/outputs.md @@ -41,7 +41,7 @@ In `FortescueFaultResult`, they are: **The status of the computation** This status can be: -- `SUCCESS`: the computation went as planned and the results are full considering the parameters. +- `SUCCESS`: the computation went as planned, and the results are full considering the parameters. - `NO_SHORT_CIRCUIT_DATA`: this status should be returned if no short-circuit data are available in the network, i.e., the sub-transient or transient reactance of generators and the minimum and maximum admissible short-circuit currents. - `SOLVER_FAILURE`: the computation failed because of an error linked to the solver. - `FAILURE`: the computation failed for any other reason. diff --git a/docs/simulation/shortcircuit/parameters.md b/docs/simulation/shortcircuit/parameters.md index 13de70c4772..110c9f67af5 100644 --- a/docs/simulation/shortcircuit/parameters.md +++ b/docs/simulation/shortcircuit/parameters.md @@ -51,7 +51,7 @@ The default value is `TRANSIENT`. The transient and sub-transient reactance of t **sub-transient-coefficient** -This property allows to define an optional coefficient, in case of a sub-transient study, to apply to the transient reactance of generators to get the sub-transient one: +This property allows defining an optional coefficient, in case of a sub-transient study, to apply to the transient reactance of generators to get the sub-transient one: $X''_d = c \times X'_d$ @@ -75,7 +75,7 @@ The voltage drop is calculated as the ratio between the initial voltage magnitud **with-loads** -This property indicates whether loads should be taken into account during the calculation. If `true`, the loads are modelled as an equivalent reactance and the equivalent reactance at the fault point will be lowered. If `false`, then they will be ignored. +This property indicates whether loads should be taken into account during the calculation. If `true`, the loads are modelled as an equivalent reactance, and the equivalent reactance at the fault point will be lowered. If `false`, then they will be ignored. **with-shunt-compensators** diff --git a/docs/user/configuration/componentDefaultConfig.md b/docs/user/configuration/componentDefaultConfig.md index 50a5409aa61..dc7ccb66d2a 100644 --- a/docs/user/configuration/componentDefaultConfig.md +++ b/docs/user/configuration/componentDefaultConfig.md @@ -1,5 +1,5 @@ # componentDefaultConfig -The `componentDefaultConfig` module is used to configure the implementation of plugins the framework has to use for specific features (e.g. computation, etc.). Contrary to the other modules, it is impossible to give an exhaustive list of the existing properties. +The `componentDefaultConfig` module is used to configure the implementation of plugins that the framework has to use for specific features (e.g. computation, etc.). Contrary to the other modules, it is impossible to give an exhaustive list of the existing properties. The names of the properties are the names of Java interfaces of the powsybl framework. Each value must be the complete name of a class which implements this interface. - ContingenciesProviderFactory diff --git a/docs/user/configuration/import-export-parameters-default-value.md b/docs/user/configuration/import-export-parameters-default-value.md index 0f537575798..d04d145642e 100644 --- a/docs/user/configuration/import-export-parameters-default-value.md +++ b/docs/user/configuration/import-export-parameters-default-value.md @@ -5,7 +5,7 @@ The `import-export-parameters-default-value` module is an optional module used b - List of Strings As the parameters are different from an importer to another, it is impossible to give an exhaustive list of supported -properties. Please refer to the documentation of each [supported formats](../../grid_exchange_formats/index.md) to know their specific configuration. +properties. Please refer to the documentation of each [supported format](../../grid_exchange_formats/index.md) to know their specific configuration. ## Examples diff --git a/docs/user/configuration/index.md b/docs/user/configuration/index.md index 8a16cbdf488..6c17e6b5338 100644 --- a/docs/user/configuration/index.md +++ b/docs/user/configuration/index.md @@ -18,7 +18,7 @@ loadflow-validation.md security-analysis.md ``` -The configuration mechanism supports YAML and XML file formats. The framework looks inside all the folders specified to the [powsybl_config_dirs](../itools/index.md#configuration) property in the [itools.conf](../itools/index.md#configuration) file for configuration files. The framework uses the [powsybl_config_name](../itools/index.md#configuration) property as the basename of the configuration files. It looks for a YAML file first, then for a XML file. The XML file will be used only if the YAML configuration file has not been found. +The configuration mechanism supports YAML and XML file formats. The framework looks inside all the folders specified to the [powsybl_config_dirs](../itools/index.md#configuration) property in the [itools.conf](../itools/index.md#configuration) file for configuration files. The framework uses the [powsybl_config_name](../itools/index.md#configuration) property as the basename of the configuration files. It looks for a YAML file first, then for an XML file. The XML file will be used only if the YAML configuration file has not been found. The configuration can also be configured using the system's environment variables. These variables should respect the following format: `MODULE_NAME__PROPERTY_NAME`. Note that these variables will overload the XML/YAML configuration files. @@ -26,7 +26,7 @@ following format: `MODULE_NAME__PROPERTY_NAME`. Note that these variables will o The default configuration folder and the configuration file name can be configured in the `POWSYBL_HOME/etc/itools.conf`. ## Modules and properties -The configuration file contains a list of modules, that can be required or optional. Each module contains one or +The configuration file contains a list of modules that can be required or optional. Each module contains one or several properties. These properties can also be required or optional. Names in configuration files are case-sensitive. ### Example @@ -59,15 +59,15 @@ module2: ``` ### System's environment variables -Configuration properties can also be overridden using system's environment variables. The module and the property are separated using two underscores. The table below give examples on the way to declare environment variables for PowSyBl: +Configuration properties can also be overridden using system's environment variables. The module and the property are separated using two underscores. The table below gives examples on the way to declare environment variables for PowSyBl: -| Environment variable | Module name | Property name | -| -------------------- | ----------- | ------------- | -| MODULE1__PROPERTY1=1 | module1 | property1 | -| LOWER_HYPHEN__PROPERTY2=2 | lower-hyphen | property2 | -| LOWER_CAMEL__PROPERTY3=3 | lowerCamel | property3 | -| UPPER_CAMEL__PROPERTY4=4 | UpperCamel | property4 | -| SNAKE_CASE__PROPERTY5=5 | snake_case | property5 | +| Environment variable | Module name | Property name | +|---------------------------|--------------|---------------| +| MODULE1__PROPERTY1=1 | module1 | property1 | +| LOWER_HYPHEN__PROPERTY2=2 | lower-hyphen | property2 | +| LOWER_CAMEL__PROPERTY3=3 | lowerCamel | property3 | +| UPPER_CAMEL__PROPERTY4=4 | UpperCamel | property4 | +| SNAKE_CASE__PROPERTY5=5 | snake_case | property5 | ## Modules list - [componentDefaultConfig](componentDefaultConfig.md) diff --git a/docs/user/configuration/limit-violation-default-filter.md b/docs/user/configuration/limit-violation-default-filter.md index b798a2fd057..ab0afab4f6e 100644 --- a/docs/user/configuration/limit-violation-default-filter.md +++ b/docs/user/configuration/limit-violation-default-filter.md @@ -5,7 +5,7 @@ The `limit-violation-default-filter` module is used by the [security-analysis](. ## Optional properties **countries** -The `countries` property is an optional property that defines a list of [ISO-3166](https://en.wikipedia.org/wiki/ISO_3166-1) country codes used for violations filtering. A violation is displayed only if at least one of its side has its substation's country in the list. If this property is not set, there is no filtering based on the countries. +The `countries` property is an optional property that defines a list of [ISO-3166](https://en.wikipedia.org/wiki/ISO_3166-1) country codes used for violations filtering. A violation is displayed only if at least one of its sides has its substation's country in the list. If this property is not set, there is no filtering based on the countries. **minBaseVoltage** The `minBaseVoltage` property is an optional property that defines a threshold value for the nominal voltage of the voltage levels. The default value of this property is `0`. diff --git a/docs/user/configuration/load-flow-action-simulator.md b/docs/user/configuration/load-flow-action-simulator.md index 88648cea378..7abdec99b84 100644 --- a/docs/user/configuration/load-flow-action-simulator.md +++ b/docs/user/configuration/load-flow-action-simulator.md @@ -6,7 +6,7 @@ The `load-flow-action-simulator` module is used by the [action-simulator]() tool **copy-strategy** Use the `copy-strategy` to define how the action-simulator will store and restore network state internally. This choice can greatly impact performances. Possible values are: - `STATE`: will only save and restore state data. Optimizes performances, but will not behave correctly if some actions modify the structure of the network. -- `DEEP`: will save and restore all network data. Decreases performances, but allows to use any type of action. +- `DEEP`: will save and restore all network data. Decreases performance, but allows to use any type of action. **ignore-pre-contingency-violations** Set the `ignore-pre-contingency-violations` to `true` to ignore the pre-contingency violations and continue the simulation even if there are still violations after the pre-contingency simulation. @@ -17,7 +17,7 @@ If this property is not set, the default load flow implementation is used. See [ configure the default load flow. **max-iterations** -Use the `max-iterations` parameter to limit the number of iteration needed to solve the violations. +Use the `max-iterations` parameter to limit the number of iterations needed to solve the violations. ## Examples diff --git a/docs/user/configuration/loadflow-validation.md b/docs/user/configuration/loadflow-validation.md index bbfd0409631..e024b379481 100644 --- a/docs/user/configuration/loadflow-validation.md +++ b/docs/user/configuration/loadflow-validation.md @@ -32,7 +32,7 @@ The `ok-missing-values` property is an optional property that defines whether th **output-writer** The `output-writer` property is an optional property that defines the output format. Currently, `CSV` and `CSV_MULTILINE` are supported. The default value of this property is set to `CSV_MULTILINE`. -If this property is set to `CSV`, in the output files a line contains all values of a validated equipment. If the property is set to `CSV_MULTILINE`, in the output files the values of an equipment are split in multiple lines, one value for each line, see examples below: +If this property is set to `CSV`, in the output files a line contains all values of validated equipment. If the property is set to `CSV_MULTILINE`, in the output files the equipment values are split in multiple lines, one value for each line, see examples below: **Example of output in CSV format:** ``` @@ -66,7 +66,7 @@ The `threshold` property is an optional property that defines the margin used fo **verbose:** The `verbose` property is an optional property that defines whether the [loadflow-validation](../itools/loadflow-validation.md) command runs in verbose or quiet mode. -If this property is set to `true`, the output files contain all the data of the validated equipments, otherwise they contain only the main data of the validated equipments. +If this property is set to `true`, the output files contain all the data of the validated equipment; otherwise they contain only the main data of the validated equipment. ## Examples diff --git a/docs/user/configuration/security-analysis.md b/docs/user/configuration/security-analysis.md index 2981849b582..0428ed570cf 100644 --- a/docs/user/configuration/security-analysis.md +++ b/docs/user/configuration/security-analysis.md @@ -5,7 +5,7 @@ The `security-analysis` module is used to configure the execution of the [securi ## Optional property **preprocessor** -The `preprocessor` property is an optional property which requires that the `SecurityAnalysisPreprocessor` with specified name is used to preprocess inputs, based on the contingencies file, before actually running the security analysis. +The `preprocessor` property is an optional property which requires that the `SecurityAnalysisPreprocessor` with specified name is used to preprocess inputs, based on the contingency file, before actually running the security analysis. Such a preprocessor will have the possibility to programmatically transform the following objects before the security analysis is actually executed : - The `Network` @@ -17,7 +17,7 @@ Such a preprocessor will have the possibility to programmatically transform the It enables, for example, to customize what should be considered a limit violation and what should not. -If absent, the default behavior of the tool is used: the contingencies file is simply interpreted by the configured contingencies provider. +If absent, the default behavior of the tool is used: the contingency file is simply interpreted by the configured contingency provider. ## Examples diff --git a/docs/user/itools/action-simulator.md b/docs/user/itools/action-simulator.md index abde565c267..871b4cc98c9 100644 --- a/docs/user/itools/action-simulator.md +++ b/docs/user/itools/action-simulator.md @@ -59,7 +59,7 @@ This option defines the path of the strategy to evaluate. This is a groovy scrip This option defines the list of contingencies to simulate. If this parameter is omitted, all the contingencies defined in the DSL file are simulated. `--export-after-each-round` -If this option is passed, a case file is exported after each round of the simulation. Otherwise, a single case file is exported at the end of the simulation (once there is no more violations or matching rules). +If this option is passed, a case file is exported after each round of the simulation. Otherwise, a single case file is exported at the end of the simulation (once there are no more violations or matching rules). `--import-parameters` This option defines the path of the importer's configuration file. It's possible to overload one or many parameters using the `-I property=value` syntax. The list of supported properties depends on the [input format](../../grid_exchange_formats/index.md). @@ -71,19 +71,19 @@ This option defines the path to the folder in which the case files will be expor This option defines the format of the output case files. The list of [supported formats](../../grid_exchange_formats/index.md) are listed between brackets in the command help. `--output-compression-format` -This option defines the compression format of the case files. The list of supported formats are listed between brackets in the command help. +This option defines the compression format of the case files. The list of supported formats is mentioned between brackets in the command help. `--output-file` This option defines the path of the result file. If this option is omitted, the results are displayed in the console. `--output-format` -This option defines the format of the result file. This option is required if `--output-file` is used. The supported format are listed between brackets in the command help. +This option defines the format of the result file. This option is required if `--output-file` is used. The supported formats are listed between brackets in the command help. `--verbose` This option enables the verbose mode, to display more information during the simulation. ## Simulators -Currently, the only simulator which is supported is the [load-flow based]() simulator. +Currently, the only simulator which is supported is the [load-flow-based]() simulator. ## Parameters TODO @@ -127,7 +127,7 @@ action('load_shed_100') { ``` -The following example show the results of the simulation of the previous script: +The following example shows the results of the simulation of the previous script: ```shell $> itools action-simulator --case-file $HOME/eurostag-tutorial.xiidm --dsl-file $HOME/actions.groovy Loading network '$HOME/eurostag-tutorial.xiidm' diff --git a/docs/user/itools/compare-security-analysis-results.md b/docs/user/itools/compare-security-analysis-results.md index f495f8eca1d..e14bb690fd2 100644 --- a/docs/user/itools/compare-security-analysis-results.md +++ b/docs/user/itools/compare-security-analysis-results.md @@ -9,13 +9,13 @@ This tool compares for the pre-contingency state and for all the post-contingenc - the values of the constraints violations Two security analysis results are considered equivalent if all the following conditions are satisfied: -- for all the pre-contingency and post-contingency states, the corresponding (i.e. related to the same state) outcome of the load flow computation is the same -- for all the constraints violations, the difference of value of a corresponding (i.e. related to the same contingency +- for all the pre-contingency and post-contingency states, the corresponding (i.e., related to the same state) outcome of the load flow computation is the same +- for all the constraint violations, the difference of value of a corresponding (i.e., related to the same contingency and equipment) violation is less than a predefined threshold -- if a constraints violation is contained in just one result, the violation is less than a predefined threshold +- if a constraint violation is contained in just one result, the violation is less than a predefined threshold - if a contingency is contained in just one result, all the post-contingency violations are less than a predefined threshold -The comparison process can optionally output in a CSV file all the compared values (pre and post-contingency load flow computation outcomes, and related constraints violations), with a corresponding comparison result (`equivalent`,`different`). See example below. +The comparison process can optionally output in a CSV file all the compared values (pre- and post-contingency load flow computation outcomes, and related constraints violations), with a corresponding comparison result (`equivalent`,`different`). See example below. ``` Contingency;StatusResult1;StatusResult2;Equipment;End;ViolationType;ViolationNameResult1;ValueResult1;LimitResult1;ViolationNameResult2;ValueResult2;LimitResult2;ActionsResult1;ActionsResult2;Comparison diff --git a/docs/user/itools/dynamic-security-analysis.md b/docs/user/itools/dynamic-security-analysis.md index da55de41c06..afd22662d73 100644 --- a/docs/user/itools/dynamic-security-analysis.md +++ b/docs/user/itools/dynamic-security-analysis.md @@ -1,6 +1,6 @@ # iTools dynamic-security-analysis -The `dynamic-security-analysis` command loads a grid file, apply dynamic models, and run a [dynamic security analysis](../../simulation/dynamic_security/index.md) simulation, to detect security violations on pre- or post-contingencies states. At the end of the simulation the results are printed or exported to a file. +The `dynamic-security-analysis` command loads a grid file, apply dynamic models, and run a [dynamic security analysis](../../simulation/dynamic_security/index.md) simulation, to detect security violations on pre- or post-contingencies states. At the end of the simulation, the results are printed or exported to a file. ## Usage ``` @@ -54,7 +54,7 @@ This option defines the path of the mapping file used to associate dynamic model ### Optional arguments `--contingencies-file` -This option defines the path of the contingencies files. If this parameter is not set, the security violations are checked on the base state only. This file is a groovy script that respects the [contingency DSL](../../simulation/security/contingency-dsl.md) syntax. +This option defines the path of the contingency files. If this parameter is not set, the security violations are checked on the base state only. This file is a groovy script that respects the [contingency DSL](../../simulation/security/contingency-dsl.md) syntax. `--external` TODO: Use this argument to run the security analysis as an external process. @@ -63,7 +63,7 @@ This option defines the path of the contingencies files. If this parameter is no This option defines the path of the importer's configuration file. It's possible to overload one or many parameters using the `-I property=value` syntax. The list of supported properties depends on the [input format](../../grid_exchange_formats/index.md). `--limit-types` -This option allows to filter certain types of violations. It overrides the default configuration defined in the [limit-violation-default-filter](../configuration/limit-violation-default-filter.md) configuration module. The supported types are the following: `CURRENT`, `LOW_VOLTAGE`, `HIGH_VOLTAGE`, `LOW_SHORT_CIRCUIT_CURRENT`, `HIGH_SHORT_CIRCUIT_CURRENT` and `OTHER`. +This option allows filtering certain types of violations. It overrides the default configuration defined in the [limit-violation-default-filter](../configuration/limit-violation-default-filter.md) configuration module. The supported types are the following: `CURRENT`, `LOW_VOLTAGE`, `HIGH_VOLTAGE`, `LOW_SHORT_CIRCUIT_CURRENT`, `HIGH_SHORT_CIRCUIT_CURRENT` and `OTHER`. `--log-file` TODO @@ -78,7 +78,7 @@ This option defines the format of the output file. This option is required if th This option defines the path of the [parameters](#parameters) file of the simulation. If this option is not used, the simulation is run with the default parameters. `--with-extensions` -This option defines the list of extensions to complete the simulation results with additional data. This list of available extensions are listed in the usage of the command. +This option defines the list of extensions to complete the simulation results with additional data. The available extensions are listed in the usage of the command. ## Simulators TODO diff --git a/docs/user/itools/dynamic-simulation.md b/docs/user/itools/dynamic-simulation.md index 942e80b3358..a466cf75ac0 100644 --- a/docs/user/itools/dynamic-simulation.md +++ b/docs/user/itools/dynamic-simulation.md @@ -1,7 +1,7 @@ # iTools dynamic-simulation The `dynamic-simulation` command loads a grid file and run a [time domain](../../simulation/dynamic/index.md) simulation. -At the end, the results and the modified network can be exported to files. +In the end, the results and the modified network can be exported to files. ## Usage ``` @@ -83,7 +83,7 @@ dynamic simulation results: +--------+ ``` -The following example shows how to run a time domain simulation, using a parameters file: +The following example shows how to run a time domain simulation, using a parameter file: ``` $> itools dynamic-simulation --case-file IEEE14.iidm --dynamic-models-file dynamicModels.groovy --parameters-file dynawoParameters.json dynamic simulation results: diff --git a/docs/user/itools/index.md b/docs/user/itools/index.md index 71629611314..2d5a2898e05 100644 --- a/docs/user/itools/index.md +++ b/docs/user/itools/index.md @@ -18,7 +18,7 @@ dynamic-security-analysis.md sensitivity-computation.md ``` -The `iTools` script provides a command-line interface to interact with PowSyBl, available under Linux and Windows (MacOS is not supported yet). +The `iTools` script provides a command-line interface to interact with PowSyBl, available under Linux and Windows (macOS is not supported yet). An `iTools` package is constituted of: - a `bin` directory containing the executable scripts and the binaries @@ -66,7 +66,7 @@ java_xmx=8G The list of the deprecated properties is available [here]() ### Logging -The `iTools` script uses [logback](https://logback.qos.ch/) as logging framework. To configure the logging framework, edit the `/etc/logback-itools.xml` configuration file. Please refer to the [logback manual](https://logback.qos.ch/manual/index.html) for the available logging options. +The `iTools` script uses [logback](https://logback.qos.ch/) as a logging framework. To configure the logging framework, edit the `/etc/logback-itools.xml` configuration file. Please refer to the [logback manual](https://logback.qos.ch/manual/index.html) for the available logging options. Sometimes, it could be useful for a user to have its own logging configuration to filter unexpected logs or to have more details for some features. The simplest way to proceed is to copy the global configuration file in the `/.itools` folder and then customize it. @@ -89,7 +89,7 @@ Sometimes, it could be useful for a user to have its own logging configuration t The `iTools` script relies on a [plugin mechanism](): the commands are discovered at runtime and depend on the jars present in the `share/java` folder. | Command | Theme | Description | -|-----------------------------------------------------------------------------| --------------- |-----------------------------------------------| +|-----------------------------------------------------------------------------|-----------------|-----------------------------------------------| | [action-simulator](./action-simulator.md) | Computation | Run a security analysis with remedial actions | | [cim-anonymizer](cim_anonymizer.md) | Data conversion | Anonymize CIM files | | [compare-security-analysis-results](./compare-security-analysis-results.md) | Computation | Compare security analysis results | diff --git a/docs/user/itools/loadflow-validation.md b/docs/user/itools/loadflow-validation.md index 6131c7102e8..29d985376c2 100644 --- a/docs/user/itools/loadflow-validation.md +++ b/docs/user/itools/loadflow-validation.md @@ -66,13 +66,13 @@ Use the `--output-folder` parameter to define the path of the folder where the o ### Optional arguments `--compare-case-file` -Use the `--compare-case-file` parameter to define the path of the second case file, in order to compare the loadflow +Use the `--compare-case-file` parameter to define the path of the second case file, in order to compare the load flow results of two case files. `--compare-results` Use the `--compare-results` parameter to define the type of results to compare. The available types are: -- `BASECASE`: compare results of the two basecases -- `COMPUTATION`: run a computation on the two basecases and compare results of the resulting states. +- `BASECASE`: compare results of the two base cases +- `COMPUTATION`: run a computation on the two base cases and compare results of the resulting states. `--import-parameters` Use the `--import-parameters` parameter to specify the path of the configuration file of the importer. It is possible to @@ -86,8 +86,8 @@ Use the `--load-flow` parameter to run a load-flow before the validation. This o `--output-format` Use the `--output-format` parameter to specify the format of the output files. The available output formats are `CSV` or `CSV_MULTILINE`. -If this parameter is set to `CSV`, in the output files a line contains all values of a validated equipment. If the parameter -is set to `CSV_MULTILINE`, in the output files the values of an equipment are split in multiple lines, one value for each +If this parameter is set to `CSV`, in the output files a line contains all values of validated equipment. If the parameter +is set to `CSV_MULTILINE`, in the output files the values of a piece of equipment are split in multiple lines, one value for each line, see examples below: **CSV** @@ -125,40 +125,40 @@ corresponding case states validated and written in the output files. Some remark - State 2 is the state analyzed in the second validation (columns with the suffix `_postComp` in the output files) - Case 1 is the value of `case-file` parameter - Case 2 is the value of `compare-case-file` parameter -- some combinations are not available, e.g. if you use the `compare-results` parameter, with the `COMPUTATION` value, +- some combinations are not available, e.g., if you use the `compare-results` parameter, with the `COMPUTATION` value, you have to use the `run-computation` (or `load-flow`) parameter. -| Number | compare-results | run-computation | State 1 | State 2 (_postComp) | -| ------- | ------- | ------- | ------- | ------- | -| 1 | absent | absent | Case 1 after import | None | -| 2 | absent | `loadflow`/`loadflowResultsCompletion` | Case 1 after import and computation | None | -| 3 | `BASECASE` | absent | Case 1 after import | Case 2 after import | -| 4 | `BASECASE` | `loadflow`/`loadflowResultsCompletion` | Case 1 after import and computation | Case 2 after import | -| 5 | `COMPUTATION` | `loadflow`/`loadflowResultsCompletion` | Case 1 after import | Case 1 after import and computation | +| Number | compare-results | run-computation | State 1 | State 2 (_postComp) | +|--------|-----------------|----------------------------------------|-------------------------------------|-------------------------------------| +| 1 | absent | absent | Case 1 after import | None | +| 2 | absent | `loadflow`/`loadflowResultsCompletion` | Case 1 after import and computation | None | +| 3 | `BASECASE` | absent | Case 1 after import | Case 2 after import | +| 4 | `BASECASE` | `loadflow`/`loadflowResultsCompletion` | Case 1 after import and computation | Case 2 after import | +| 5 | `COMPUTATION` | `loadflow`/`loadflowResultsCompletion` | Case 1 after import | Case 1 after import and computation | ## Parameters To learn how to configure the `loadflow-validation` command, read the documentation of the [loadflow validation](../configuration/loadflow-validation.md) module. -You may also configure the loadflow itself to tune the loadflow validation using the `--run-computation` option (check the [loadflow configuration page](../configuration/load-flow.md)). +You may also configure the load flow itself to tune the load flow validation using the `--run-computation` option (check the [loadflow configuration page](../configuration/load-flow.md)). ## Load flow results validation -Overall, in the PowSyBl validation the tests are not made overly tight. In particular, leniency is preferred to tightness in case approximations are needed or +Overall, in the PowSyBl validation, the tests are not made overly tight. In particular, leniency is preferred to tightness in case approximations are needed or when expectations are unclear (typically when the input data is inconsistent). For example, there is a switch to test only the main component because it is not clear what to expect from load flow results on small connected components. Another important global setting available in the PowSyBl validation is the `ok-missing-values` parameter, which determines if is OK to have missing -values or `NaN`. Normally, it should be set to false but it may be useful in the cases where the power flow results are +values or `NaN`. Normally, it should be set to false, but it may be useful in the cases where the power flow results are incomplete to go through the rest of the validation. -In this section we go into more details about the checks performed by the validation feature of load-flow results available in PowSyBl. +In this section, we go into more details about the checks performed by the validation feature of load-flow results available in PowSyBl. ### Buses If all values are present, or if only one value is missing, the result is considered to be consistent. Note that if the result contains only the voltages (phase and angle), the PowSyBl validation provides a load-flow results completion feature. -It can be used to compute the flows from the voltages in order to ensure the results consistency, with the run-computation option of +It can be used to compute the flows from the voltages to ensure the result consistency, with the run-computation option of the PowSyBl validation. ### Branches @@ -167,19 +167,19 @@ The result on the branch is considered consistent if: $$\max( \left| P_1^{calc} - P_1 \right|, \left| Q_1^{calc} - Q_1 \right|, \left| P_2^{calc} - P_2 \right|, \left| Q_2^{calc} - Q_2 \right| ) \leq \epsilon$$ -For a branch that is disconnected on one end (for example end 2), then $P_2 = Q_2 = 0$. As a result, it is +For a branch that is disconnected on one end (for example, end 2), then $P_2 = Q_2 = 0$. As a result, it is possible to recompute $(V_2, \theta_2)$ which are usually not returned by power flows and which are not stored in node-breaker [network](../../grid_model/index.md) format. The quality checks are done when this is done. In case of missing results (usually the powers $P_1$, $Q_1$, $P_2$, $Q_2$ which are not mandatory), the PowSyBl validation will consider the results as inconsistent, unless `ok-missing-values` was set to `true` by the user on purpose to make the consistency -check more lenient. +check more leniently. -In case the voltages are available but not the powers, the results completion feature of the PowSyBl validation -can be used to recompute them using the validation equations (meaning that the branch validation tests will always be OK, so that it allows to perform the bus validation tests). +In case the voltages are available but not the powers, the result completion feature of the PowSyBl validation +can be used to recompute them using the validation equations (meaning that the branch validation tests will always be OK, so that it allows performing the bus validation tests). -### Three-windings transformers -To be implemented, based on a conversion into 3 two-windings transformers. +### Three-winding transformers +To be implemented, based on a conversion into 3 two-winding transformers. ### Generators @@ -212,7 +212,7 @@ $$ $$ In the PowSyBl validation, there are a few tricks to handle special cases: -- if $minQ > maxQ$, then the values are switched to recover a meaningfull interval if `noRequirementIfReactiveBoundInversion = false` +- if $minQ > maxQ$, then the values are switched to recover a meaningful interval if `noRequirementIfReactiveBoundInversion = false` - in case of a missing value, the corresponding test is OK - $minQ$ and $maxQ$ are function of $P$. If $targetP$ is outside $[minP, maxP]$, no test is done. @@ -252,8 +252,8 @@ $$\sum_{\text{stations}}{P} = \sum_{\text{stations}}{Loss} + Loss_{cable}$$ To check a steady-state has been reached, an upper bound of the deadband value is needed. Generally, the value of the deadband is not available in data models. Usual load flow solvers simply consider a continuous tap that is rounded -afterwards. As a result, one should compute an upper bound of the effect of the rounding. Under the usual situation where -the low voltage (side one) is controlled, the maximum effect is expected if the high voltage is fixed (usually it decreases) +afterward. As a result, one should compute an upper bound of the effect of the rounding. Under the usual situation where +the low voltage (side one) is controlled, the maximum effect is expected if the high voltage is fixed (usually it decreases), and if the network connected to the low voltage is an antenna. If the transformer is perfect, the equations are: - With the current tap `tap`, and if the regulated side is side `TWO`: @@ -277,17 +277,17 @@ $$ $$ Finally, we check that the voltage deviation $$\text{deviation} = V_2(tap) - targetV2$$ stays inside the deadband. -- If $deviation < 0$, meaning that the voltage is too low, it should be checked if the deviation would be smaller by -increasing V2, i.e. the following condition should be satisfied: $$\left| deviation \right| < down deadband + threshold$$ -- If $$deviation > 0$$, meaning that the voltage is too high, it should be checked if the deviation would be smaller by -decreasing V2, i.e. the following condition should be satisfied: $$deviation < up deadband + threshold$$ +- If $deviation < 0$, meaning that the voltage is too low, it should be checked if the deviation is smaller by +increasing V2, i.e., the following condition should be satisfied: $$\left| deviation \right| < down deadband + threshold$$ +- If $$deviation > 0$$, meaning that the voltage is too high, it should be checked if the deviation is smaller by +decreasing V2, i.e., the following condition should be satisfied: $$deviation < up deadband + threshold$$ -The test is done only if the regulated voltage is on one end of the transformer and it always returns OK if the controlled voltage is remote. +The test is done only if the regulated voltage is on one end of the transformer, and it always returns OK if the controlled voltage is remote. ## Examples ### Example 1 -The following example shows how to run a loadflow validation on a UCTE network model: +The following example shows how to run a load flow validation on a UCTE network model: ``` $> itools loadflow-validation --case-file 20170322_1844_SN3_FR2.uct --output-folder /tmp/results ``` @@ -306,7 +306,7 @@ Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation typ Eventually, you will find in your output-folder one csv file for each validation type. ### Example 2 -In this example we are comparing results of two validation: before and after load flow computation. Two additional +In this example, we are comparing results of two validations: before and after load flow computation. Two additional arguments are needed: - `load-flow` - `compare_results`: COMPUTATION diff --git a/docs/user/itools/loadflow.md b/docs/user/itools/loadflow.md index 5b0bc890efe..53e54a00c55 100644 --- a/docs/user/itools/loadflow.md +++ b/docs/user/itools/loadflow.md @@ -1,6 +1,6 @@ # iTools loadflow -The `loadflow` command loads a grid file and run a [load flow](../../simulation/loadflow/index.md) simulation. At the end, the results and the modified network can be exported to files. +The `loadflow` command loads a grid file and run a [load flow](../../simulation/loadflow/index.md) simulation. In the end, the results and the modified network can be exported to files. ## Usage ``` @@ -88,7 +88,7 @@ Components results: +------------------+-----------+-----------------+--------------+--------------------+ ``` -The following example shows how to run a power flow simulation, using a parameters file: +The following example shows how to run a power flow simulation, using a parameter file: ``` $> itools loadflow --case-file case.xiidm --parameters-file loadflowparameters.json loadflow results: diff --git a/docs/user/itools/run-script.md b/docs/user/itools/run-script.md index bd24b64b79d..f44be8905cb 100644 --- a/docs/user/itools/run-script.md +++ b/docs/user/itools/run-script.md @@ -21,7 +21,7 @@ Available arguments are: This option defines the path of the script to execute. Current, only Groovy scripts are supported. ## Groovy extensions -The `run-script` command relies on a [plugin mechanism]() to load extensions. Those extensions provide utility functions to make the usage of PowSyBl easier through the scripts. It avoids the user to write boilerplate code hiding the technical complexity of framework into more user-friendly functions. PowSyBl provides the following extensions to: +The `run-script` command relies on a [plugin mechanism]() to load extensions. Those extensions provide utility functions to make the usage of PowSyBl easier through the scripts. It prevents the user from writing boilerplate code and hides the technical complexity of the framework in more user-friendly functions. PowSyBl provides the following extensions to: - [load a network from a file](#load-a-network) - [save a network to a file](#save-a-network) - [run a power flow simulation](#run-a-power-flow) diff --git a/docs/user/itools/security-analysis.md b/docs/user/itools/security-analysis.md index 32fa2d1c529..0e705313f73 100644 --- a/docs/user/itools/security-analysis.md +++ b/docs/user/itools/security-analysis.md @@ -1,6 +1,6 @@ # iTools security-analysis -The `security-analysis` command loads a grid file and run a [security analysis](../../simulation/security/index.md) simulation, to detect security violations on pre- or post-contingencies states. At the end of the simulation the results are printed or exported to a file. +The `security-analysis` command loads a grid file and run a [security analysis](../../simulation/security/index.md) simulation, to detect security violations on pre- or post-contingencies states. At the end of the simulation, the results are printed or exported to a file. ## Usage ``` @@ -45,7 +45,7 @@ This option defines the path of the case file on which the power flow simulation ### Optional arguments `--contingencies-file` -This option defines the path of the contingencies files. If this parameter is not set, the security violations are checked on the base state only. This file is a groovy script that respects the [contingency DSL](../../simulation/security/contingency-dsl.md) syntax. +This option defines the path of the contingency files. If this parameter is not set, the security violations are checked on the base state only. This file is a groovy script that respects the [contingency DSL](../../simulation/security/contingency-dsl.md) syntax. `--external` TODO: Use this argument to run the security analysis as an external process. @@ -55,7 +55,7 @@ This option defines the path of the contingencies files. If this parameter is no This option defines the path of the importer's configuration file. It's possible to overload one or many parameters using the `-I property=value` syntax. The list of supported properties depends on the [input format](../../grid_exchange_formats/index.md). `--limit-types` -This option allows to filter certain types of violations. It overrides the default configuration defined in the [limit-violation-default-filter](../configuration/limit-violation-default-filter.md) configuration module. The supported types are the following: `CURRENT`, `LOW_VOLTAGE`, `HIGH_VOLTAGE`, `LOW_SHORT_CIRCUIT_CURRENT`, `HIGH_SHORT_CIRCUIT_CURRENT` and `OTHER`. +This option allows filtering certain types of violations. It overrides the default configuration defined in the [limit-violation-default-filter](../configuration/limit-violation-default-filter.md) configuration module. The supported types are the following: `CURRENT`, `LOW_VOLTAGE`, `HIGH_VOLTAGE`, `LOW_SHORT_CIRCUIT_CURRENT`, `HIGH_SHORT_CIRCUIT_CURRENT` and `OTHER`. `--log-file` TODO @@ -70,7 +70,7 @@ This option defines the format of the output file. This option is required if th This option defines the path of the [parameters](#parameters) file of the simulation. If this option is not used, the simulation is run with the default parameters. `--with-extensions` -This option defines the list of extensions to complete the simulation results with additional data. This list of available extensions are listed in the usage of the command. +This option defines the list of extensions to complete the simulation results with additional data. The available extensions are listed in the usage of the command. ## Simulators TODO @@ -87,7 +87,7 @@ This option defines the list of extensions to complete the simulation results wi ## Examples ### Example 1 -The following example shows how to run a security analysis simulation to detect only pre-contingency violations, for a given network: +The following example shows how to run a security analysis simulation to detect only pre-contingency violations for a given network: ``` $> itools security-analysis --case-file 20170322_1844_SN3_FR2.uct ``` @@ -104,7 +104,7 @@ Pre-contingency violations: ``` ### Example 2 -The following example shows how to run a security analysis simulation to detect the post-contingency violations status of given network and a set of contingencies. +The following example shows how to run a security analysis simulation to detect the post-contingency violations status of a given network and a set of contingencies. **Content of the contingencies.groovy file:**`` ``` From 306472817c61c04cd66fc3439b5abfd05e43554f Mon Sep 17 00:00:00 2001 From: Coline Piloquet <55250145+colinepiloquet@users.noreply.github.com> Date: Wed, 11 Sep 2024 11:25:17 +0200 Subject: [PATCH 6/7] Add anchors in the documentation (#3126) Signed-off-by: Coline PILOQUET --- docs/grid_exchange_formats/ampl/export.md | 1 + docs/grid_exchange_formats/cgmes/export.md | 18 ++++++++++ docs/grid_exchange_formats/cgmes/import.md | 33 +++++++++++++++++++ docs/grid_exchange_formats/iidm/export.md | 1 + docs/grid_exchange_formats/iidm/import.md | 1 + docs/grid_exchange_formats/iidm/index.md | 2 ++ docs/grid_exchange_formats/psse/import.md | 12 +++++-- .../ucte/format_specification.md | 1 + docs/grid_exchange_formats/ucte/import.md | 10 ++++-- docs/grid_features/import_post_processor.md | 3 ++ docs/grid_features/loadflow_validation.md | 11 +++++++ docs/simulation/shortcircuit/parameters.md | 2 +- docs/user/itools/index.md | 2 ++ 13 files changed, 92 insertions(+), 5 deletions(-) diff --git a/docs/grid_exchange_formats/ampl/export.md b/docs/grid_exchange_formats/ampl/export.md index fe015b58f1c..49d2587d3d6 100644 --- a/docs/grid_exchange_formats/ampl/export.md +++ b/docs/grid_exchange_formats/ampl/export.md @@ -1,6 +1,7 @@ # Export TODO +(ampl-export-options)= ## Options These properties can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) module. diff --git a/docs/grid_exchange_formats/cgmes/export.md b/docs/grid_exchange_formats/cgmes/export.md index 33c52979b80..5c30e44e3a5 100644 --- a/docs/grid_exchange_formats/cgmes/export.md +++ b/docs/grid_exchange_formats/cgmes/export.md @@ -25,6 +25,7 @@ If the dependencies have to be updated automatically (see parameter **iidm.expor The output filenames will follow the pattern `_.xml`. The basename is determined from the parameters, or the basename of the export data source or the main network name. +(cgmes-cgm-quick-export)= ## CGM (Common Grid Model) quick export When exporting a CGM, we need an IIDM network (CGM) that contains multiple subnetworks (one for each IGM). @@ -72,6 +73,7 @@ exampleBase_SV.xml where the updated SSH files will supersede the original ones, and the SV will contain the correct dependencies of new SSH and original TPs. +(cgmes-cgm-manual-export)= ## CGM (Common Grid Model) manual export If you want to intervene in how the updated IGM SSH files or the CGM SV are exported, you can make multiple calls to the CGMES export function. @@ -155,18 +157,21 @@ Remember that, in addition to setting the info for metadata models in the IIDM e The following sections describe in detail how each supported PowSyBl network model object is converted to CGMES network components. +(cgmes-battery-export)= ### Battery PowSyBl [`Battery`](../../grid_model/network_subnetwork.md#battery) is exported as `SynchronousMachine` with `HydroGeneratingUnit`. TODO details +(cgmes-busbar-section-export)= ### BusbarSection PowSyBl [`BusbarSection`](../../grid_model/network_subnetwork.md#busbar-section) is exported as CGMES `BusbarSection`. TODO details +(cgmes-dangling-line-export)= ### DanglingLine PowSyBl [`DanglingLine`](../../grid_model/network_subnetwork.md#dangling-line) is exported as several CGMES network objects. @@ -174,6 +179,7 @@ Each dangling line will be exported as one `EquivalentInjection` and one `ACLine TODO details +(cgmes-generator-export)= ### Generator PowSyBl [`Generator`](../../grid_model/network_subnetwork.md#generator) is exported as CGMES `SynchronousMachine`. @@ -189,24 +195,28 @@ generator has the extension [`RemoteReactivePowerControl`](../../grid_model/exte with the `enabled` activated and the generator attribute `voltageRegulatorOn` set to `false`. In all other cases, a `RegulatingControl` is exported with `RegulatingControl.mode` set to `RegulatingControlModeKind.voltage`. +(cgmes-hvdc-export)= ### HVDC line and HVDC converter stations A PowSyBl [`HVDCLine`](../../grid_model/network_subnetwork.md#hvdc-line) and its two [`HVDCConverterStations`](../../grid_model/network_subnetwork.md#hvdc-converter-station) are exported as a `DCLineSegment` with two `DCConverterUnits`. TODO details +(cgmes-line-export)= ### Line PowSyBl [`Line`](../../grid_model/network_subnetwork.md#line) is exported as `ACLineSegment`. TODO details +(cgmes-load-export)= ### Load PowSyBl [`Load`](../../grid_model/network_subnetwork.md#load) is exported as `ConformLoad`, `NonConformLoad` or `EnergyConsumer` depending on the extension [`LoadDetail`](../../grid_model/extensions.md#load-detail). TODO details +(cgmes-shunt-compensator-export)= ### Shunt compensator PowSyBl [`ShuntCompensator`](../../grid_model/network_subnetwork.md#shunt-compensator) is exported as `LinearShuntCompensator` or `NonlinearShuntCompensator` depending on their models. @@ -220,6 +230,7 @@ A shunt compensator with local voltage control (i.e., the regulating terminal is and no valid voltage target will not have any exported regulating control. In all other cases, a `RegulatingControl` is exported with `RegulatingControl.mode` set to `RegulatingControlModeKind.voltage`. +(cgmes-static-var-compensator-export)= ### StaticVarCompensator PowSyBl [`StaticVarCompensator`](../../grid_model/network_subnetwork.md#static-var-compensator) is exported as `StaticVarCompensator`. @@ -238,18 +249,21 @@ to `RegulatingControlModeKind.voltage` when the static VAR compensator mode is ` is `OFF`, the exported regulating control mode will be reactive power only if the voltage target is not valid but the reactive power target is. Otherwise, the exported mode will be voltage. +(cgmes-substation-export)= ### Substation PowSyBl [`Substation`](../../grid_model/network_subnetwork.md#substation) is exported as `Substation`. TODO details +(cgmes-switch-export)= ### Switch PowSyBl [`Switch`](../../grid_model/network_subnetwork.md#breakerswitch) is exported as CGMES `Breaker`, `Disconnector` or `LoadBreakSwitch` depending on its `SwitchKind`. TODO details +(cgmes-three-winding-transformer-export)= ### ThreeWindingsTransformer PowSyBl [`ThreeWindingsTransformer`](../../grid_model/network_subnetwork.md#three-winding-transformer) is exported as `PowerTransformer` with three `PowerTransformerEnds`. @@ -270,12 +284,14 @@ In a `PhaseTapChanger`, the `TapChangerControl` is exported with `RegulatingCont `PhaseTapChanger` `regulationMode` is set to `ACTIVE_POWER_CONTROL`, and with `RegulatingControl.mode` set to `RegulatingControlModeKind.currentFlow` when `PhaseTapChanger` `regulationMode` is set to `CURRENT_LIMITER`. +(cgmes-two-winding-transformer-export)= ### TwoWindingsTransformer PowSyBl [`TwoWindingsTransformer`](../../grid_model/network_subnetwork.md#two-winding-transformer) is exported as `PowerTransformer` with two `PowerTransformerEnds`. Tap changer controls for two-winding transformers are exported following the same rules explained in the previous section about three-winding transformers. See [tap changer control](#tap-changer-control). +(cgmes-voltage-level-export)= ### Voltage level PowSyBl [`VoltageLevel`](../../grid_model/network_subnetwork.md#voltage-level) is exported as `VoltageLevel`. @@ -284,12 +300,14 @@ PowSyBl [`VoltageLevel`](../../grid_model/network_subnetwork.md#voltage-level) i ## Extensions +(cgmes-control-areas-export)= ### Control areas PowSyBl [`ControlAreas`](import.md#cgmes-control-areas) are exported as several `ControlArea`. TODO details +(cgmes-export-options)= ## Options These properties can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) module. diff --git a/docs/grid_exchange_formats/cgmes/import.md b/docs/grid_exchange_formats/cgmes/import.md index 3ef15fd9534..a9ca9aef94e 100644 --- a/docs/grid_exchange_formats/cgmes/import.md +++ b/docs/grid_exchange_formats/cgmes/import.md @@ -7,6 +7,7 @@ The CIM-CGMES importer reads and converts a CIM-CGMES model to the PowSyBl grid The data in input CIM/XML files uses RDF (Resource Description Framework) syntax. In RDF, data is described making statements about resources using triplet expressions: (subject, predicate, object). To describe the conversion from CGMES to PowSyBl, we first introduce some generic considerations about the level of detail of the model (node/breaker or bus/branch), the identity of the equipments and equipment containment in substations and voltage levels. After that, the conversion for every CGMES relevant class is explained. Consistency checks and validations performed during the conversion are mentioned in the corresponding sections. +(cgmes-import-level-of-detail)= ## Levels of detail: node/breaker and bus/branch CGMES models defined at node/breaker level of detail will be mapped to PowSyBl node/breaker topology level. CGMES models defined at bus/branch level will be mapped to PowSyBl bus/breaker topology level. @@ -23,12 +24,14 @@ Some equipment, like switches, lines or transformers, have more than one point o In PowSyBl, a `Node` can have zero or one terminal. In CGMES, the `ConnectivityNode` objects may have more than one associated terminal. To be able to represent this in PowSyBl, the conversion process will automatically create internal connections between the PowSyBl nodes that represent equipment connections and the nodes created to map `ConnectivityNode` objects. +(cgmes-id-import)= ## Identity of model equipments Almost all the equipments of the PowSyBl grid model require a unique identifier `Id` and may optionally have a human-readable `Name`. Whenever possible, these attributes will be directly copied from original CGMES attributes. Terminals are used by CGMES and PowSyBl to define the points of connection of the equipment to the network. CGMES terminals have unique identifiers. PowSyBl does not allow terminals to have an associated identifier. Information about original CGMES terminal identifiers is stored in each PowSyBl object using aliases. +(cgmes-substation-voltage-level-import)= ## Equipment containers: substations and voltage levels The PowSyBl grid model establishes the substation as a required container of voltage levels and transformers (two- and three-winding transformers and phase shifters). Voltage levels are the required container of the rest of the network equipment, except for the AC and DC transmission lines that establish connections between substations and are directly associated with the network model. All buses at the transformer ends should be kept in the same substation. @@ -39,12 +42,14 @@ The CGMES model does not guarantee these hierarchical constraints, so the first The following sections describe in detail how each supported CGMES network object is converted to PowSyBl network model objects. +(cgmes-substation-import)= ### Substation For each substation (considering only the representative substation if they are connected by transformers) in the CGMES model a new substation is created in the PowSyBl grid model with the following attributes created as such: - `Country` It is obtained from the `regionName` property as a first option, from `subRegionName` as second option. Otherwise, is assigned to `null`. - `GeographicalTags` It is obtained from the `SubRegion` property. +(cgmes-voltage-level-import)= ### VoltageLevel As for substations, for each voltage level (considering only the representative voltage level if they are connected by switches) in the CGMES model, a new voltage level is created in the PowSyBl grid model with the following attributes created as such: @@ -53,6 +58,7 @@ As for substations, for each voltage level (considering only the representative - `LowVoltageLimit` It is copied from the `lowVoltageLimit` property. - `HighVoltageLimit` It is copied from the `highVoltageLimit` property. +(cgmes-connectivity-node-import)= ### ConnectivityNode If the CGMES model is a node/breaker model then `ConnectivityNode` objects are present in the CGMES input files, and for each of them a new `Node` is created in the corresponding PowSyBl voltage level. A `Node` in the PowSyBl model is an integer identifier that is unique by voltage level. @@ -61,6 +67,7 @@ If the import option `iidm.import.cgmes.create-busbar-section-for-every-connecti - Identity attributes `Id` and `Name` are copied from the `ConnectivityNode`. - `Node` The same `Node` assigned to the mapped `ConnectivityNode`. +(cgmes-topological-node-import)= ### TopologicalNode If the CGMES model is defined at bus/branch detail, then `TopologicalNode` objects are used in the conversion, and for each of them a `Bus` is created in the PowSyBl grid model inside the corresponding voltage level container, at the PowSyBl bus/breaker topology level. The created `Bus` has the following attributes: @@ -68,6 +75,7 @@ If the CGMES model is defined at bus/branch detail, then `TopologicalNode` objec - `V` The voltage of the `TopologicalNode` is copied if it is valid (greater than `0`). - `Angle` The angle the `TopologicalNode` is copied if the previous voltage is valid. +(cgmes-busbar-section-import)= ### BusbarSection Busbar sections can be created in PowSyBl grid model only at node/breaker level. @@ -76,6 +84,7 @@ CGMES Busbar sections are mapped to PowSyBl busbar sections only if CGMES is nod - Identity attributes `Id` and `Name` are copied from the CGMES `BusbarSection`. - `Node` A new `Node` in the corresponding voltage level. +(cgmes-energy-consumer-import)= ### EnergyConsumer Every `EnergyConsumer` in the CGMES model creates a new `Load` in PowSyBl. The attributes are created as such: @@ -95,6 +104,7 @@ When the type is a non-conform load: - `withVariableActivePower` is set to `0`. - `withVariableReactivePower` is set to `0`. +(cgmes-energy-source-import)= ### EnergySource An `EnergySource` is a generic equivalent for an energy supplier, with the injection given using load sign convention. @@ -103,6 +113,7 @@ For each `EnergySource` object in the CGMES model a new PowSyBl `Load` is create - `P0`, `Q0` set from `SSH` or `SV` values depending on which are defined. - `LoadType` It will be `FICTITIOUS` if the `Id` of the `energySource` contains the pattern `fict`. Otherwise `UNDEFINED`. +(cgmes-sv-injection-import)= ### SvInjection CGMES uses `SvInjection` objects to report mismatches on calculated buses: they record the calculated bus injection minus the sum of the terminal flows. According to the documentation, the values will thus follow generator sign convention: positive sign means injection into the bus. Note that all the reference cases used for development follow load sign convention to report these mismatches, so we have decided to follow this load sign convention as a first approach. @@ -112,6 +123,7 @@ For each `SvInjection` in the CGMES network model a new PowSyBl `Load` with attr - `LoadType` is always set to `FICTITIOUS`. - `Fictitious` is set to `true`. +(cgmes-equivalent-injection-import)= ### EquivalentInjection The mapping of an `EquivalentInjection` depends on its location relative to the boundary area. @@ -128,6 +140,7 @@ Attributes of the PowSyBl generator or of the PowSyBl dangling line generation a - `VoltageRegulatorOn` It is assigned to `true` if both properties, `regulationCapability` and `regulationStatus` are `true` and the terminal is connected. - `EnergySource` is set to `OTHER`. +(cgmes-ac-line-segment-import)= ### ACLineSegment `ACLineSegments`' mapping depends on its location relative to the boundary area. @@ -170,6 +183,7 @@ If the `ACLineSegment` is mapped to a paired PowSyBl [`DanglingLine`](../../grid - `B2` is `0.0` is the dangling line is on side `TWO` of the Tie Line. If the dangling line is on side `ONE` of the Tie Line, it is copied from CGMES `bch`. - `PairingKey` is copied from the name of the `TopologicalNode` or the `ConnectivityNode` (respectively in `NODE-BREAKER` or `BUS-BRANCH`) inside boundaries +(cgmes-equivalent-branch-import)= ### EquivalentBranch Equivalent branches mapping depends on its location relative to the boundary area. @@ -203,6 +217,7 @@ If the `EquivalentBranch` is mapped to a PowSyBl [`DanglingLine`](../../grid_mod - `P0` is copied from CGMES `P` of the terminal at boundary side - `Q0` is copied from CGMES `Q` of the terminal at boundary side +(cgmes-asynchronous-machine-import)= ### AsychronousMachine Asynchronous machines represent rotating machines whose shaft rotates asynchronously with the electrical field. @@ -212,6 +227,7 @@ An `AsynchronousMachine` is mapped to a PowSyBl [`Load`](../../grid_model/networ - `P0`, `Q0` are set from CGMES values taken from `SSH` or `SV`data depending on which are defined. If there is no defined data, it is `0.0`. - `LoadType` is `FICTITIOUS` if the CGMES ID contains "fict". Otherwise, it is `UNDEFINED`. +(cgmes-synchronous-machine-import)= ### SynchronousMachine Synchronous machines represent rotating machines whose shaft rotates synchronously with the electrical field. @@ -236,6 +252,7 @@ A `SynchronousMachine` is mapped to a PowSyBl [`Generator`](../../grid_model/net TODO normalPF +(cgmes-equivalent-shunt-import)= ### EquivalentShunt An `EquivalentShunt` is mapped to a PowSyBl linear [`ShuntCompensator`](../../grid_model/network_subnetwork.md#shunt-compensator). A linear shunt compensator has banks or sections with equal admittance values. @@ -244,6 +261,7 @@ Its attributes are created as described below: - `BPerSection` is copied from CGMES `b` - `MaximumSectionCount` is set to `1` +(cgmes-external-network-injection-import)= ### ExternalNetworkInjection External network injections are injections representing the flows from an entire external network. @@ -258,6 +276,7 @@ An `ExternalNetworkinjection` is mapped to a PowSyBl [`Generator`](../../grid_mo TODO regulation +(cgmes-linear-shunt-compensator-import)= ### LinearShuntCompensator Linear shunt compensators represent shunt compensators with banks or sections with equal admittance values. @@ -270,6 +289,7 @@ The created PowSyBl shunt compensator is linear, and its attributes are defined TODO regulation +(cgmes-nonlinear-shunt-compensator-import)= ### NonlinearShuntCompensator Non-linear shunt compensators represent shunt compensators with banks or section admittance values that differ. @@ -283,9 +303,11 @@ Sections are created from the lowest CGMES `sectionNumber` to the highest and ea TODO regulation +(cgmes-operational_limit-import)= ### OperationalLimit TODO +(cgmes-power-transformer-import)= ### PowerTransformer Power transformers represent electrical devices consisting of two or more coupled windings, each represented by a `PowerTransformerEnd`. PowSyBl only supports `PowerTransformers` with two or three windings. @@ -322,6 +344,7 @@ Please note that in this case, if `PowerTransformerEnds` are in different substa For more information about this conversion, please look at the classes [`InterpretedT3xModel`](https://github.com/powsybl/powsybl-core/blob/main/cgmes/cgmes-conversion/src/main/java/com/powsybl/cgmes/conversion/elements/transformers/InterpretedT3xModel.java) and [`ConvertedT3xModel`](https://github.com/powsybl/powsybl-core/blob/main/cgmes/cgmes-conversion/src/main/java/com/powsybl/cgmes/conversion/elements/transformers/ConvertedT3xModel.java). +(cgmes-series-compensator-import)= ### SeriesCompensator Series compensators represent series capacitors or reactors or AC transmission lines without charging susceptance. @@ -334,6 +357,7 @@ If a `SeriesCompensator` has its ends inside different voltage levels, it is map - `X` is copied from CGMES `x` - `G1`, `G2`, `B1` and `B2` are set to `0` +(cgmes-static-var-compensator-import)= ### StaticVarCompensator Static VAR compensators represent a facility for providing variable and controllable shunt reactive power. @@ -346,6 +370,7 @@ A PowSyBl [`VoltagePerReactivePowerControl`](../../grid_model/extensions.md#volt TODO regulation +(cgmes-switch-import)= ### Switch (Switch, Breaker, Disconnector, LoadBreakSwitch, ProtectedSwitch, GroundDisconnector) Switches, breakers, disconnectors, load break switches, protected switches and ground disconnectors are @@ -381,6 +406,7 @@ If the CGMES `Switch` is mapped to a PowSyBl [`DanglingLine`](../../grid_model/n The CIM-CGMES format contains more information than what the `iidm` grid model needs for calculation. The additional data that are needed to export a network in CIM-CGMES format are stored in several extensions. +(cgmes-control-areas-import)= ### CGMES control areas This extension models all the control areas contained in the network as modeled in CIM-CGMES. @@ -404,6 +430,7 @@ It is possible to retrieve a control area by its ID. It is also possible to iter This extension is provided by the `com.powsybl:powsybl-cgmes-extensions` module. +(cgmes-dangling-line-boundary-node-import)= ### CGMES dangling line boundary node This extension is used to add some CIM-CGMES characteristics to dangling lines. @@ -416,6 +443,7 @@ This extension is used to add some CIM-CGMES characteristics to dangling lines. This extension is provided by the `com.powsybl:powsybl-cgmes-extensions` module. +(cgmes-line-boundary-node-import)= ### CGMES line boundary node This extension is used to add some CIM-CGMES characteristics to tie lines. @@ -427,20 +455,25 @@ This extension is used to add some CIM-CGMES characteristics to tie lines. This extension is provided by the `com.powsybl:powsybl-cgmes-extensions` module. +(cgmes-tap-changers-import)= ### CGMES Tap Changers TODO +(cgmes-metadata-model-import)= ### CGMES metadata model TODO +(cgmes-cim-characteristics-import)= ### CIM characteristics TODO +(cgmes-model-import)= ### CGMES model +(cgmes-import-options)= ## Options These properties can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md) module. diff --git a/docs/grid_exchange_formats/iidm/export.md b/docs/grid_exchange_formats/iidm/export.md index 92a783b2d65..5d2b5f6195c 100644 --- a/docs/grid_exchange_formats/iidm/export.md +++ b/docs/grid_exchange_formats/iidm/export.md @@ -2,6 +2,7 @@ TODO +(iidm-export-options)= ## Options These properties can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) module. diff --git a/docs/grid_exchange_formats/iidm/import.md b/docs/grid_exchange_formats/iidm/import.md index 16392f31df1..9259a22b935 100644 --- a/docs/grid_exchange_formats/iidm/import.md +++ b/docs/grid_exchange_formats/iidm/import.md @@ -2,6 +2,7 @@ TODO +(iidm-import-options)= ## Options These properties can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) module. diff --git a/docs/grid_exchange_formats/iidm/index.md b/docs/grid_exchange_formats/iidm/index.md index d90d736f70b..ea04c69f517 100644 --- a/docs/grid_exchange_formats/iidm/index.md +++ b/docs/grid_exchange_formats/iidm/index.md @@ -18,6 +18,7 @@ Below are two exports from the same network: - one XML export (XIIDM exchange format) - one JSON export (JIIDM exchange format) +(xiidm)= ## XIIDM ```xml @@ -64,6 +65,7 @@ Below are two exports from the same network: ``` +(jiidm)= ## JIIDM ```json { diff --git a/docs/grid_exchange_formats/psse/import.md b/docs/grid_exchange_formats/psse/import.md index fdfc85d0625..cad323b5a93 100644 --- a/docs/grid_exchange_formats/psse/import.md +++ b/docs/grid_exchange_formats/psse/import.md @@ -7,12 +7,14 @@ The import module reads and converts a PSS®E power flow data file to the PowSyB First, input data is obtained by reading and parsing the input file, and as a result, a PSS®E model is created in memory. This model can be viewed as a set of Java classes where each data block of the PSS®E model is associated with a specific Java class that describes all their attributes or data items. Then, some inconsistency checks are performed on this model. If the validation succeeds, the PSS®E model is converted to a PowSyBl grid model. +(psse-import-options)= ## Options Parameters for the import can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) module. **psse.import.ignore-base-voltage** The `psse.import.ignore-base-voltage` property is an optional property that defines if the importer should ignore the base voltage information present in the PSS®E file. The default value is `false`. +(psse-inconsistency-checks)= ## Inconsistency checks -TODO @@ -37,6 +39,7 @@ Every voltage level is assigned to its corresponding substation, with attributes The following sections describe in detail how each supported PSS®E data block is converted to PowSyBl network model objects. +(psse-bus-data-conversion)= ### _Bus Data_ There is a one-to-one correspondence between the records of the PSS®E _Bus Data_ block and the buses of the PowSyBl network model. For each record in the _Bus Data_ block a PowSyBl bus is created and assigned to its corresponding voltage level with the following attributes: @@ -46,6 +49,7 @@ There is a one-to-one correspondence between the records of the PSS®E _Bus Data - **Angle** is copied from the PSS®E bus voltage phase angle, `VA`. +(psse-load-data-conversion)= ### _Load Data_ Every _Load Data_ record represents one load. Multiple loads are allowed at the same bus by specifying one _Load Data_ record with the same bus and different load identifiers. Each record defines a new load in the PowSyBl grid model associated with its corresponding voltage level and with the following attributes: @@ -59,6 +63,7 @@ The load is connected to the ConnectableBus if load status (field `STATUS` in th PSS®E supports loads with three different characteristics: Constant Power, Constant Current and Constant Admittance. The current version only takes into consideration the Constant Power component, discarding the Constant Current component (fields `IP` and `IQ` in the _Load Data_ record) and the Constant Admittance component (fields `YP` and `YQ` in the _Load Data_ record). +(psse-fixed-bus-shunt-data-conversion)= ### _Fixed Bus Shunt Data_ Each _Fixed Bus Shunt Data_ record defines a PowSyBl shunt compensator with a linear model and a single section. It is possible to define multiple fixed shunts at the same bus. The PowSyBl shunt compensator is associated with its corresponding voltage level and has the following attributes: @@ -73,6 +78,7 @@ Each _Fixed Bus Shunt Data_ record defines a PowSyBl shunt compensator with a li The shunt compensator is connected to the ConnectableBus if fixed shunt status (field `STATUS` in the _Fixed Bus Shunt Data_ record) is `1` (In-service). +(psse-switched-shunt-data-conversion)= ### _Switched Shunt Data_ In the PSS®E version 33, only one switched shunt element can be defined on each bus. Version 35 allows multiple switched shunts on the same bus, adding an alphanumeric switched shunt identifier. @@ -103,6 +109,7 @@ When the adjustment method `ADJM` is `0`, the behaviour of the switched shunt ca If the adjustment method `ADJM` is `1`, the reactor and capacitor blocks can be specified at any order, and all the switching combinations are considered in PSS®E. Current conversion does not support building a separate section for each switching combination. To map the PSS@E shunt blocks/steps into PowSyBl sections, first the reactor and capacitor blocks are increasingly ordered by susceptance (field `BI` in the _Switched Shunt Data_ record) and then sections are created like in the previous adjustment considering that blocks are switched on following the sorted order. +(psse-generator-data-conversion)= ### _Generator Data_ Every _Generator Data_ single line record represents one generator. Multiple generators are allowed at a PSS®E bus by specifying the same bus and a different identifier. Each record defines a new generator in the PowSyBl grid model associated with its corresponding voltage level and with the following attributes: @@ -120,7 +127,7 @@ Every _Generator Data_ single line record represents one generator. Multiple gen The generator is connected to the ConnectableBus if generator status (field `STAT` in the _Generator Data_ record) is `1` (In-service). - +(psse-branch-data-conversion)= ### _Non-Transformer Branch Data_ In PSS®E each AC transmission line is represented as a non-transformer branch record and defines a new line in the PowSyBl grid model with the following attributes: @@ -140,7 +147,7 @@ The line is connected at both ends if the branch status (field `ST` in the _Non- A set of current permanent limits is defined as `1000.0` * `rateMva` / (`sqrt(3.0)` * `vnom1`) at the end `1` and `1000.0` * `rateMva` / (`sqrt(3.0)` * `vnom2`) at the end `2` where `rateMva` is the first rating of the branch (field `RATEA` in version 33 of the _Non-Transformer Branch Data_ record and field `RATE1` in version 35) and `vnom1` and `vnom2` are the nominal voltages of the associated voltage levels. - +(psse-transformer-data-conversion)= ### _Transformer Data_ The _Transformer Data_ block defines two- and three-winding transformers. Two-winding transformers have four line records, while three-winding transformers have five line records. A `0` value in the field `K` of the _Transformer Data_ record first line is used to indicate that is a two-winding transformer, otherwise is considered a three-winding transformer. @@ -222,6 +229,7 @@ When a three-winding transformer is modeled, the two-winding transformer steps s ![ThreeWindingsTransformerModels](img/three-winding-transformer-model.svg){width="100%" align=center class="only-light"} ![ThreeWindingsTransformerModels](img/dark_mode/three-winding-transformer-model.svg){width="100%" align=center class="only-dark"} +(psse-slack-bus-conversion)= ### Slack bus The buses defined as slack terminal are the buses with type code `3` (field `IDE` in the _Bus Data_ record). diff --git a/docs/grid_exchange_formats/ucte/format_specification.md b/docs/grid_exchange_formats/ucte/format_specification.md index 6b1b5c9c846..c513d46566e 100644 --- a/docs/grid_exchange_formats/ucte/format_specification.md +++ b/docs/grid_exchange_formats/ucte/format_specification.md @@ -13,6 +13,7 @@ Each block is introduced by a key line consisting of the two characters `##` and The grid is described in Bus/Branch topology, and only a few types of equipment are supported (nodal injections, AC line, two-winding transformer). Fictitious nodes are located at the electric middle of each tie line. The defined X-nodes are binding for all users. +(ucte-file-name-convention)= ## File name convention The UCTE-DEF format use the following file name convention: `___.uct` with: - `yyyymmdd`: year, month and day diff --git a/docs/grid_exchange_formats/ucte/import.md b/docs/grid_exchange_formats/ucte/import.md index f2a1bd3f3a9..5e484fa9b28 100644 --- a/docs/grid_exchange_formats/ucte/import.md +++ b/docs/grid_exchange_formats/ucte/import.md @@ -8,7 +8,7 @@ The UCTE parser provided by PowSyBl does not support the blocks `##TT` and `##E` description of the two-winding transformers and the scheduled active power exchange between countries. Those blocks are ignored during the parsing step. - +(ucte-import-options)= ## Options Parameters for the import can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) module. @@ -31,6 +31,7 @@ considered as [area](../../grid_model/network_subnetwork.md#area) DC boundaries. The default value is an empty list. For more details see further below about [area conversion](#area-conversion). +(ucte-inconsistency-checks)= ## Inconsistency checks Once the UCTE grid model is created in memory, a consistency check is performed on the different elements (nodes, lines, two-winding transformers and regulations). @@ -102,6 +103,7 @@ Notations: ## From UCTE to IIDM The UCTE file name is parsed to extract metadata required to initialize the IIDM network, such as its ID, the case date and the forecast distance. +(ucte-node-conversion)= ### Node conversion There is no equivalent [voltage level](../../grid_model/network_subnetwork.md#voltage-level) or [substation](../../grid_model/network_subnetwork.md#substation) concept in the UCTE-DEF format, so we have to create substations and voltage levels from the node description and the topology. @@ -132,6 +134,7 @@ The power plant type is converted to an [energy source]() value (see the mapping The list of the power plant types is more detailed than the list of available [energy source]() types in IIDM, so we add the `powerPlantType` property to each generator to keep the initial value. +(ucte-line-conversion)= ### Line conversion The busbar couplers connecting two real nodes are converted into a [switch](../../grid_model/network_subnetwork.md#breakerswitch). This switch is open or closed depending on the status of the coupler. In the UCTE-DEF format, the coupler can have extra information not supported in IIDM we keep @@ -151,6 +154,7 @@ In IIDM, a dangling line is a line segment connected to a constant load. The sum of the active load and generation (rep. reactive) is computed to initialize the `P0` (resp. `Q0`) of the dangling line. The element name of the UCTE line is stored in the `elementName` property and the geographical name of the X-node is stored in the `geographicalName` property. +(ucte-two-winding-transformer-conversion)= ### Two-winding transformer conversion The two-winding transformers connected between two real nodes are converted into a [two-winding transformer](../../grid_model/network_subnetwork.md#two-winding-transformer). If the current limits are defined, a permanent limit is created only for the second side. @@ -164,13 +168,14 @@ except for the reactance that is set to $0.05\space\Omega$. **TODO**: insert a schema - +(ucte-phase-regulation-conversion)= #### Phase regulation If a phase regulation is defined for a transformer, it is converted into a [ratio tap changer](../../grid_model/additional.md#ratio-tap-changer). If the voltage setpoint is defined, the ratio tap changer will regulate the voltage to this setpoint. The regulating terminal is assigned to the first side of the transformer. The ρ of each step is calculated according to the following formula: $\rho = 1 / (1 + i * \delta U / 100)$. +(ucte-angle-regulation-conversion)= #### Angle regulation If an angle regulation is defined for a transformer, it is converted into a [phase tap changer](../../grid_model/additional.md#phase-tap-changer), with a `FIXED_TAP` regulation mode. ρ and α of each step are calculated according to the following formulas: @@ -198,6 +203,7 @@ $$ **Note:** The sign of $\alpha$ is changed because the phase tap changer is on side 2 in UCTE-DEF, and on side 1 in IIDM. +(ucte-area-conversion)= ### Area conversion When the [`ucte.import.create-areas` option](#ucteimportcreate-areas) is set to `true` (default), the importer will create diff --git a/docs/grid_features/import_post_processor.md b/docs/grid_features/import_post_processor.md index ec19a6825cb..d2ad055832f 100644 --- a/docs/grid_features/import_post_processor.md +++ b/docs/grid_features/import_post_processor.md @@ -6,6 +6,7 @@ PowSyBl provides 2 different implementations of post-processors: - [Groovy](#groovy-post-processor): to execute a groovy script - [LoadFlow](#loadflow-post-processor): to run a power flow simulation +(groovy-post-processor)= ## Groovy post-processor This post-processor executes a groovy script, loaded from a file. The script can access to the network and the [computation manager]() using the variables `network` and `computationManager`. To use this post-processor, add the `com.powsybl:powsybl-iidm-scripting` dependency to your classpath, and configure both `import` and `groovy-post-processor` modules: @@ -37,6 +38,7 @@ The following example prints meta-information from the network: println "Network " + network.getId() + " (" + network.getSourceFormat()+ ") is imported" ``` +(loadflow-post-processor)= ## LoadFlow post-processor Mathematically speaking, a [load flow](../simulation/loadflow/index) result is fully defined by the complex voltages at each node. The consequence is that most load flow algorithms converge very fast if they are initialized with voltages. As a result, it happens that load flow results include only voltages and not flows on branches. This post-processors computes the flows given the voltages. The equations (Kirchhoff law) used are the same as the one used in the [load flow validation](../user/itools/loadflow-validation.md#load-flow-results-validation) to compute $P_1^{\text{calc}}$, $Q_1^{\text{calc}}$, $P_2^{\text{calc}}$, $Q_2^{\text{calc}}$ for branches and $P_3^{\text{calc}}$, $Q_3^{\text{calc}}$ in addition for three-winding transformers. @@ -58,6 +60,7 @@ import: **Note:** This post-processor relies on the [load flow results completion]() module. +(geographical-data-import-post-processor)= ## Geographical data import post-processor One way to add geographical positions on a network is to use the import post-processor named odreGeoDataImporter, that will automatically add the [LinePosition](../grid_model/extensions.md#line-position) and [SubstationPosition](../grid_model/extensions.md#substation-position) extensions to the network model. diff --git a/docs/grid_features/loadflow_validation.md b/docs/grid_features/loadflow_validation.md index 3a5cb4989ad..bbf2c78e458 100644 --- a/docs/grid_features/loadflow_validation.md +++ b/docs/grid_features/loadflow_validation.md @@ -4,6 +4,7 @@ A load flow result is considered *acceptable* if it describes a feasible steady- More practically, generations of practitioners have set quasi-standard ways to describe them that makes it possible to define precise rules. They are described below for the different elements of the network. +(loadflow-validation-buses)= ## Buses The first law of Kirchhoff must be satisfied for every bus for active and reactive power: @@ -13,6 +14,7 @@ $$\begin{equation} \left| \sum_{branches} Q + \sum_{injections} Q \right| \leq \epsilon \\ \end{equation}$$ +(loadflow-validation-branches)= ## Branches Lines and two-winding transformers are converted into classical PI models: @@ -40,9 +42,11 @@ Thanks to Kirchhoff laws (see the [line](../grid_model/network_subnetwork.md#lin $(P_1^{calc}, Q_1^{calc}, P_2^{calc}, Q_2^{calc}) = f(\text{Voltages}, \text{Characteristics})$ +(loadflow-validation-three-winding-transformers)= ## Three-winding transformers To be implemented, based on a conversion into 3 two-winding transformers. +(loadflow-validation-generators)= ## Generators ### Active power @@ -89,9 +93,11 @@ V - targetV & < & -& \epsilon && \& && |Q-maxQ| & \leq & \epsilon \\ targetV - V & < && \epsilon && \& && |Q-minQ| & \leq & \epsilon \\ \end{align*} +(loadflow-validation-loads)= ## Loads To be implemented, with tests similar to generators with voltage regulation. +(loadflow-validation-shunts)= ## Shunts A shunt is expected not to generate or absorb active power: @@ -100,6 +106,7 @@ $\left| P \right| < \epsilon$ A shunt is expected to generate reactive power according to the number of activated sections and to the susceptance per section $B$: $\left| Q + \text{#sections} * B V^2 \right| < \epsilon$ +(loadflow-validation-static-var-compensators)= ## Static VAR Compensators Static VAR Compensators behave like generators producing zero active power except that their reactive bounds are expressed in susceptance, so that they are voltage dependent. @@ -111,16 +118,20 @@ $targetP = 0$ MW - If the regulation mode is `VOLTAGE`, it behaves like a generator with voltage regulation with the following bounds (dependent on the voltage, which is not the case for generators): $minQ = - Bmax * V^2$ and $maxQ = - Bmin V^2$ +(loadflow-validation-hvdc)= ## HVDC lines To be done. +(loadflow-validation-vsc)= ## VSC VSC converter stations behave like generators with the additional constraints that the sum of active power on converter stations paired by a cable is equal to the losses on the converter stations plus the losses on the cable. +(loadflow-validation-lcc)= ## LCC To be done. +(loadflow-validation-transformers-ratio-tap-changer)= ## Transformers with a ratio tap changer Transformers with a ratio tap changer have a tap with a finite discrete number of positions that allows to change their transformer ratio. diff --git a/docs/simulation/shortcircuit/parameters.md b/docs/simulation/shortcircuit/parameters.md index 110c9f67af5..6f53f70e9c4 100644 --- a/docs/simulation/shortcircuit/parameters.md +++ b/docs/simulation/shortcircuit/parameters.md @@ -129,7 +129,7 @@ Here is an example of this JSON file: ] ```` - +(shortcircuit-fault-parameters)= ## FaultParameters It is possible to override parameters for each fault by creating an instance of `com.powsybl.shortcircuit.FaultParameters`. This object will take the fault to which it applies and all the parameters diff --git a/docs/user/itools/index.md b/docs/user/itools/index.md index 2d5a2898e05..03f68c50b11 100644 --- a/docs/user/itools/index.md +++ b/docs/user/itools/index.md @@ -42,6 +42,7 @@ Available commands are: `--config-name` Use this option to overload the default base name for the configuration file. It overrides the [powsybl_config_name](#powsybl_config_name) property defined in the `itools.conf` file. +(itools-configuration)= ### Configuration The `iTools` script reads its configuration from the `/etc/itools.conf` [property file](https://en.wikipedia.org/wiki/.properties). The properties defined in this file are used to configure the Java Virtual Machine. @@ -85,6 +86,7 @@ Sometimes, it could be useful for a user to have its own logging configuration t ``` +(itools-available-commands)= ## Available commands The `iTools` script relies on a [plugin mechanism](): the commands are discovered at runtime and depend on the jars present in the `share/java` folder. From 8aff9a331ec5df6dfb0998e7e701e5b65cfec717 Mon Sep 17 00:00:00 2001 From: rcourtier <129156292+rcourtier@users.noreply.github.com> Date: Mon, 16 Sep 2024 08:28:28 +0200 Subject: [PATCH 7/7] Fix CGM export dependencies issues (#3128) Signed-off-by: Romain Courtier --- .../powsybl/cgmes/conversion/CgmesExport.java | 44 ++++++++---- .../export/CommonGridModelExportTest.java | 72 ++++++++++++++++--- docs/grid_exchange_formats/cgmes/export.md | 6 +- 3 files changed, 94 insertions(+), 28 deletions(-) diff --git a/cgmes/cgmes-conversion/src/main/java/com/powsybl/cgmes/conversion/CgmesExport.java b/cgmes/cgmes-conversion/src/main/java/com/powsybl/cgmes/conversion/CgmesExport.java index d64e9d0650f..1fa2f960162 100644 --- a/cgmes/cgmes-conversion/src/main/java/com/powsybl/cgmes/conversion/CgmesExport.java +++ b/cgmes/cgmes-conversion/src/main/java/com/powsybl/cgmes/conversion/CgmesExport.java @@ -107,14 +107,16 @@ public void export(Network network, Properties parameters, DataSource dataSource private void exportCGM(Network network, DataSource dataSource, CgmesExportContext context) { checkCgmConsistency(network, context); - // Initialize models for export. The original IGM TP and SSH don't get exported, + // Initialize models for export. The original IGM EQ, SSH, TP and TP_BD don't get exported, // but we need to init their models to retrieve their IDs when building the dependencies. Map igmModels = new HashMap<>(); for (Network subnetwork : network.getSubnetworks()) { IgmModelsForCgm igmModelsForCgm = new IgmModelsForCgm( - initializeModelForExport(subnetwork, CgmesSubset.STEADY_STATE_HYPOTHESIS, context, false, false), initializeModelForExport(subnetwork, CgmesSubset.STEADY_STATE_HYPOTHESIS, context, false, true), - initializeModelForExport(subnetwork, CgmesSubset.TOPOLOGY, context, false, false) + initializeModelForExport(subnetwork, CgmesSubset.EQUIPMENT, context, false, false), + initializeModelForExport(subnetwork, CgmesSubset.STEADY_STATE_HYPOTHESIS, context, false, false), + initializeModelForExport(subnetwork, CgmesSubset.TOPOLOGY, context, false, false), + initializeModelForExport(subnetwork, CgmesSubset.TOPOLOGY_BOUNDARY, context, false, false) ); igmModels.put(subnetwork, igmModelsForCgm); } @@ -122,7 +124,7 @@ private void exportCGM(Network network, DataSource dataSource, CgmesExportContex // Update dependencies if (context.updateDependencies()) { - updateDependenciesCGM(igmModels.values(), updatedCgmSvModel); + updateDependenciesCGM(igmModels.values(), updatedCgmSvModel, context.getBoundaryTpId()); } // Export the SSH for the IGMs and the SV for the CGM @@ -227,22 +229,29 @@ public static CgmesMetadataModel initializeModelForExport( } /** - * Update cross dependencies between the subset models through the dependentOn relationship. - * The IGMs updated SSH supersede the original ones. - * The CGM updated SV depends on the IGMs updated SSH and on the IGMs original TP. - * @param igmModels For each IGM: the original SSH model, the updated SSH model and the original TP model. + * Update cross dependencies between the subset models (including boundaries) through the dependentOn relationship. + * The IGMs updated SSH supersede the original ones and depend on the original EQ. Other dependencies are kept. + * The CGM updated SV depends on the IGMs updated SSH and on the IGMs original TP and TP_BD. + * @param igmModels For each IGM: the updated SSH model and the original SSH, TP and TP_BD models. * @param updatedCgmSvModel The SV model for the CGM. + * @param boundaryTpId The model id for the TP_BD subset. */ - private void updateDependenciesCGM(Collection igmModels, CgmesMetadataModel updatedCgmSvModel) { + private void updateDependenciesCGM(Collection igmModels, CgmesMetadataModel updatedCgmSvModel, String boundaryTpId) { + // Each updated SSH model depends on the original EQ model + igmModels.forEach(m -> m.updatedSsh.addDependentOn(m.originalEq.getId())); + // Each updated SSH model supersedes the original one - // Clear previous dependencies - igmModels.forEach(m -> m.updatedSsh.clearDependencies()); igmModels.forEach(m -> m.updatedSsh.clearSupersedes()); igmModels.forEach(m -> m.updatedSsh.addSupersedes(m.originalSsh.getId())); - // Updated SV model depends on updated SSH models and original TP models + // Updated SV model depends on updated SSH models and original TP and TP_BD models updatedCgmSvModel.addDependentOn(igmModels.stream().map(m -> m.updatedSsh.getId()).collect(Collectors.toSet())); updatedCgmSvModel.addDependentOn(igmModels.stream().map(m -> m.originalTp.getId()).collect(Collectors.toSet())); + if (boundaryTpId != null) { + updatedCgmSvModel.addDependentOn(boundaryTpId); + } else { + updatedCgmSvModel.addDependentOn(igmModels.stream().map(m -> m.originalTpBd.getId()).collect(Collectors.toSet())); + } } /** @@ -492,14 +501,19 @@ private String getBaseName(CgmesExportContext context, DataSource dataSource, Ne * when setting the relationships (dependOn, supersedes) between them in a CGM export. */ private static class IgmModelsForCgm { - CgmesMetadataModel originalSsh; CgmesMetadataModel updatedSsh; + CgmesMetadataModel originalEq; + CgmesMetadataModel originalSsh; CgmesMetadataModel originalTp; + CgmesMetadataModel originalTpBd; - public IgmModelsForCgm(CgmesMetadataModel originalSsh, CgmesMetadataModel updatedSsh, CgmesMetadataModel originalTp) { - this.originalSsh = originalSsh; + public IgmModelsForCgm(CgmesMetadataModel updatedSsh, CgmesMetadataModel originalEq, CgmesMetadataModel originalSsh, + CgmesMetadataModel originalTp, CgmesMetadataModel originalTpBd) { this.updatedSsh = updatedSsh; + this.originalEq = originalEq; + this.originalSsh = originalSsh; this.originalTp = originalTp; + this.originalTpBd = originalTpBd; } } diff --git a/cgmes/cgmes-conversion/src/test/java/com/powsybl/cgmes/conversion/test/export/CommonGridModelExportTest.java b/cgmes/cgmes-conversion/src/test/java/com/powsybl/cgmes/conversion/test/export/CommonGridModelExportTest.java index 47ae912b2ae..26f2917527d 100644 --- a/cgmes/cgmes-conversion/src/test/java/com/powsybl/cgmes/conversion/test/export/CommonGridModelExportTest.java +++ b/cgmes/cgmes-conversion/src/test/java/com/powsybl/cgmes/conversion/test/export/CommonGridModelExportTest.java @@ -140,14 +140,20 @@ void testCgmExportNoModelsNoProperties() throws IOException { String updatedNlSshId = "urn:uuid:Network_NL_N_STEADY_STATE_HYPOTHESIS_2021-02-03T04:30:00Z_2_1D__FM"; String originalBeTpId = "urn:uuid:Network_BE_N_TOPOLOGY_2021-02-03T04:30:00Z_1_1D__FM"; String originalNlTpId = "urn:uuid:Network_NL_N_TOPOLOGY_2021-02-03T04:30:00Z_1_1D__FM"; - Set expectedDependencies = Set.of(updatedBeSshId, updatedNlSshId, originalBeTpId, originalNlTpId); + String originalBeTpBdId = "urn:uuid:Network_BE_N_TOPOLOGY_BOUNDARY_2021-02-03T04:30:00Z_1_1D__FM"; + String originalNlTpBdId = "urn:uuid:Network_NL_N_TOPOLOGY_BOUNDARY_2021-02-03T04:30:00Z_1_1D__FM"; + Set expectedDependencies = Set.of(updatedBeSshId, updatedNlSshId, originalBeTpId, originalNlTpId, originalBeTpBdId, originalNlTpBdId); assertEquals(expectedDependencies, getOccurrences(updatedCgmSvXml, REGEX_DEPENDENT_ON)); - // Each updated IGM SSH should supersede the original one + // Each updated IGM SSH should supersede the original one and depend on the original EQ String originalBeSshId = "urn:uuid:Network_BE_N_STEADY_STATE_HYPOTHESIS_2021-02-03T04:30:00Z_1_1D__FM"; + String originalBeEqId = "urn:uuid:Network_BE_N_EQUIPMENT_2021-02-03T04:30:00Z_1_1D__FM"; String originalNlSshId = "urn:uuid:Network_NL_N_STEADY_STATE_HYPOTHESIS_2021-02-03T04:30:00Z_1_1D__FM"; + String originalNlEqId = "urn:uuid:Network_NL_N_EQUIPMENT_2021-02-03T04:30:00Z_1_1D__FM"; assertEquals(originalBeSshId, getFirstOccurrence(updatedBeSshXml, REGEX_SUPERSEDES)); + assertEquals(originalBeEqId, getFirstOccurrence(updatedBeSshXml, REGEX_DEPENDENT_ON)); assertEquals(originalNlSshId, getFirstOccurrence(updatedNlSshXml, REGEX_SUPERSEDES)); + assertEquals(originalNlEqId, getFirstOccurrence(updatedNlSshXml, REGEX_DEPENDENT_ON)); // Profiles should be consistent with the instance files assertEquals("http://entsoe.eu/CIM/SteadyStateHypothesis/1/1", getFirstOccurrence(updatedBeSshXml, REGEX_PROFILE)); @@ -195,14 +201,17 @@ void testCgmExportWithModelsForSubnetworks() throws IOException { String updatedNlSshId = "urn:uuid:Network_NL_N_STEADY_STATE_HYPOTHESIS_2021-02-03T04:30:00Z_2_1D__FM"; String originalBeTpId = "urn:uuid:Network_BE_N_TOPOLOGY_2021-02-03T04:30:00Z_1_1D__FM"; String originalNlTpId = "urn:uuid:Network_NL_N_TOPOLOGY_2021-02-03T04:30:00Z_1_1D__FM"; - Set expectedDependencies = Set.of(updatedBeSshId, updatedNlSshId, originalBeTpId, originalNlTpId); + String originalTpBdId = "Common TP_BD model ID"; + Set expectedDependencies = Set.of(updatedBeSshId, updatedNlSshId, originalBeTpId, originalNlTpId, originalTpBdId); assertEquals(expectedDependencies, getOccurrences(updatedCgmSvXml, REGEX_DEPENDENT_ON)); - // Each updated IGM SSH should supersede the original one + // Each updated IGM SSH should supersede the original one and depend on the original EQ String originalBeSshId = "urn:uuid:Network_BE_N_STEADY_STATE_HYPOTHESIS_2021-02-03T04:30:00Z_1_1D__FM"; String originalNlSshId = "urn:uuid:Network_NL_N_STEADY_STATE_HYPOTHESIS_2021-02-03T04:30:00Z_1_1D__FM"; assertEquals(originalBeSshId, getFirstOccurrence(updatedBeSshXml, REGEX_SUPERSEDES)); assertEquals(originalNlSshId, getFirstOccurrence(updatedNlSshXml, REGEX_SUPERSEDES)); + assertEquals(Set.of("BE EQ model ID"), getOccurrences(updatedBeSshXml, REGEX_DEPENDENT_ON)); + assertEquals(Set.of("NL EQ model ID"), getOccurrences(updatedNlSshXml, REGEX_DEPENDENT_ON)); // Profiles should be consistent with the instance files assertEquals("http://entsoe.eu/CIM/SteadyStateHypothesis/1/1", getFirstOccurrence(updatedBeSshXml, REGEX_PROFILE)); @@ -254,15 +263,19 @@ void testCgmExportWithModelsForAllNetworks() throws IOException { String updatedNlSshId = "urn:uuid:Network_NL_N_STEADY_STATE_HYPOTHESIS_2022-03-04T05:30:00Z_4_1D__FM"; String originalBeTpId = "urn:uuid:Network_BE_N_TOPOLOGY_2022-03-04T05:30:00Z_1_1D__FM"; String originalNlTpId = "urn:uuid:Network_NL_N_TOPOLOGY_2022-03-04T05:30:00Z_1_1D__FM"; + String originalTpBdId = "Common TP_BD model ID"; String additionalDependency = "Additional dependency"; - Set expectedDependencies = Set.of(updatedBeSshId, updatedNlSshId, originalBeTpId, originalNlTpId, additionalDependency); + Set expectedDependencies = Set.of(updatedBeSshId, updatedNlSshId, originalBeTpId, + originalNlTpId, originalTpBdId, additionalDependency); assertEquals(expectedDependencies, getOccurrences(updatedCgmSvXml, REGEX_DEPENDENT_ON)); - // Each updated IGM SSH should supersede the original one + // Each updated IGM SSH should supersede the original one and depend on the original EQ String originalBeSshId = "urn:uuid:Network_BE_N_STEADY_STATE_HYPOTHESIS_2022-03-04T05:30:00Z_1_1D__FM"; String originalNlSshId = "urn:uuid:Network_NL_N_STEADY_STATE_HYPOTHESIS_2022-03-04T05:30:00Z_1_1D__FM"; assertEquals(originalBeSshId, getFirstOccurrence(updatedBeSshXml, REGEX_SUPERSEDES)); assertEquals(originalNlSshId, getFirstOccurrence(updatedNlSshXml, REGEX_SUPERSEDES)); + assertEquals(Set.of("BE EQ model ID"), getOccurrences(updatedBeSshXml, REGEX_DEPENDENT_ON)); + assertEquals(Set.of("NL EQ model ID"), getOccurrences(updatedNlSshXml, REGEX_DEPENDENT_ON)); // Profiles should be consistent with the instance files // The model of the main network brings an additional profile @@ -288,6 +301,7 @@ void testCgmExportWithProperties() throws IOException { exportParams.put(CgmesExport.MODELING_AUTHORITY_SET, "Regional Coordination Center"); exportParams.put(CgmesExport.MODEL_DESCRIPTION, "Common Grid Model export"); exportParams.put(CgmesExport.MODEL_VERSION, "4"); + exportParams.put(CgmesExport.BOUNDARY_TP_ID, "ENTSOE TP_BD model ID"); String basename = "test_bare+properties"; network.write("CGMES", exportParams, tmpDir.resolve(basename)); String updatedBeSshXml = Files.readString(tmpDir.resolve(basename + "_BE_SSH.xml")); @@ -314,14 +328,19 @@ void testCgmExportWithProperties() throws IOException { String updatedNlSshId = "urn:uuid:Network_NL_N_STEADY_STATE_HYPOTHESIS_2021-02-03T04:30:00Z_4_1D__FM"; String originalBeTpId = "urn:uuid:Network_BE_N_TOPOLOGY_2021-02-03T04:30:00Z_1_1D__FM"; String originalNlTpId = "urn:uuid:Network_NL_N_TOPOLOGY_2021-02-03T04:30:00Z_1_1D__FM"; - Set expectedDependencies = Set.of(updatedBeSshId, updatedNlSshId, originalBeTpId, originalNlTpId); + String originalTpBdId = "ENTSOE TP_BD model ID"; + Set expectedDependencies = Set.of(updatedBeSshId, updatedNlSshId, originalBeTpId, originalNlTpId, originalTpBdId); assertEquals(expectedDependencies, getOccurrences(updatedCgmSvXml, REGEX_DEPENDENT_ON)); - // Each updated IGM SSH should supersede the original one + // Each updated IGM SSH should supersede the original one and depend on the original EQ String originalBeSshId = "urn:uuid:Network_BE_N_STEADY_STATE_HYPOTHESIS_2021-02-03T04:30:00Z_1_1D__FM"; + String originalBeEqId = "urn:uuid:Network_BE_N_EQUIPMENT_2021-02-03T04:30:00Z_1_1D__FM"; String originalNlSshId = "urn:uuid:Network_NL_N_STEADY_STATE_HYPOTHESIS_2021-02-03T04:30:00Z_1_1D__FM"; + String originalNlEqId = "urn:uuid:Network_NL_N_EQUIPMENT_2021-02-03T04:30:00Z_1_1D__FM"; assertEquals(originalBeSshId, getFirstOccurrence(updatedBeSshXml, REGEX_SUPERSEDES)); + assertEquals(originalBeEqId, getFirstOccurrence(updatedBeSshXml, REGEX_DEPENDENT_ON)); assertEquals(originalNlSshId, getFirstOccurrence(updatedNlSshXml, REGEX_SUPERSEDES)); + assertEquals(originalNlEqId, getFirstOccurrence(updatedNlSshXml, REGEX_DEPENDENT_ON)); // Profiles should be consistent with the instance files assertEquals("http://entsoe.eu/CIM/SteadyStateHypothesis/1/1", getFirstOccurrence(updatedBeSshXml, REGEX_PROFILE)); @@ -347,6 +366,7 @@ void testCgmExportWithModelsAndProperties() throws IOException { exportParams.put(CgmesExport.MODELING_AUTHORITY_SET, "Regional Coordination Center"); exportParams.put(CgmesExport.MODEL_DESCRIPTION, "Common Grid Model export"); exportParams.put(CgmesExport.MODEL_VERSION, "4"); + exportParams.put(CgmesExport.BOUNDARY_TP_ID, "ENTSOE TP_BD model ID"); String basename = "test_bare+models+properties"; network.write("CGMES", exportParams, tmpDir.resolve(basename)); String updatedBeSshXml = Files.readString(tmpDir.resolve(basename + "_BE_SSH.xml")); @@ -375,15 +395,19 @@ void testCgmExportWithModelsAndProperties() throws IOException { String updatedNlSshId = "urn:uuid:Network_NL_N_STEADY_STATE_HYPOTHESIS_2022-03-04T05:30:00Z_4_1D__FM"; String originalBeTpId = "urn:uuid:Network_BE_N_TOPOLOGY_2022-03-04T05:30:00Z_1_1D__FM"; String originalNlTpId = "urn:uuid:Network_NL_N_TOPOLOGY_2022-03-04T05:30:00Z_1_1D__FM"; + String originalTpBdId = "ENTSOE TP_BD model ID"; // the parameter prevails on the extension String additionalDependency = "Additional dependency"; - Set expectedDependencies = Set.of(updatedBeSshId, updatedNlSshId, originalBeTpId, originalNlTpId, additionalDependency); + Set expectedDependencies = Set.of(updatedBeSshId, updatedNlSshId, originalBeTpId, + originalNlTpId, originalTpBdId, additionalDependency); assertEquals(expectedDependencies, getOccurrences(updatedCgmSvXml, REGEX_DEPENDENT_ON)); - // Each updated IGM SSH should supersede the original one + // Each updated IGM SSH should supersede the original one and depend on the original EQ String originalBeSshId = "urn:uuid:Network_BE_N_STEADY_STATE_HYPOTHESIS_2022-03-04T05:30:00Z_1_1D__FM"; String originalNlSshId = "urn:uuid:Network_NL_N_STEADY_STATE_HYPOTHESIS_2022-03-04T05:30:00Z_1_1D__FM"; assertEquals(originalBeSshId, getFirstOccurrence(updatedBeSshXml, REGEX_SUPERSEDES)); assertEquals(originalNlSshId, getFirstOccurrence(updatedNlSshXml, REGEX_SUPERSEDES)); + assertEquals(Set.of("BE EQ model ID"), getOccurrences(updatedBeSshXml, REGEX_DEPENDENT_ON)); + assertEquals(Set.of("NL EQ model ID"), getOccurrences(updatedNlSshXml, REGEX_DEPENDENT_ON)); // Profiles should be consistent with the instance files, CGM SV has an additional profile assertEquals("http://entsoe.eu/CIM/SteadyStateHypothesis/1/1", getFirstOccurrence(updatedBeSshXml, REGEX_PROFILE)); @@ -647,6 +671,20 @@ private void addModelsForSubnetworks(Network network, int version) { .addSupersedes("BE SSH previous ID") .addProfile("http://entsoe.eu/CIM/SteadyStateHypothesis/1/1") .add() + .newModel() + .setId("BE EQ model ID") + .setSubset(CgmesSubset.EQUIPMENT) + .setVersion(1) + .setModelingAuthoritySet("http://elia.be/CGMES/2.4.15") + .addProfile("http://entsoe.eu/CIM/EquipmentCore/3/1") + .add() + .newModel() + .setId("Common TP_BD model ID") + .setSubset(CgmesSubset.TOPOLOGY_BOUNDARY) + .setVersion(1) + .setModelingAuthoritySet("http://www.entsoe.eu/OperationalPlanning") + .addProfile("http://entsoe.eu/CIM/TopologyBoundary/3/1") + .add() .add(); network.getSubnetwork("Network_NL") .newExtension(CgmesMetadataModelsAdder.class) @@ -659,6 +697,20 @@ private void addModelsForSubnetworks(Network network, int version) { .addSupersedes("NL SSH previous ID") .addProfile("http://entsoe.eu/CIM/SteadyStateHypothesis/1/1") .add() + .newModel() + .setId("NL EQ model ID") + .setSubset(CgmesSubset.EQUIPMENT) + .setVersion(1) + .setModelingAuthoritySet("http://tennet.nl/CGMES/2.4.15") + .addProfile("http://entsoe.eu/CIM/EquipmentCore/3/1") + .add() + .newModel() + .setId("Common TP_BD model ID") + .setSubset(CgmesSubset.TOPOLOGY_BOUNDARY) + .setVersion(1) + .setModelingAuthoritySet("http://www.entsoe.eu/OperationalPlanning") + .addProfile("http://entsoe.eu/CIM/TopologyBoundary/3/1") + .add() .add(); } diff --git a/docs/grid_exchange_formats/cgmes/export.md b/docs/grid_exchange_formats/cgmes/export.md index 5c30e44e3a5..b8121191c1f 100644 --- a/docs/grid_exchange_formats/cgmes/export.md +++ b/docs/grid_exchange_formats/cgmes/export.md @@ -39,8 +39,8 @@ If a version number is given as a parameter, it is used for the exported files. The quick CGM export will always write updated SSH files for IGMs and a single SV for the CGM. The parameter for selecting which profiles to export is ignored in this kind of export. If the dependencies have to be updated automatically (see parameter **iidm.export.cgmes.update-dependencies** below), the exported instance files will contain metadata models where: -* Updated SSH for IGMs supersede the original ones. -* Updated SV for the CGM depends on the updated SSH from IGMs and on the original TP from IGMs. +* Updated SSH for IGMs supersede the original ones, and depend on the original EQ from IGMs. +* Updated SV for the CGM depends on the updated SSH from IGMs and on the original TP and TP_BD from IGMs. The filenames of the exported instance files will follow the pattern: * For the CGM SV: `_SV.xml`. @@ -71,7 +71,7 @@ exampleBase_NL_SSH.xml exampleBase_SV.xml ``` -where the updated SSH files will supersede the original ones, and the SV will contain the correct dependencies of new SSH and original TPs. +where the updated SSH files will supersede the original ones and depend on the original EQs, and the SV will contain the correct dependencies of new SSH and original TPs and TP_BD. (cgmes-cgm-manual-export)= ## CGM (Common Grid Model) manual export