diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml new file mode 100644 index 00000000000..934aaacee03 --- /dev/null +++ b/docs/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +build: + os: ubuntu-20.04 + tools: + python: "3.9" + +sphinx: + configuration: docs/conf.py + +python: + install: + - requirements: docs/requirements.txt \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000000..4d15385e8a5 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,27 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + + +clean: + @echo "Removing $(SOURCEDIR)/reference/api" + @rm -rf "$(SOURCEDIR)/reference/api" + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000000..687db4142e0 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,11 @@ +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. + +To build the docs locally, run the following commands: +~~~bash +pip install -r docs/requirements.txt +sphinx-build -a docs ./build-docs +~~~ +Then open `build-docs/index.html` in your browser. \ No newline at end of file diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 00000000000..2ea6b5c3fed Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/_static/logos/logo_lfe_powsybl.svg b/docs/_static/logos/logo_lfe_powsybl.svg new file mode 100644 index 00000000000..37450078ff6 --- /dev/null +++ b/docs/_static/logos/logo_lfe_powsybl.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000000..53d01fa6462 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,98 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +# Path to python sources, for doc generation on readthedocs +source_path = os.path.abspath('..') +sys.path.insert(0, source_path) +print(f'appended {source_path}') + + +# -- Project information ----------------------------------------------------- + +project = 'powsybl core' +copyright = '2024, RTE (http://www.rte-france.com)' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.viewcode', + 'sphinx.ext.doctest', + 'sphinx.ext.napoleon', + 'sphinx.ext.todo', + 'sphinx.ext.intersphinx', + 'sphinx_tabs.tabs', + 'myst_parser'] +myst_enable_extensions = [ + "amsmath", + "colon_fence", + "dollarmath", + "attrs_inline" +] +myst_heading_anchors = 6 + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "furo" + +html_title = 'core' +html_short_title = 'core' + +html_logo = '_static/logos/logo_lfe_powsybl.svg' +html_favicon = "_static/favicon.ico" + +html_context = { + # TODO : replace next option with "https://powsybl.readthedocs.org" when website is published + "sidebar_logo_href": "https://www.powsybl.org/" +} + +html_theme_options = { + # the following 3 lines enable edit button + "source_repository": "https://github.com/powsybl/powsybl-core/", + "source_branch": "main", + "source_directory": "docs/", +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] +html_css_files = ['styles/styles.css'] + +todo_include_todos = True + +# Links to external documentations : python 3 and pandas +intersphinx_mapping = { +} +intersphinx_disabled_reftypes = ["*"] + +# Generate one file per method +autosummary_generate = True \ No newline at end of file diff --git a/docs/grid_exchange_formats/ampl/ampl.md b/docs/grid_exchange_formats/ampl/ampl.md new file mode 100644 index 00000000000..376564fc95e --- /dev/null +++ b/docs/grid_exchange_formats/ampl/ampl.md @@ -0,0 +1 @@ +# AMPL \ No newline at end of file diff --git a/docs/grid_exchange_formats/cgmes/examples.md b/docs/grid_exchange_formats/cgmes/examples.md new file mode 100644 index 00000000000..4eb1249921d --- /dev/null +++ b/docs/grid_exchange_formats/cgmes/examples.md @@ -0,0 +1,3 @@ +# Examples +Have a look to the [CGMES sample files](https://www.entsoe.eu/Documents/CIM_documents/Grid_Model_CIM/TestConfigurations_packageCASv2.0.zip) +from ENTSO-E Test Configurations for Conformity Assessment Scheme v2.0. \ No newline at end of file diff --git a/docs/grid_exchange_formats/cgmes/export.md b/docs/grid_exchange_formats/cgmes/export.md new file mode 100644 index 00000000000..e2256d20e6a --- /dev/null +++ b/docs/grid_exchange_formats/cgmes/export.md @@ -0,0 +1,205 @@ +# Export + +TODO + +Please note that PowSyBl always exports CGMES networks as CGMES Node/Breaker networks without considering the topology +level of the PowSyBl network. + +## Conversion from PowSyBl grid model to CGMES + +The following sections describe in detail how each supported PowSyBl network model object is converted to CGMES network +components. + +### Battery + +PowSyBl [`Batteries`](../model/index.md#battery) are exported as CGMES `SynchronousMachine` with CGMES `HydroGeneratingUnits`. + +TODO details + +### BusbarSection + +PowSyBl [`BusbarSections`](../model/index.md#busbar-section) are exported as CGMES `BusbarSections`. + +TODO details + +### DanglingLine + +PowSyBl [`DanglingLines`](../model/index.md#dangling-line) are exported as several CGMES network components. +Each dangling line will be exported as one CGMES `EquivalentInjection` and one CGMES `ACLineSegment`. + +TODO details + +### Generator + +PowSyBl [`Generators`](../model/index.md#generator) are exported as CGMES `SynchronousMachines`. + +TODO details + +### HVDC line and HVDC converter stations + +A PowSyBl [`HVDCLine`](../model/index.md#hvdc-line) and its two [`HVDCConverterStations`](../model/index.md#hvdc-converter-station) +are exported as a CGMES `DCLineSegment` and two CGMES `DCConverterUnits`. + +TODO details + +### Line + +PowSyBl [`Lines`](../model/index.md#line) are exported as CGMES `ACLineSegment`. + +TODO details + +### Load + +PowSyBl [`Loads`](../model/index.md#load) are exported as CGMES `ConformLoads`, `NonConformLoads` or `EnergyConsumers` +depending on the extension [`LoadDetail`](../model/extensions.md#load-detail). + +TODO details + +### Shunt compensator + +PowSyBl [`ShuntCompensators`](../model/index.md#shunt-compensator) are exported as CGMES `LinearShuntCompensator` or +`NonlinearShuntCompensator` depending on their models. + +TODO details + +### StaticVarCompensator + +PowSyBl [`StaticVarCompensators`](../model/index.md#static-var-compensator) are exported as CGMES `StaticVarCompensators`. + +TODO details + +### Substation + +PowSyBl [`Substations`](../model/index.md#substation) are exported as CGMES `Substations`. + +TODO details + +### Switch + +PowSyBl [`Switches`](../model/index.md#breakerswitch) are exported as CGMES `Breakers`, `Disconnectors` or `LoadBreakSwitches` depending on its `SwitchKind`. + +TODO details + +### ThreeWindingsTransformer + +PowSyBl [`ThreeWindingsTransformers`](../model/index.md#three-windings-transformer) are exported as CGMES `PowerTransformers` with three CGMES `PowerTransformerEnds`. +TODO details +### TwoWindingsTransformer + +PowSyBl [`TwoWindingsTransformers`](../model/index.md#two-windings-transformer) are exported as CGMES `PowerTransformers` with two CGMES `PowerTransformerEnds`. + +TODO details + +### Voltage level + +PowSybl [`VoltatgeLevels`](../model/index.md#voltage-level) are exported as CGMES `VoltageLevels`. + +TODO details + +## Extensions + +### Control areas + +PowSyBl [`ControlAreas`](../model/extensions.md#cim-cgmes-control-areas) are exported as CGMES `ControlAreas`. + +TODO details + +## 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. + +**iidm.export.cgmes.base-name** +Optional property that defines the base name of the exported files. Exported CGMES files' names will look like this: +``` +_EQ.xml +_TP.xml +_SSH.xml +_SV.xml +``` +By default, the base name is the network's name if it exists, or else the network's ID. + +**iidm.export.cgmes.boundary-eq-id** +Optional property that defines the ID of the EQ-BD model if there is any. +Its default value is `null`: we consider there is no EQ-BD model to consider. + +**iidm.export.cgmes.boundary-tp-id** +Optional property that defines the ID of the TP-BD model if there is any. +Its default value is `null`: we consider there is no TP-BD model to consider. + +**iidm.export.cgmes.cim-version** +Optional property that defines the CIM version number in which the user wants the CGMES files to be exported. +CIM versions 14, 16 and 100 are supported i.e. its valid values are `14`, `16` and `100`. +If not defined, and the network has the extension `CimCharacteristics`, the CIM version will be the one indicated in the extension. If not, its default value is `16`. +CIM version 16 corresponds to CGMES 2.4.15. +CIM version 100 corresponds to CGMES 3.0. + +**iidm.export.cgmes.encode-ids** +Optional property that must be used if IIDM IDs that are not compliant with CGMES requirements are to be used as CGMES IDs. `true` by default. Used for debugging purposes. + +**iidm.export.cgmes.export-boundary-power-flows** +Optional property that defines if power flows at boundary nodes are to be exported in the SV file or not. `true` by default. + +**iidm.export.cgmes.export-power-flows-for-switches** +Optional property that defines if power flows of switches are exported in the SV file. `true` by default. + +**idm.export.cgmes.naming-strategy** +Optional property that defines which naming strategy is used to transform IIDM identifiers to CGMES identifiers. +It can be: +- `identity`: CGMES IDs are the same as IIDM IDs. +- `cgmes`: new CGMES IDs (new master resource identifiers, cim:mRID) are created for IIDM `Identifiables` if the IIDM IDs are not compliant with CGMES requirements. +- `cgmes-fix-all-invalid-ids`: ensures that all CGMES IDs in the export will comply with CGMES requirements, for IIDM `Identifiables`and also for its related objects (tap changers, operational limits, regulating controls, reactive capability curves, ...). + Its default value is `identity`. + +**iidm.export.cgmes.uuid-namespace** +Optional property related to the naming strategy specified in `iidm.export.cgmes.naming-strategy`. When new CGMES IDs have to be generated, a mechanism that ensures creation of new, stable identifiers based on IIDM IDs is used (see [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122)). These new IDs are guaranteed to be unique inside a namespace given by this UUID. By default, it is the name-based UUID fo the text "powsybl.org" in the empty namespace. + +**iidm.export.cgmes.profiles** +Optional property that determines which instance files will be exported. +By default, it is a full CGMES export: the instance files for the profiles EQ, TP, SSH and SV are exported. + +**iidm.export.cgmes.modeling-authority-set** +Optional property allowing to write a custom modeling authority set in the exported file headers. `powsybl.org` by default. +If a Boundary set is given with the property `iidm.import.cgmes.boundary-location` and the network sourcing actor is found inside it, then the modeling authority set will be obtained from the boundary file without the need to set this property. +The sourcing actor can be specified using the parameter `iidm.export.cgmes.sourcing-actor`. + +**iidm.export.cgmes.model-description** +Optional property allowing to write a custom model description in the file headers. +By default, the model description is `EQ model` for the EQ file, `TP model` for the TP file, `SSH model` for the SSH +file and `SV model` for the SV file. + +**iidm.export.cgmes.export-transformers-with-highest-voltage-at-end1** +Optional property defining whether the transformers should be exported with the highest voltage at end 1, even if it might not be the case in the IIDM model. +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 +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 +`iidm.export.cgmes.max-p-mismatch-converged` and `iidm.export.cgmes.max-q-mismatch-converged`. +This property is set to `true` by default. + +**iidm.export.cgmes.max-p-mismatch-converged** +Optional property that defines the threshold below which a bus is considered to be balanced for the load flow status of the `TopologicalIsland` in active power. If the sum of all the active power of the terminals connected to the bus is greater than this threshold, then the load flow is considered to be divergent. Its default value is `0.1`, and it should be used only if the `iidm.export.cgmes.export-load-flow-status` property is set to `true`. + +**iidm.export.cgmes.max-q-mismatch-converged** +Optional property that defines the threshold below which a bus is considered to be balanced for the load flow status of the `TopologicalIsland` in reactive power. If the sum of all the reactive power of the terminals connected to the bus is greater than this threshold, then the load flow is considered to be divergent. Its default value is `0.1`, and it should be used only if the `iidm.export.cgmes.export-load-flow-status` property is set to `true`. + +**iidm.export.cgmes.export-sv-injections-for-slacks** +Optional property to specify if the total mismatch left after power flow calculation at IIDM slack buses should be exported as an SvInjection. +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. +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. + +**iidm.export.cgmes.model-version** +Optional property defining the version of the exported CGMES file. It will be used if the version is not already available in the network. +The version will be written in the header of each exported file and will also be used to generate a unique UUID for the `FullModel` field. +Its default value is 1. + +**iidm.export.cgmes.business-process** +The business process in which the export takes place. This is used to generate unique UUIDs for the EQ, TP, SSH and SV file `FullModel`. +Its default value is `1D`. + diff --git a/docs/grid_exchange_formats/cgmes/format_specification.md b/docs/grid_exchange_formats/cgmes/format_specification.md new file mode 100644 index 00000000000..5e9d4c8abac --- /dev/null +++ b/docs/grid_exchange_formats/cgmes/format_specification.md @@ -0,0 +1,3 @@ +# Format specification + +Current supported versions of CGMES are 2.4.15 and 3.0. To learn more about the standard, read the documents in the [Common Grid Model Exchange Standard (CGMES) Library](https://www.entsoe.eu/digital/cim/cim-for-grid-models-exchange/). diff --git a/docs/grid_exchange_formats/cgmes/import.md b/docs/grid_exchange_formats/cgmes/import.md new file mode 100644 index 00000000000..b57522fd907 --- /dev/null +++ b/docs/grid_exchange_formats/cgmes/import.md @@ -0,0 +1,480 @@ +# Import + +The CGMES importer reads and converts a CGMES model to the PowSyBl grid model. The import process is performed in two steps: +- Read input files into a triplestore +- Convert 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. + +## 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. + +If the model is specified at the bus/breaker level, a `Bus` must be specified for the equipment. + +If the voltage level is built at node/breaker level, a `Node` must be specified when adding the equipment to PowSyBl. The conversion will create a different `Node` in PowSyBl for each equipment connection. + +Using the `Node` or `Bus` information, PowSyBl creates a `Terminal` that will be used to manage the point of connection of the equipment to the network. + +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 CGMES `ConnectivityNode` objects. + +## 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. + +## 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 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. + +## Conversion from CGMES to PowSyBl grid model + +The following sections describe in detail how each supported CGMES network component is converted to PowSyBl network model objects. + +### 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`. +- `GeographicalTags` It is obtained from the `SubRegion` property. + +### VoltageLevel + +As in the 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. +- `HighVoltageLimit` It is copied from the `highVoltageLimit` property. + +### 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. + +If the import option `iidm.import.cgmes.create-busbar-section-for-every-connectivity-node` is `true` an additional busbar section is also created in the same voltage level. This option is used to debug the conversion and facilitate the comparison of the topology present in the CGMES input files and the topology computed by PowSyBl. The attributes of the busbar section are created as such: +- Identity attributes `Id` and `Name` are copied from the `ConnectivityNode`. +- `Node` The same `Node` assigned to the mapped `ConnectivityNode`. + +### TopologicalNode + +If the CGMES model is defined at bus/branch detail, then CGMES `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: +- Identity attributes `Id` and `Name` are copied from the `TopologicalNode`. +- `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. + +### BusbarSection + +Busbar sections can be created in PowSyBl grid model only at node/breaker level. + +CGMES Busbar sections are mapped to PowSyBl busbar sections only if CGMES is node/breaker and the import option `iidm.import.cgmes.create-busbar-section-for-every-connectivity-node` is set to `false`. In this case, a `BusbarSection` is created in the PowSyBl grid model for each `BusbarSection` of the CGMES model, with the attributes created as such: +- Identity attributes `Id` and `Name` are copied from the CGMES `BusbarSection`. +- `Node` A new `Node` in the corresponding voltage level. + +### EnergyConsumer + +Every `EnergyConsumer` object in the CGMES model creates a new `Load` in PowSyBl. The attributes are created as such: +- `P0`, `Q0` are set from CGMES values taken from `SSH`, `SV`, or `EQ` data depending on which are defined. +- `LoadType` It will be `FICTITIOUS` if the `Id` of the `energyConsumer` contains the pattern `fict`. Otherwise `UNDEFINED`. +- `LoadDetail` Additional information about conform and non-conform loads is added as an extension of the `Load` object (for more details about the [extension](../model/extensions.md#load-detail)). + +The `LoadDetail` extension attributes depend on the `type` property of the CGMES `EnergyConsumer`. For a conform load: +- `withFixedActivePower` is always `0`. +- `withFixedReactivePower` is always `0`. +- `withVariableActivePower` is set to the Load `P0`. +- `withVariableReactivePower` is set to the Load `Q0`. + +When the type is a non-conform load: +- `withFixedActivePower` is set to the Load `P0`. +- `withFixedReactivePower` is set to the Load `Q0`. +- `withVariableActivePower` is set to `0`. +- `withVariableReactivePower` is set to `0`. + +### EnergySource + +A CGMES `EnergySource` is a generic equivalent for an energy supplier, with the injection given using load sign convention. + +For each `EnergySource` object in the CGMES model a new PowSyBl `Load` is created, with attributes created as such: +- `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`. + +### 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. + +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`. +- `LoadType` is always set to `FICTITIOUS`. +- `Fictitious` is set to `true`. + +### EquivalentInjection + +The mapping of a CGMES `EquivalentInjection` depends on its location relative to the boundary area. + +If the `EquivalentInjection` is outside the boundary area, it will be mapped to a PowSyBl `Generator`. + +If the `EquivalentInjection` is at the boundary area, its regulating voltage data will be mapped to the generation data inside the PowSyBl `DanglingLine` created at the boundary point and its values for `P`, `Q` will be used to define the DanglingLine `P0`, `Q0`. Please note that the said `DanglingLine` can be created from an [`ACLineSegment`](#aclinesegment), a [`Switch`](#switch-switch-breaker-disconnector-loadbreakswitch-protectedswitch-grounddisconnector), +an [`EquivalentBranch`](#equivalentbranch) or a [`PowerTransformer`](#powertransformer). + +Attributes of the PowSyBl generator or of the PowSyBl dangling line's 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. +- `VoltageRegulatorOn` It is assigned to `true` if both properties, `regulationCapability` and `regulationStatus` are `true` and the terminal is connected. +- `EnergySource` is set to `OTHER`. + +### ACLineSegment + +CGMES `ACLineSegments`' mapping depends on its location relative to the boundary area. + +If the `ACLineSegment` is outside the boundary area, it will be mapped to a PowSyBl [`Line`](../model/index.md#line). + +If the `ACLineSegment` is completely inside the boundary area, if the boundaries are not imported, it is ignored. Otherwise, it is mapped to a PowSyBl [`Line`](../model/index.md#line). + +If the `ACLineSegment` has one side inside the boundary area and one side outside the boundary area, the importer checks if another `ACLineSegment` is linked to the same CGMES [`TopologicalNode`](#TopologicalNode) in the boundary area. +- If it is the only one `ACLineSegment` linked to this `TopologicalNode`, it is mapped to a PowSyBl [`DanglingLine`](../model/index.md#dangling-line). +- If there are one or more other `ACLineSegment` linked to this `TopologicalNode` and they all are in the same `SubGeographicalRegion`, they are all mapped to PowSyBl [`DanglingLines`](../model/index.md#dangling-line). +- If there is exactly one other `ACLineSegment` linked to this `TopologicalNode` in another `SubGeographicalRegion`, they are both mapped to PowSybl [`HalfLines`](../model/index.md#half-line), part of the same PowSyBl [`TieLine`](../model/index.md#tie-line). +- If there are two or more other `ACLineSegment` linked to this `TopologicalNode` in different `SubGeographicalRegions`: + - If there are only two `ACLineSegments` with their boundary terminal connected **and** in different `SubGeographicalRegion`, they are both mapped to PowSybl [`HalfLines`](../model/index.md#half-line), part of the same PowSyBl [`TieLine`](../model/index.md#tie-line) and all other `ACLineSegments` are mapped to PowSyBl [`DanglingLines`](../model/index.md#dangling-line). + - Otherwise, they are all mapped to PowSyBl [`DanglingLines`](../model/index.md#dangling-line). + +If the `ACLineSegment` is mapped to a PowSyBl [`Line`](../model/index.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 +- `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` + +If the `ACLineSegment` is mapped to a PowSyBl [`DanglingLine`](../model/index.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 +- `B` is copied from CGMES `bch` +- `UcteXnodeCode` 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 +- `Q0` is copied from CGMES `Q` of the terminal at boundary side + +If the `ACLineSegment` is mapped to a PowSyBl [`HalfLine`](../model/index.md#half-line): +- `R` is copied from CGMES `r` +- `X` is copied from CGMES `x` +- `G1` is `0.0` is the Half Line is on side `ONE` of the Tie Line. If the Half 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 Half Line is on side `TWO` of the Tie Line. If the Half 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 Half Line is on side `ONE` of the Tie Line. If the Half Line is on side `TWO` of the Tie Line, it is copied from CGMES `bch`. +- `B2` is `0.0` is the Half Line is on side `TWO` of the Tie Line. If the Half Line is on side `ONE` of the Tie Line, it is copied from CGMES `bch`. +- `UcteXnodeCode` is copied from the name of the `TopologicalNode` or the `ConnectivityNode` (respectively in `NODE-BREAKER` or `BUS-BRANCH`) inside boundaries + +### EquivalentBranch + +CGMES `EquivalentBranches`' mapping depends on its location relative to the boundary area. + +If the `EquivalentBranch` is outside the boundary area, it will be mapped to a PowSyBl [`Line`](../model/index.md#line). + +If the `EquivalentBranch` is completely inside the boundary area, if the boundaries are not imported, it is ignored. Otherwise, it is mapped to a PowSyBl [`Line`](../model/index.md#line). + +If the `EquivalentBranch` has one side inside the boundary area and one side outside the boundary area, the importer checks if another `EquivalentBranch` is linked to the same CGMES [`TopologicalNode`](#TopologicalNode) in the boundary area. +- If it is the only one `EquivalentBranch` linked to this `TopologicalNode`, it is mapped to a PowSyBl [`DanglingLine`](../model/index.md#dangling-line). +- If there are one or more other `EquivalentBranch` linked to this `TopologicalNode` and they all are in the same `SubGeographicalRegion`, they are all mapped to PowSyBl [`DanglingLines`](../model/index.md#dangling-line). +- If there is exactly one other `EquivalentBranch` linked to this `TopologicalNode` in another `SubGeographicalRegion`, they are both mapped to PowSybl [`HalfLines`](../model/index.md#half-line), part of the same PowSyBl [`TieLine`](../model/index.md#tie-line). +- If there are two or more other `EquivalentBranches` linked to this `TopologicalNode` in different `SubGeographicalRegions`: + - If there are only two `EquivalentBranches` with their boundary terminal connected **and** in different `SubGeographicalRegion`, they are both mapped to PowSybl [`HalfLines`](../model/index.md#half-line), part of the same PowSyBl [`TieLine`](../model/index.md#tie-line) and all other `EquivalentBranches` are mapped to PowSyBl [`DanglingLines`](../model/index.md#dangling-line). + - Otherwise, they are all mapped to PowSyBl [`DanglingLines`](../model/index.md#dangling-line). + +If the `EquivalentBranch` is mapped to a PowSyBl [`Line`](../model/index.md#line): +- `R` is copied from CGMES `r` +- `X` is copied from CGMES `x` +- `G1` is `0.0` +- `G2` is `0.0` +- `B1` is `0.0` +- `B2` is `0.0` + +If the `EquivalentBranch` is mapped to a PowSyBl [`DanglingLine`](../model/index.md#dangling-line): +- `R` is copied from CGMES `r` +- `X` is copied from CGMES `x` +- `G` is `0.0` +- `B` is `0.0` +- `UcteXnodeCode` 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 +- `Q0` is copied from CGMES `Q` of the terminal at boundary side + +### AsychronousMachine + +CGMES `AsynchronousMachines` represent rotating machines whose shaft rotates asynchronously with the electrical field. +It can be motor or generator; no distinction is made for the conversion of these two types. + +A CGMES `AsynchronousMachine` is mapped to a PowSyBl [`Load`](../model/index.md#load) with attributes created as described below: +- `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`. + +### SynchronousMachine +CGMES `SynchronousMachines` represent rotating machines whose shaft rotates synchronously with the electrical field. +It can be motor or generator; no distinction is made for the conversion of these two types. + +A CGMES `SynchronousMachine` is mapped to a PowSyBl [`Generator`](../model/index.md#generator) with attributes created as described below: +- `MinP` is set from CGMES `GeneratingUnit.minOperatingP` on the `GeneratingUnit` associated with the `SynchronousMachine`. If invalid, `MinP` is `-Double.MAX_VALUE`. +- `MaxP` is set from CGMES `GeneratingUnit.maxOperatingP` on the `GeneratingUnit` associated with the `SynchronousMachine`. If invalid, `MaxP` is `Double.MAX_VALUE`. +- `ratedS` is copied from CGMES `ratedS`. If it is strictly lower than 0, it is considered undefined. +- `EnergySource` is defined from the CGMES `GeneratingUnit` class of the `GeneratingUnit` associated with the `SynchronousMachine` + - If it is a `HydroGeneratingUnit`, `EnergySource` is `HYDRO` + - If it is a `NuclearGeneratingUnit`, `EnergySource` is `NUCLEAR` + - If it is a `ThermalGeneratingUnit`, `EnergySource` is `THERMAL` + - If it is a `WindGeneratingUnit`, `EnergySource` is `WIND` + - If it is a `SolarGeneratingUnit`, `EnergySource` is `SOLAR` + - Else, `EnergySource` is `OTHER` +- `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`. If undefined, `TargetP` is set from CGMES `GeneratingUnit.initialP` from the `GeneratingUnit` associated to the `SynchronousMachine` and `TargetQ` is set to `0`. + +TODO reactive limits + +TODO regulation + +TODO normalPF + +### EquivalentShunt + +A CGMES `EquivalentShunt` is mapped to a PowSyBl linear [`ShuntCompensator`](../model/index.md#shunt-compensator). A linear shunt compensator has banks or sections with equal admittance values. +Its attributes are created as described below: +- `SectionCount` is `1` if the `EquivalentShunt` CGMES `Terminal` is connected, else it is `0`. +- `BPerSection` is copied from CGMES `b` +- `MaximumSectionCount` is set to `1` + +### ExternalNetworkInjection + +CGMES `ExternalNetworkInjections` are injections representing the flows from an entire external network. + +A CGMES `ExternalNetworkinjection` is mapped to a PowSyBl [`Generator`](../model/index.md#generator) with attributes created as described below: +- `MinP` is copied from CGMES `minP` +- `MaxP` is copied from CGMES `maxP` +- `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`. If undefined, they are set to `0`. +- `EnergySource` is set as `OTHER` + +TODO reactive limits + +TODO regulation + +### LinearShuntCompensator + +CGMES `LinearShuntCompensators` represent shunt compensators with banks or sections with equal admittance values. + +A CGMES `LinearShuntCompensator` is mapped to a PowSybl [`ShuntCompensator`](../model/index.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`. + +TODO regulation + +### NonlinearShuntCompensator + +CGMES `NonlinearShuntCompensators` represent shunt compensators with banks or section addmittance values that differs. + +A CGMES `NonlinearShuntCompensator` is mapped to a PowSyBl [`ShuntCompensator`](../model/index.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 CGMES `NonlinearShuntCompensatorPoint` associated with the CGMES `NonlinearShuntCompensator` it is mapped to. + +Sections are created from the lowest CGMES `sectionNumber` to the highest and each section has its attributes created as describe below: +- `B` is calculated as the sum of all CGMES `b` of `NonlinearShuntCompensatorPoints` with `sectionNumber` lower or equal to its `sectionNumber` +- `G` is calculated as the sum of all CGMES `g` of `NonlinearShuntCompensatorPoints` with `sectionNumber` lower or equal to its `sectionNumber` + +TODO regulation + +### OperationalLimit +TODO + +### PowerTransformer +TODO + +### SeriesCompensator + +CGMES `SeriesCompensators` represent series capacitors or reactors or AC transmission lines without charging susceptance. + +If a CGMES `SeriesCompensator` has both its ends inside the same voltage level, it is mapped to a PowSyBl [`Switch`](../model/index.md#breakerswitch). In this case, +all its CGMES electrical attributes are ignored. It is considered as closed, fictitious and, if it is in a node-breaker voltage level, retained. Its `SwitchKind` is `BREAKER`. + +If a CGMES `SeriesCompensator` has its ends inside different voltage levels, it is mapped to a PowSyBl [`Line`](../model/index.md#line) with attributes as described below: +- `R` is copied from CGMES `r` +- `X` is copied from CGMES `x` +- `G1`, `G2`, `B1` and `B2` are set to `0` + +### StaticVarCompensator + +CGMES `StaticVarCompensators` represent a facility for providing variable and controllable shunt reactive power. + +A CGMES `StaticVarCompensator` is mapped to a PowSyBl [`StaticVarCompensator`](../model/index.md#static-var-compensator) with attributes as described below: +- `Bmin` is calculated from CGMES `inductiveRating`: if it is defined and not equals to `0`, `Bmin` is `1 / inductiveRating`. Else, it is `-Double.MAX_VALUE`. +- `Bmax` is calculated from CGMES `capacitiveRating`: if it defined and not equals to `0`, `Bmax` is `1 / capacitiveRating`. Else, it is `Double.MAX_VALUE`. + +A PowSyBl [`VoltagePerReactivePowerControl`](../model/extensions.md#voltage-per-reactive-power-control) extension is also created from the CGMES `StaticVarCompensator` and linked to the PowSyBl `StaticVarCompensator` with its `slope` attribute copied from CGMES `slope` if the latter is `0` or positive. + +TODO regulation + +### Switch (Switch, Breaker, Disconnector, LoadBreakSwitch, ProtectedSwitch, GroundDisconnector) + +CGMES `Switches`, `Breakers`, `Disconnectors`, `LoadBreakSwitches`, `ProtectedSwitches` and `GroundDisconnectors` are +all imported in the same manner. For convenience purpose, we will now use CGMES `Switch` as a say but keep in mind that this section is valid for all these CGMES classes. + +If the CGMES `Switch` has its ends both inside the same voltage level, it is mapped to a PowSyBl [`Switch`](../model/index.md#breakerswitch) with attributes as described below: +- `SwitchKind` is defined depending on the CGMES class + - If it is a CGMES `Breaker`, it is `BREAKER` + - If it is a CGMES `Disconnector`, it is `DISCONNECTOR` + - If it is a CGMES `LoadBreakSwitch`, it is `LOAD_BREAK_SWITCH` + - Otherwise, it is `BREAKER` +- `Retained` is copied from CGMES `retained` if defined in node-breaker. Else, it is `false`. +- `Open` is copied from CGMES SSH `open` if defined. Else, it is copied from CGMES `normalOpen`. If neither are defined, it is `false`. + +If the CGMES `Switch` has its ends in different voltage levels inside the same IGM, it is mapped to a [`Switch`](../model/index.md#breakerswitch) but the voltage levels, and potentially the substations, that contain its ends are merged: they are mapped to only one voltage level and/or substation. +The created PowSyBl `Switch` has its attributes defined as described above. + +If the CGMES `Switch` has one of its end in the boundary area, it is mapped to a PowSybl [`DanglingLine`](../model/index.md#dangling-line) with attributes as described below: +- `R`, `X`, `G`, `B` are `0.0`. +- `UcteXnodeCode` 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 +- `Q0` is copied from CGMES `Q` of the terminal at boundary side + +## 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. + +### CIM-CGMES control areas + +This extension models all the control areas contained in the network as modeled in CIM-CGMES. + +| Attribute | Type | Unit | Required | Default value | Description | +|---------------------|--------------------------------|------|----------|---------------|------------------------------------------| +| CGMES control areas | `Collection` | - | no | - | The list of control areas in the network | + +**CGMES control area** + +| Attribute | Type | Unit | Required | Default value | Description | +|----------------------------------|------------|------|----------|---------------|----------------------------------------------------------| +| ID | String | - | yes | - | The ID of the control area | +| name | String | - | no | - | The name of the control area | +| Energy Identification Code (EIC) | String | - | no | - | The EIC control area | +| net interchange | double | - | no | - | The net interchange of the control area (at its borders) | +| terminals | `Terminal` | - | no | - | Terminals at the border of the control area | +| boundaries | `Boundary` | - | no | - | Boundaries at the border of the control area | + +It is possible to retrieve a control area by its ID. It is also possible to iterate through all control areas. + +This extension is provided by the `com.powsybl:powsybl-cgmes-extensions` module. + +### CIM-CGMES dangling line boundary node + +This extension is used to add some CIM-CGMES characteristics to dangling lines. + + +| Attribute | Type | Unit | Required | Default value | Description | +|---------------------------------------|---------|------|----------|---------------|---------------------------------------------------------------------| +| hvdc status | boolean | - | no | false | Indicates if the boundary line is associated with a DC Xnode or not | +| Line Energy Identification Code (EIC) | String | - | no | - | The EIC of the boundary line if it exists | + +This extension is provided by the `com.powsybl:powsybl-cgmes-extensions` module. + +### CIM-CGMES line boundary node + +This extension is used to add some CIM-CGMES characteristics to tie lines. + +| Attribute | Type | Unit | Required | Default value | Description | +|---------------------------------------|---------|------|----------|---------------|---------------------------------------------------------------------| +| hvdc status | boolean | - | no | false | Indicates if the boundary line is associated with a DC Xnode or not | +| Line Energy Identification Code (EIC) | String | - | no | - | The EIC of the boundary line EIC if it exists | + +This extension is provided by the `com.powsybl:powsybl-cgmes-extensions` module. + +### CIM-CGMES Tap Changers + +TODO + +### CIM-CGMES SSH metadata + +TODO + +### CIM-CGMES SV metadata + +TODO + +### CIM characteristics + +TODO + +## 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. + +**iidm.import.cgmes.boundary-location** +Optional property that defines the directory path where the CGMES importer can find the boundary files (`EQBD` and `TPBD` profiles) if they are not present in the imported zip file. By default, its value is `/CGMES/boundary`. + +**iidm.import.cgmes.change-sign-for-shunt-reactive-power-flow-initial-state** +Optional property that defines if the CGMES importer inverts the sign of active and reactive power flows for shunt compensators. Its default value is `false`. + +**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. + +**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. `false` 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`. + +**iidm.import.cgmes.create-busbar-section-for-every-connectivity-node** +Optional property that defines if the CGMES importer creates an [IIDM Busbar Section](../model/index.md#busbar-section) for each CGMES connectivity node. Used for debugging purposes. `false` by default. + +**iidm.import.cgmes.create-fictitious-switches-for-disconnected-terminals-mode** +Optional property that defines if fictitious switches are created when terminals are disconnected in CGMES node-breaker networks. +Three modes are available: +- `ALWAYS`: fictitious switches are created at every disconnected terminal. +- `ALWAYS_EXCEPT_SWITCHES`: fictitious switches are created at every disconnected terminal that is not a terminal of a switch. +- `NEVER`: no fictitious switches are created at disconnected terminals. + +The default value is `ALWAYS`. + +**iidm.import.cgmes.decode-escaped-identifiers** +Optional property that defines if identifiers containing escaped characters are decoded when CGMES files are read. `true` by default. + +**iidm.import.cgmes.ensure-id-alias-unicity** +Optional property that defines if IDs' and aliases' unicity is ensured during CGMES import. If it is set to `true`, identical CGMES IDs will be modified to be unique. If it is set to `false`, identical CGMES IDs will throw an exception. `false` by default. + +**iidm.import.cgmes.import-control-areas** +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`. + +**iidm.import.cgmes.post-processors** +Optional property that defines all the CGMES post-processors which will be activated after import. +By default, it is an empty list. +One implementation of such a post-processor is available in PowSyBl in the [powsybl-diagram](../../developer/repositories/powsybl-diagram.md) repository, named [CgmesDLImportPostProcessor](#CgmesDLImportPostProcessor). + +**iidm.import.cgmes.powsybl-triplestore** +Optional property that defines which Triplestore implementation is used. Currently, PowSyBl only supports [RDF4J](https://rdf4j.org/). `rdf4j` by default. + +**iidm.import.cgmes.profile-for-initial-values-shunt-sections-tap-positions** +Optional property that defines which CGMES profile is used to initialize tap positions and section counts. It can be `SSH` or `SV`. The default value is `SSH`. + +**iidm.import.cgmes.source-for-iidm-id** +Optional property that defines if IIDM IDs must be obtained from the CGMES `mRID` (master resource identifier) or the CGMES `rdfID` (Resource Description Framework identifier). The default value is `mRID`. + +**iidm.import.cgmes.store-cgmes-model-as-network-extension** +Optional property that defines if the whole CGMES model is stored in the imported IIDM network as an [extension](../model/extensions.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`. + +**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`. + +**iidm.import.cgmes.disconnect-dangling-line-if-boundary-side-is-disconnected** +Optional property used at CGMES import that disconnects the IIDM dangling line if in the CGMES model the line is open at the boundary side. As IIDM does not have any equivalence for that, this is an approximation. Its default value is `false`. + +**iidm.import.cgmes.missing-permanent-limit-percentage** +Optional property used when in operational limits, temporary limits are present and the permanent limit is missing as it is forbidden in IIDM. The missing permanent limit is equal to a percentage of the lowest temporary limit, with the percentage defined by the value of this property if present, `100` by default. + +**iidm.import.cgmes.cgm-with-subnetworks** +Optional property to define if subnetworks must be added to the network when importing a Common Grid Model (CGM). Each subnetwork will model an Individual Grid Model (IGM). By default `true`: subnetworks are added, and the merging is done at IIDM level, with a main IIDM network representing the CGM and containing a set of subnetworks, one for each IGM. If the value is set to `false` all the CGMES data will be flattened in a single network and information about the ownership of each equipment will be lost. + +**iidm.import.cgmes.cgm-with-subnetworks-defined** +If `iidm.import.cgmes.cgm-with-subnetworks` is set to `true`, use this property to specify how the set of input files should be split by IGM: based on their filenames (use the value `FILENAME`) or by its modeling authority, read from the header (use the value `MODELING_AUTHORITY`). diff --git a/docs/grid_exchange_formats/cgmes/index.md b/docs/grid_exchange_formats/cgmes/index.md new file mode 100644 index 00000000000..40318a69ac1 --- /dev/null +++ b/docs/grid_exchange_formats/cgmes/index.md @@ -0,0 +1,29 @@ +# CIM-CGMES + +```{toctree} +:hidden: +format_specification.md +triple_store.md +import.md +post_processor.md +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. + +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. +- `SSH` Steady State Hypothesis. Required input parameters to perform power flow analysis; e.g., energy injections and consumptions and setpoint values for regulating controls. +- `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. +- `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. + +`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/cgmes/post_processor.md b/docs/grid_exchange_formats/cgmes/post_processor.md new file mode 100644 index 00000000000..29fd336d385 --- /dev/null +++ b/docs/grid_exchange_formats/cgmes/post_processor.md @@ -0,0 +1,23 @@ +# CGMES post-processors + +## CgmesDLImportPostProcessor +This post-processor loads the diagram layout (DL) profile contained in the CGMES file, if available, into the triplestore. +The diagram layout profile contains the data which is necessary to represent a drawing of the diagram corresponding to the CGMES file. +For instance, it contains the position of all equipments. + +This post-processor is enabled by adding the name `cgmesDLImport` to the list associated to `iidm.import.cgmes.post-processors` property. + +## CgmesGLImportPostProcessor +TODO + +## CgmesMeasurementsPostProcessor +TODO + +## CgmesShortCircuitPostProcessor +TODO + +## EntsoeCategoryPostProcessor +TODO + +## PhaseAngleClock +TODO \ No newline at end of file diff --git a/docs/grid_exchange_formats/cgmes/triple_store.md b/docs/grid_exchange_formats/cgmes/triple_store.md new file mode 100644 index 00000000000..d4affc99bfb --- /dev/null +++ b/docs/grid_exchange_formats/cgmes/triple_store.md @@ -0,0 +1,18 @@ +# Triple store +A triplestore or RDF store is a purpose-built database for the storage and retrieval of triples through semantic queries. A triple is a data +entity composed of subject-predicate-object such as "Generator is in France", or in RDF/XML: +```xml + + France + +``` + +Input CGMES data read from CIM/XML files is stored natively in a purpose specific database for RDF statements (a Triplestore). There are multiple open-source implementations of Triplestore engines that could be easily plugged in PowSyBl. +The only supported Triplestore engine used by PowSyBl is [RDF4J](https://rdf4j.org/). +Loading from RDF/XML files to the Triplestore is highly optimized by these engines. Furthermore, the Triplestore repository can be configured to use an in-memory store, allowing faster access to data. + +## In-memory Rdf4j +[Eclipse RDF4J™](https://rdf4j.org/about/) is an open source modular Java framework for working with RDF data. This includes parsing, storing, inferencing and querying of/over such data. It offers an easy-to-use API that can be connected to all leading RDF storage solutions. It allows you to connect with SPARQL endpoints and create applications +that leverage the power of Linked Data and Semantic Web. + +Its in-memory implementation is the default triplestore engine use by PowSyBl for CIM-CGMES import. \ No newline at end of file diff --git a/docs/grid_exchange_formats/ieee/ieee.md b/docs/grid_exchange_formats/ieee/ieee.md new file mode 100644 index 00000000000..13b2374a4ef --- /dev/null +++ b/docs/grid_exchange_formats/ieee/ieee.md @@ -0,0 +1 @@ +# IEEE \ No newline at end of file diff --git a/docs/grid_exchange_formats/index.md b/docs/grid_exchange_formats/index.md new file mode 100644 index 00000000000..1f087c8ce60 --- /dev/null +++ b/docs/grid_exchange_formats/index.md @@ -0,0 +1,19 @@ +# Grid exchange formats + +This section is dedicated to the description of the various grid formats available in PowSyBl. While IIDM is at the core +of it, it is possible to import or export data in a number of formats that may be dedicated to European data exchanges +or network simulation via different tools: check them out below. + +```{toctree} +--- +maxdepth: 2 +--- + +ampl/ampl.md +cgmes/index.md +ieee/ieee.md +matpower/matpower.md +psse/psse.md +ucte/ucte.md +xiidm/xiidm.md +``` diff --git a/docs/grid_exchange_formats/matpower/matpower.md b/docs/grid_exchange_formats/matpower/matpower.md new file mode 100644 index 00000000000..5372fcb7029 --- /dev/null +++ b/docs/grid_exchange_formats/matpower/matpower.md @@ -0,0 +1 @@ +# Matpower \ No newline at end of file diff --git a/docs/grid_exchange_formats/psse/psse.md b/docs/grid_exchange_formats/psse/psse.md new file mode 100644 index 00000000000..9d2d67e8150 --- /dev/null +++ b/docs/grid_exchange_formats/psse/psse.md @@ -0,0 +1 @@ +# PSSE \ No newline at end of file diff --git a/docs/grid_exchange_formats/ucte/ucte.md b/docs/grid_exchange_formats/ucte/ucte.md new file mode 100644 index 00000000000..ea73335b624 --- /dev/null +++ b/docs/grid_exchange_formats/ucte/ucte.md @@ -0,0 +1 @@ +# UCTE-DEF \ No newline at end of file diff --git a/docs/grid_exchange_formats/xiidm/xiidm.md b/docs/grid_exchange_formats/xiidm/xiidm.md new file mode 100644 index 00000000000..60f345bc5a7 --- /dev/null +++ b/docs/grid_exchange_formats/xiidm/xiidm.md @@ -0,0 +1 @@ +# XIIDM \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000000..64ebe3e0585 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,12 @@ +```{toctree} +--- +caption: Contents of this website +maxdepth: 2 +hidden: true +--- + +grid_exchange_formats/index.md +simulation/index.md +``` + +# TODO \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000000..96ed7097e45 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000000..bbadfbf5130 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +sphinx==7.1.2 +sphinx-tabs +furo==2024.1.29 +myst-parser \ No newline at end of file diff --git a/docs/simulation/index.md b/docs/simulation/index.md new file mode 100644 index 00000000000..627c7afa64e --- /dev/null +++ b/docs/simulation/index.md @@ -0,0 +1,17 @@ +# Simulation + +One major aim of the PowSyBl project is to make it easy to plug it with different solvers for grid simulation. +At the moment, four types of simulations are supported: power flow, security analysis, time-domain simulation and sensitivity analysis. +For each of them, one or several simulators is officially supported, but it is also possible to plug your own simulator within the framework. +Below comes a description of the various types of simulation and supported solvers. + +```{toctree} +--- +maxdepth: 2 +--- + +loadflow/loadflow.md +security/security.md +sensitivity/sensitivity.md +shortcircuit/index.md +``` \ No newline at end of file diff --git a/docs/simulation/loadflow/loadflow.md b/docs/simulation/loadflow/loadflow.md new file mode 100644 index 00000000000..a5e37c3466a --- /dev/null +++ b/docs/simulation/loadflow/loadflow.md @@ -0,0 +1 @@ +# Load flow \ No newline at end of file diff --git a/docs/simulation/security/security.md b/docs/simulation/security/security.md new file mode 100644 index 00000000000..7f0b2b29597 --- /dev/null +++ b/docs/simulation/security/security.md @@ -0,0 +1 @@ +# Security analysis \ No newline at end of file diff --git a/docs/simulation/sensitivity/sensitivity.md b/docs/simulation/sensitivity/sensitivity.md new file mode 100644 index 00000000000..30f248ddf6e --- /dev/null +++ b/docs/simulation/sensitivity/sensitivity.md @@ -0,0 +1 @@ +# Sensitivity analysis \ No newline at end of file diff --git a/docs/simulation/shortcircuit/index.md b/docs/simulation/shortcircuit/index.md new file mode 100644 index 00000000000..c0cef7a2267 --- /dev/null +++ b/docs/simulation/shortcircuit/index.md @@ -0,0 +1,19 @@ +# 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. + +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). + +```{toctree} +--- +caption: Short-circuit analysis +maxdepth: 2 +hidden: true +--- + +parameters.md +inputs.md +outputs.md +``` diff --git a/docs/simulation/shortcircuit/inputs.md b/docs/simulation/shortcircuit/inputs.md new file mode 100644 index 00000000000..99a2dc98fc0 --- /dev/null +++ b/docs/simulation/shortcircuit/inputs.md @@ -0,0 +1,40 @@ +# Inputs + +The API takes as inputs: + +**A network** + +It is the network on which the computation will be done. + +**A list of faults** + +The API takes as input a list of faults on which the calculation should be done. Faults on buses and on lines are supported. +Each fault can either be an instance of `com.powsybl.shortcircuit.BusFault` or `com.powsybl.shortcircuit.BranchFault`. + +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) | +| 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 | +| faultType | FaultType | - | no | `FaultType.THREE_PHASE` | The type of fault simulated: can be three-phased or single-phased | + +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 | +| 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 | +| faultType | FaultType | - | no | `FaultType.THREE_PHASE` | The type of fault simulated: can be three-phased or single-phased | +| proportionalLocation | double | % | yes | - | The position where the fault should be simulated, in percent of the line | + +**A list of FaultParameters** + +Optionally, it is possible to specify a list of `FaultParameters`. Each `FaultParameter` will override the default parameters for a given fault. +For more information on parameters, see [above](#faultparameters). diff --git a/docs/simulation/shortcircuit/outputs.md b/docs/simulation/shortcircuit/outputs.md new file mode 100644 index 00000000000..f19458beef3 --- /dev/null +++ b/docs/simulation/shortcircuit/outputs.md @@ -0,0 +1,98 @@ +# Outputs +The results of the short-circuit analysis are stored in `com.powsybl.shortcircuit.ShortCircuitAnalysisResult`. This class gathers the results for every fault, they are accessible either by the ID of the fault or the ID of the element on which the fault is simulated. +For each fault, an object `com.powsybl.shortcircuit.FaultResult` is returned. + +Depending on `with-fortescue-result`, the returned result should either be an instance of `com.powsybl.shortcircuit.MagnitudeFaultResult` or `com.powsybl.shortcircuit.FortescueFaultResult`. + +Both classes contain the following attributes: + +| Attribute | Type | Unit | Required | Default value | Description | +|------------------------|-----------------------------|------|----------|---------------|------------------------------------------------------------------------------------------------------------| +| fault | Fault | - | yes | - | The fault that was simulated | +| status | Status | - | yes | - | The status of the computation, see below for more details | +| shortCircuitPower | double | MVA | yes | - | The value of the short-circuit power | +| timeConstant | Duration | - | yes | - | The duration before reaching the permanent short-circuit current | +| feederResults | List | - | no | Empty list | A list of FeederResult, should not be empty if the parameter `with-feeder-result` is set to `true`. | +| limitViolations | List | - | no | Empty list | A list of LimitViolation, should be empty if the parameter `with-limit-violations` is set to `false`. | +| shortCircuitBusResults | List | - | no | Empty list | A list of ShortCircuitBusResult, should be empty if the parameter `with-voltage-result` is set to `false`. | + +However, in these classes, the short-circuit current and voltage are represented differently. + +In `MagnitudeFaultResult`, the additional attributes are: + +| Attribute | Type | Unit | Required | Default value | Description | +|-----------|--------|------|----------|---------------|------------------------------------------------------------------| +| current | double | A | yes | - | The three-phased magnitude of the computed short-circuit current | +| voltage | double | kV | yes | - | The three-phased magnitude of the computed short-circuit voltage | + + +In `FortescueFaultResult`, they are: + +| Attribute | Type | Unit | Required | Default value | Description | +|-----------|------------------|------|----------|---------------|--------------------------------------------------------------------------------------------| +| current | `FortescueValue` | A | yes | - | The magnitude and angle of the computed short-circuit current detailed on the three phases | +| voltage | `FortescueValue` | kV | yes | - | The magnitude and angle of the computed short-circuit voltage detailed on the three phases | + + + +**The status of the computation** + +This status can be: +- `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. + +**FeederResults** + +This field contains the contributions of each feeder to the short-circuit current as a list. It should only be returned if `with-feeder-result` is set to `true`. +Depending on the value of `with-fortescue-result`, it should be an instance of `com.powsybl.shortcircuit.MagnitudeFeederResult` or `com.powsybl.shortcircuit.FortescueFeederResult`. + +The attributes of `MagnitudeFeederResults` are: + +| Attribute | Type | Unit | Required | Default value | Description | +|---------------|--------|------|----------|---------------|------------------------------------------------------------------------------------------------------------| +| connectableId | String | - | yes | - | ID of the feeder | +| current | double | A | yes | - | Three-phased current magnitude of the feeder participating to the short-circuit current at the fault point | + + +The attributes of `FortescueFeederResuts` are: + +| Attribute | Type | Unit | Required | Default value | Description | +|---------------|------------------|------|----------|---------------|-------------------------------------------------------------------------------------------------------------------------------| +| connectableId | String | - | yes | - | ID of the feeder | +| current | `FortescueValue` | A | yes | - | Current magnitudes and angles on the three phases of the feeder participating to the short-circuit current at the fault point | + + +**LimitViolations** + +This field contains a list of all the violations after the fault. This implies to have defined in the network the maximum or the minimum acceptable short-circuit currents on the voltage levels. +Then, with comparing to the computed short-circuit current, two types of violations can be created: `LOW_SHORT_CIRCUIT_CURRENT` and `HIGH_SHORT_CIRCUIT_CURRENT`. +This list should be empty if the property `with-limit-violations` is set to `false`. + +**ShortCircuitBusResults** + +This field contains a list of voltage results on every bus of the network after simulating the fault. It should be empty if `with-voltage-result` is set to `false`. +The value of the property `with-voltage-drop-threshold` allows to filter these results by keeping only those where the voltage drop is higher than this defined threshold. +Depending on the value of `with-fortescue-result`, the list should contain instances of either `com.powsybl.shortcircuit.MagnitudeShortCircuitBusResult` or `com.powsybl.shortcircuit.FortescueShortCircuitBusResult` objects. + + +The attributes of `MagnitudeShortCircuitBusResult` are: + +| Attribute | Type | Unit | Required | Default value | Description | +|-------------------------|--------|------|----------|---------------|--------------------------------------------------------| +| voltageLevelId | String | - | yes | - | ID of the voltage level containing the bus | +| busId | String | - | yes | - | ID of the bus | +| initialVoltageMagnitude | double | kV | yes | - | Magnitude of the three-phased voltage before the fault | +| voltageDropProportional | double | % | yes | - | Voltage drop after the fault | +| voltage | double | kV | yes | - | Magnitude of the three-phased voltage after the fault | + +The attributes of `FortescueShortCircuitBusResult` are: + +| Attribute | Type | Unit | Required | Default value | Description | +|-------------------------|------------------|------|----------|---------------|--------------------------------------------------------------------------| +| voltageLevelId | String | - | yes | - | ID of the voltage level containing the bus | +| busId | String | - | yes | - | ID of the bus | +| initialVoltageMagnitude | double | kV | yes | - | Magnitude of the three-phased voltage before the fault | +| voltageDropProportional | double | % | yes | - | Voltage drop after the fault | +| voltage | `FortescueValue` | kV | yes | - | Magnitudes and angles of the voltage on the three phases after the fault | diff --git a/docs/simulation/shortcircuit/parameters.md b/docs/simulation/shortcircuit/parameters.md new file mode 100644 index 00000000000..d0d2c1b56cb --- /dev/null +++ b/docs/simulation/shortcircuit/parameters.md @@ -0,0 +1,137 @@ +# Parameters + +## Available parameters +The parameters to be used for the short-circuit calculation should be defined in the config.yml file. For example, here are some valid short-circuit parameters: + +```yaml +short-circuit-parameters: + with-voltage-result: false + with-feeder-result: true + with-limit-violations: true + study-type: TRANSIENT + with-fortescue-result: false + min-voltage-drop-proportional-threshold: 20 + with-loads: true + with-shunt-compensators: true + with-vsc-converter-stations: false + with-neutral-position: true + initial-voltage-profile-mode: CONFIGURED + voltage-ranges: /path/to/voltage/ranges/file +``` + +Available parameters in the short-circuit API are stored in `com.powsybl.shortcircuit.ShortCircuitParameters`. They are all optional. + +**with-limit-violations** + +This property indicates whether limit violations should be returned after the computation. The violations that should be used are `LOW_SHORT_CIRCUIT_CURRENT` and `HIGH_SHORT_CIRCUIT_CURRENT`. +It can be used to filter results where the computed short-circuit current is too high or too low. The default value is `true`. + +**with-fortescue-result** + +This property indicates if the computed results, like currents and voltages, should be returned only in three-phased magnitude or detailed with magnitude and angle on each phase. +According to this property, different classes to return results can be used. If it is set to false, the classes `MagnitudeFaultResult`, `MagnitudeFeederResult` and `MagnitudeShortCircuitBusResult` should be used. +If the property is true, the classes `FortescueFaultResult`, `FortescueFeederResult` and `FortescueShortCircuitBusResult` should be used. All these classes are in `com.powsybl.shortcircuit`. +The default value is `true`. + +**with-feeder-result** + +This property indicates if the contributions of each feeder to the short-circuit current at the fault should be computed. +If the property is set to true, the results can be stored in class `com.powsybl.shortcircuit.FeederResult`. +The default value is `true`. + +**study-type** + +This property indicates the type of short-circuit study. It can be: +- `SUB_TRANSIENT`: it is the first stage of the short circuit, right when the fault happens. In this case, it is the sub-transient reactance of generators that is used. + This reactance can either be stored in the network or calculated from the transient reactance of generators with a coefficient defined by the parameter `sub-transient-coefficient`. +- `TRANSIENT`: the second stage of the short circuit, before the system stabilizes. The transient reactance of generators will be used. +- `STEADY_STATE`: the last stage, once all transient effects are gone. + +The default value is `TRANSIENT`. The transient and sub-transient reactance of the generators are stored in the [short-circuit generator extension.](../../grid/model/extensions.md#generator-short-circuit) + +**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: + +$$X''_d = c \times X'_d$$ + +with: + +- $$X''_d$$: the sub-transient reactance +- $$c$$: the sub-transient coefficient defined in this property +- $$X'_d$$: the transient reactance + +By default, the value of the coefficient is 0.7, and it should not be higher than 1. + +**with-voltage-result** + +This property indicates if the voltage profile should be computed on every node of the network. The results, if this property is `true`, should be stored in class `com.powsybl.shortcircuit.ShortCircuitBusResult`. The default value is `true`. + +**min-voltage-drop-proportional-threshold** + +This property indicates a threshold to filter the voltage results. Thus, it only makes sense if `with-voltage-result` is set to true. +Only the nodes where the voltage drop due to the short circuit in absolute value is above this property are kept. +The voltage drop is calculated as the ratio between the initial voltage magnitude on the node and the voltage magnitude on the node after the fault. The default value is `0`. + +**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. + +**with-shunt-compensators** + +This property indicates if shunt compensators should be taken into account during the computation. If `true`, the shunt compensators will be modelled as an equivalent reactance. +If `false`, then the shunt compensators will be ignored. + +**with-vsc-converter-stations** + +This property is a boolean property that indicates whether the VSC converter stations should be included in the calculation. +If `true`, the VSC converter stations will be modeled as an equivalent reactance. If `false`, they will be ignored. + +**with-neutral-position** + +This property indicates which position of the tap changer of transformers should be used for the calculation. If `true`, the neutral step of the tap changer +is used. The neutral step is the one for which $$\rho = 1$$ and $$\alpha = 0$$. If `false`, then the step that is in the model will be used. +By default, this property is set to false. +For more information about tap changers, see [the documentation about it](../../grid/model/index.md#phase-tap-changer). + +**initial-voltage-profile-mode** + +This property defines the voltage profile that should be used for the calculation. Three options are available: +- `NOMINAL`: the nominal voltage profile is used for the calculation +- `PREVIOUS`: the voltage profile from the load flow is used for the calculation +- `CONFIGURED`: the voltage profile is specified by the user + In the case of `CONFIGURED` voltage profile, ranges of nominal voltages with multiplicative coefficients must be specified in the `voltage-ranges` property. + By default, the initial voltage profile mode is set to `NOMINAL`. + +**voltage-ranges** + +This property specifies a path to a JSON file containing the voltage ranges and associated coefficients to be used when `initial-voltage-profile-mode` is set to `CONFIGURED`. +The JSON file must contain a list of voltage ranges and coefficients. Then, for each nominal voltage in the network that belongs to the range, the given coefficient is applied to calculate the voltage to be used +in the calculation. All the coefficients should be between 0.8 and 1.2. +Here is an example of this JSON file: +````json +[ + { + "minimumNominalVoltage": 350.0, + "maximumNominalVoltage": 400.0, + "voltageRangeCoefficient": 1.1 + }, + { + "minimumNominalVoltage": 215.0, + "maximumNominalVoltage": 235.0, + "voltageRangeCoefficient": 1.2 + }, + { + "minimumNominalVoltage": 80.0, + "maximumNominalVoltage": 150.0, + "voltageRangeCoefficient": 1.05 + } +] +```` + + +## 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 +for this specific fault. One `FaultParameters` corresponds to one `Fault`. +A list of `FaultParameters` can be given as an input to the API with specific parameters for one or multiple faults. If a fault has no `FaultParameters` corresponding, then the general parameters will be used.