diff --git a/docs/README.md b/docs/README.md index 687db4142e0..c78b7066ce9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,9 +3,25 @@ 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 +When modifying the website content, you can easily preview the result on your PC. + +**First option - in a terminal, navigate to the root of the project and run the following commands:** + +~~~ 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 + +**Second option - run the following commands directly from your IDE GUI** + +~~~bash +pip install -r requirements.txt +~~~ + +~~~bash +sphinx-build -a . ../build-docs +~~~ + +**Preview the result** + +Then open `../build-docs/index.html` in your browser. \ No newline at end of file diff --git a/docs/grid_exchange_formats/ampl/export.md b/docs/grid_exchange_formats/ampl/export.md index 01c48742d64..fe015b58f1c 100644 --- a/docs/grid_exchange_formats/ampl/export.md +++ b/docs/grid_exchange_formats/ampl/export.md @@ -3,7 +3,7 @@ ## 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. +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. **iidm.export.ampl.export-ratio-tap-changer-voltage-target** The `iidm.export.ampl.export-ratio-tap-changer-voltage-target` property is an optional property that defines whether the AMPL exporter exports the ratio tap changer voltage setpoint or not. Its default value is `false`. diff --git a/docs/grid_exchange_formats/cgmes/export.md b/docs/grid_exchange_formats/cgmes/export.md index 0cb8895c54d..482e92c13ce 100644 --- a/docs/grid_exchange_formats/cgmes/export.md +++ b/docs/grid_exchange_formats/cgmes/export.md @@ -100,13 +100,13 @@ PowSybl [`VoltatgeLevels`](../../grid_model/network_subnetwork.md#voltage-level) ### Control areas -PowSyBl [`ControlAreas`](../model/extensions.md#cim-cgmes-control-areas) are exported as CGMES `ControlAreas`. +PowSyBl [`ControlAreas`](import.md#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. +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. **iidm.export.cgmes.base-name** Optional property that defines the base name of the exported files. Exported CGMES files' names will look like this: diff --git a/docs/grid_exchange_formats/cgmes/import.md b/docs/grid_exchange_formats/cgmes/import.md index e83903f5520..f9b7380a5d9 100644 --- a/docs/grid_exchange_formats/cgmes/import.md +++ b/docs/grid_exchange_formats/cgmes/import.md @@ -339,7 +339,7 @@ If the CGMES `Switch` has one of its end in the boundary area, it is mapped to a 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 +### CGMES control areas This extension models all the control areas contained in the network as modeled in CIM-CGMES. @@ -362,7 +362,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. -### CIM-CGMES dangling line boundary node +### CGMES dangling line boundary node This extension is used to add some CIM-CGMES characteristics to dangling lines. @@ -374,7 +374,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. -### CIM-CGMES line boundary node +### CGMES line boundary node This extension is used to add some CIM-CGMES characteristics to tie lines. @@ -385,15 +385,11 @@ 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. -### CIM-CGMES Tap Changers +### CGMES Tap Changers TODO -### CIM-CGMES SSH metadata - -TODO - -### CIM-CGMES SV metadata +### CGMES metadata model TODO @@ -401,9 +397,11 @@ This extension is provided by the `com.powsybl:powsybl-cgmes-extensions` module. TODO +### CGMES model + ## 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. +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. **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`. @@ -459,7 +457,7 @@ Optional property that defines which CGMES profile is used to initialize tap pos 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`. +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`. diff --git a/docs/grid_exchange_formats/iidm/export.md b/docs/grid_exchange_formats/iidm/export.md index 4c3dae10c96..25cebec2615 100644 --- a/docs/grid_exchange_formats/iidm/export.md +++ b/docs/grid_exchange_formats/iidm/export.md @@ -3,7 +3,7 @@ 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. +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. **iidm.export.xml.indent** The `iidm.export.xml.indent` property is an optional property that defines whether the XIIDM file generated by the XIIDM exporter will be indented or not. Its default value is `true`. diff --git a/docs/grid_exchange_formats/iidm/import.md b/docs/grid_exchange_formats/iidm/import.md index 800a84f198e..b3e123c1912 100644 --- a/docs/grid_exchange_formats/iidm/import.md +++ b/docs/grid_exchange_formats/iidm/import.md @@ -3,7 +3,7 @@ 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. +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. **iidm.import.xml.throw-exception-if-extension-not-found** 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`. diff --git a/docs/grid_exchange_formats/iidm/index.md b/docs/grid_exchange_formats/iidm/index.md index 238fbb18b3c..b94416c5fb8 100644 --- a/docs/grid_exchange_formats/iidm/index.md +++ b/docs/grid_exchange_formats/iidm/index.md @@ -12,15 +12,13 @@ IIDM is the internal format used in Powsybl because it is designed for running s Several exchange formats result from this internal format: - XIIDM, which corresponds to an XML export of IIDM, - JIIDM, which corresponds to a JSON export of IIDM, -- BIIDM, which corresponds to a binary export (this is still a beta-feature). - -## Examples +- BIIDM, which corresponds to a binary export (this is still a beta-feature). Below are two export from a same network: - one XML export (XIIDM exchange format) - one JSON export (JIIDM exchange format) -### XIIDM example +## XIIDM ```xml @@ -66,7 +64,7 @@ Below are two export from a same network: ``` -### JIIDM example +## JIIDM ```json { "version" : "1.12", diff --git a/docs/grid_exchange_formats/index.md b/docs/grid_exchange_formats/index.md index 04f925f5c67..37dbd4b5507 100644 --- a/docs/grid_exchange_formats/index.md +++ b/docs/grid_exchange_formats/index.md @@ -10,7 +10,7 @@ or network simulation via different tools: check them out below. | [CIM-CGMES](cgmes/index.md) | the standard format for European grid data exchange | ✔ | ✔ | | [UCTE-DEF](ucte/index.md) | the legacy format for European grid data exchange | ✔ | ✘* | | [IIDM](iidm/index.md) (XIIDM, JIIDM, BIIDM) | the internal data model of PowSyBl in a XML / JSON / binary format | ✔ | ✔ | -| [IEEE-CDF](ieee/index.md) | a IEEE standard format | ✔ | ✘ | +| [IEEE-CDF](ieee/ieee.md) | a IEEE standard format | ✔ | ✘ | | [PSS®E](psse/index.md) | the format for power flow analysis on Siemens PSS®E software | ✔ | ✘* | | PowerFactory | the format for DIgSILENT PowerFactory software | ✔ | ✘ | | [Matpower](matpower/index.md) | the format for the free and open-source Matlab toolbox dedicated to power system simulation and optimization | ✔ | ✘ | diff --git a/docs/grid_exchange_formats/psse/import.md b/docs/grid_exchange_formats/psse/import.md index 12a4814071a..7ec3d13a963 100644 --- a/docs/grid_exchange_formats/psse/import.md +++ b/docs/grid_exchange_formats/psse/import.md @@ -8,7 +8,7 @@ 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 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) module. +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`. diff --git a/docs/grid_exchange_formats/ucte/export.md b/docs/grid_exchange_formats/ucte/export.md index cdc5f089067..bcf6fae2a79 100644 --- a/docs/grid_exchange_formats/ucte/export.md +++ b/docs/grid_exchange_formats/ucte/export.md @@ -3,7 +3,7 @@ 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. +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. **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. diff --git a/docs/grid_features/extraction.md b/docs/grid_features/extraction.md index 54260e07ef7..20e4ff1d75a 100644 --- a/docs/grid_features/extraction.md +++ b/docs/grid_features/extraction.md @@ -188,7 +188,7 @@ $> ./itools run-script --file extraction.groovy network.xiidm network2.xiidm ``` ### Import post-processor -This example shows how to automatically reduce networks when they are loaded, using the [groovy post-processors](import-post-processor.md#groovy-post-processor) with the same script as above. Note that the script will be applied each time a case file will be loaded. If you want to do it only once, use the [previous method](#groovy-scripting). +This example shows how to automatically reduce networks when they are loaded, using the [groovy post-processors](import_post_processor.md#groovy-post-processor) with the same script as above. Note that the script will be applied each time a case file will be loaded. If you want to do it only once, use the [previous method](#groovy-scripting). The script is a little different from the previous one: ```groovy @@ -209,9 +209,9 @@ import: groovy-post-processor: script: /home/user/network-reduction.groovy ``` -For more information about the configuration of the groovy post-processor, please refer to this [documentation page](import-post-processor.md#groovy-post-processor). +For more information about the configuration of the groovy post-processor, please refer to this [documentation page](import_post_processor.md#groovy-post-processor). -Then, we run the [convert-network](../user/itools/convert-network.md) command: +Then, we run the [convert-network](../user/itools/convert_network.md) command: ```shell $> ./itools convert-network --input-file /home/user/input.xiidm --output-file /home/user/output.xiidm --output-format XIIDM diff --git a/docs/grid_features/import_post_processor.md b/docs/grid_features/import_post_processor.md index 729316be1be..d9a4d3d9dc4 100644 --- a/docs/grid_features/import_post_processor.md +++ b/docs/grid_features/import_post_processor.md @@ -69,9 +69,8 @@ The following example prints meta-information from the network: print("Network " + network.getId() + " (" + network.getSourceFormat()+ ") is imported"); ``` - ## LoadFlow post-processor -Mathematically speaking, a [power flow](../../simulation/powerflow/index.md) 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/loadflow.md) 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. 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. diff --git a/docs/grid_model/extensions.md b/docs/grid_model/extensions.md index 16eda486842..553899d1356 100644 --- a/docs/grid_model/extensions.md +++ b/docs/grid_model/extensions.md @@ -11,7 +11,7 @@ Note that some extensions provided by PowSyBl aren't supported in the [persisten Every extension is considered as serializable unless explicitly specified as non-serializable in XML-IIDM. ## Active power control -This extension is used to configure the participation factor of the generator, typically in the case of a load flow computation with distributed slack enabled (with [balance type](../simulation/powerflow/index.md#balanceType) on generator). This extension is attached to a [generator](network_subnetwork.md#generator) or a [battery](network_subnetwork.md#battery). +This extension is used to configure the participation factor of the generator, typically in the case of a load flow computation with distributed slack enabled (with [balance type](../simulation/loadflow/loadflow.md#generic-parameters) on generator). This extension is attached to a [generator](network_subnetwork.md#generator) or a [battery](network_subnetwork.md#battery). | Attribute | Type | Unit | Required | Default value | Description | |----------------------|---------|------------------------|----------|---------------|----------------------------------------------| @@ -282,7 +282,7 @@ A load is described by its active power setpoint $P0$ and its reactive power set | variableReactivePower | double | MVar | yes | - | The part of the reactive power setpoint that is considered variable | | fixedReactivePower | double | MVar | yes | - | The part of the reactive power setpoint that is considered constant | -Here is how to add an load detail extension to a load: +Here is how to add a load detail extension to a load: ```java load.newExtension(LoadDetailAdder.class) .withVariableActivePower(40) @@ -328,7 +328,12 @@ This extensions is used for generators with a remote reactive control. ## Slack terminal -This extension is attached to a [voltage level](network_subnetwork.md#voltage-level) and is used to define the slack bus of a power flow calculation i.e. which bus will be used to balance the active and reactive power in load flow analysis. Use this extension before a computation to force the slack bus selection. You should enable default load flow parameter [`isReadSlackBus`](../simulation/powerflow/index.md#available-parameters). Use this extension after a computation to attach to the network the slack bus that has been selected by the load flow engine (one by connected component). You should enable default load flow parameter [`isWriteSlackBus`](../../simulation/powerflow/index.md#available-parameters). +This extension is attached to a [voltage level](network_subnetwork.md#voltage-level) and is used to define the slack bus +of a power flow calculation i.e. which bus will be used to balance the active and reactive power in load flow analysis. +Use this extension before a computation to force the slack bus selection. You should enable default load flow parameter +[`isReadSlackBus`](../simulation/loadflow/loadflow.md#generic-parameters). Use this extension after a computation to attach +to the network the slack bus that has been selected by the load flow engine (one by connected component). You should enable +default load flow parameter [`isWriteSlackBus`](../simulation/loadflow/loadflow.md#generic-parameters). The slack bus is defined through the terminal of a connectable that belongs to the bus. It is totally allowed to define a disconnected terminal as slack as the connectable could be reconnected during a grid study. diff --git a/docs/grid_model/network_subnetwork.md b/docs/grid_model/network_subnetwork.md index fe14ea25de5..2ba1d972832 100644 --- a/docs/grid_model/network_subnetwork.md +++ b/docs/grid_model/network_subnetwork.md @@ -46,11 +46,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 [TSO](../../glossary.md#tso) 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. @@ -264,7 +264,7 @@ are automatically computed using information from the terminal of the dangling l **Available extensions** -- [CGMES Dangling Line Boundary Node](extensions.md#cgmes-dangling-line-boundary-node) +- [CGMES Dangling Line Boundary Node](../grid_exchange_formats/cgmes/import.md#cgmes-dangling-line-boundary-node) - [Connectable position](extensions.md#connectable-position) - [Discrete Measurements](extensions.md#discrete-measurements) - [Identifiable Short-Circuit](extensions.md#identifiable-short-circuit) @@ -449,7 +449,7 @@ $$ - [Connectable position](extensions.md#connectable-position) - [Branch Observability](extensions.md#branch-observability) - [Branch Status](extensions.md#branch-status) -- [CGMES Line Boundary Node](extensions.md#cgmes-line-boundary-node) +- [CGMES Line Boundary Node](../grid_exchange_formats/cgmes/import.md#cgmes-line-boundary-node) - [Discrete Measurements](extensions.md#discrete-measurements) - [Identifiable Short-Circuit](extensions.md#identifiable-short-circuit) - [Measurements](extensions.md#measurements) diff --git a/docs/simulation/index.md b/docs/simulation/index.md index 627c7afa64e..04aba49c95d 100644 --- a/docs/simulation/index.md +++ b/docs/simulation/index.md @@ -1,17 +1,19 @@ # 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. +One major aim of the PowSyBl project is to make it easy to plug it with different simulators or optimization tools for grid calculations. At the moment, several types of calculations are supported: load flow, security analysis, sensitivity analysis, short-circuit analysis, or time-domain simulation (also called dynamic simulation). + +For each of them, one or several simulators are supported, but it is also possible to plug your own simulator within the library. +Below comes a description of the various types of simulation. + ```{toctree} --- maxdepth: 2 --- -loadflow/loadflow.md +loadflow/index.md security/security.md sensitivity/sensitivity.md shortcircuit/index.md +dynamic_simulation/index.md ``` \ No newline at end of file diff --git a/docs/simulation/loadflow/index.md b/docs/simulation/loadflow/index.md new file mode 100644 index 00000000000..9503dfbefde --- /dev/null +++ b/docs/simulation/loadflow/index.md @@ -0,0 +1,9 @@ +# Load flow + +```{toctree} +--- +maxdepth: 2 +--- +loadflow.md +loadflow_validation.md +``` diff --git a/docs/simulation/loadflow/loadflow.md b/docs/simulation/loadflow/loadflow.md index a5e37c3466a..d4278f0e32c 100644 --- a/docs/simulation/loadflow/loadflow.md +++ b/docs/simulation/loadflow/loadflow.md @@ -1 +1,181 @@ -# Load flow \ No newline at end of file +# Load flow + +## Introduction + +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 +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. + +## Inputs + +The only input for a load flow simulation is a network and optionally a set of parameters. The parameters could be generic +(use `LoadFlowParameters`), meaning that there are shared between all implementations. They also could be specific to an +implementation. + +## Outputs + +The load flow simulation outputs consists of: +- A network, which has been modified based on the simulation results. The modified variables are the active and reactive +power at the terminals, the voltage magnitude and voltage angle at all buses, the solved tap changers positions, the +solved shunt compensator sections. +- A global status indicating if the simulation succeeded for all synchronous components (`Fully Converged` status), or for +only some of them (`Partially Converged` status), or for none of them (`Failed` status). +- Detailed results per synchronous component: a convergence status, the number of iterations (could be equal to `-1` if +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. +- Logs in a simulator specific format. + +## Implementations + +The following power flow implementations are supported: +- [PowSyBl OpenLoadFlow](TODO) +- [Dynaflow](TODO) + +## Configuration +You first need to choose which implementation to use in your configuration file: +```yaml +load-flow: + default-impl-name: "" +``` + +Each implementation is identified by its name, that may be unique in the classpath: +- use "OpenLoadFlow" to use PowSyBl OpenLoadFlow +- use "DynaFlow" to use DynaFlow implementation + +## Parameters + +Then, configure some generic parameters for all load flow implementations: +```yaml +load-flow-default-parameters: + dc: false + voltageInitMode: UNIFORM_VALUES + distributedSlack: true + balanceType: PROPORTIONAL_TO_GENERATION_P_MAX + countriesToBalance: + - FR + - BE + readSlackBus: false + writeSlackBus: false + useReactiveLimits: true + phaseShifterRegulationOn: false + transformerVoltageControlOn: false + shuntCompensatorVoltageControlOn: false + connectedComponentMode: MAIN + twtSplitShuntAdmittance: false + dcUseTransformerRatio: true + dcPowerFactor: 1.0 +``` + +The parameters may also be overridden with a JSON file, in which case the configuration will look like: +```json +{ + "version": "1.8", + "dc": false, + "voltageInitMode": "UNIFORM_VALUES", + "distributedSlack": true, + "balanceType": "PROPORTIONAL_TO_GENERATION_P_MAX", + "countriesToBalance": ["FR", "BE"], + "readSlackBus": false, + "writeSlackBus": false, + "useReactiveLimits": true, + "phaseShifterRegulationOn": false, + "transformerVoltageControlOn": false, + "shuntCompensatorVoltageControlOn": false, + "connectedComponentMode": "MAIN", + "twtSplitShuntAdmittance": false, + "dcUseTransformerRatio": true, + "dcPowerFactor": 1.0 +} +``` + +### Generic parameters + +**dc** +The `dc` property is an optional property that defines if you want to run an AC power flow (`false`) or a DC power flow (`true`). +The default value is `false`. + +**voltageInitMode** +The `voltageInitMode` property is an optional property that defines the policy used by the load flow to initialize the +voltage values. The available values are: +- `UNIFORM_VALUES`: $v = 1 pu$ , $\theta = 0$ +- `PREVIOUS_VALUES`: use previous computed value from the network +- `DC_VALUES`: $v = 1 pu$, $\theta$ initialized using a DC load flow + +The default value is `UNIFORM_VALUES`. + +**distributedSlack** +The `distributedSlack` property is an optional property that defines if the active power mismatch is distributed over the network or not. +The default value is `true`. + +**balanceType** +The `balanceType` property is an optional property that defines, if `distributedSlack` parameter is set to true, how to manage the distribution. Several algorithms are supported. All algorithms follow the same scheme: only some elements are participating in the slack distribution, with a given participation factor. Three options are available: +- If using `PROPORTIONAL_TO_GENERATION_P_MAX` then the participating elements are the generators. The participation factor is computed using the maximum active power target $MaxP$ and the active power control droop. The default droop value is `4`. If present, the simulator uses the droop of the generator given by the [active power control extension](../../grid_model/extensions.md#active-power-control). +- If using `PROPORTIONAL_TO_GENERATION_P` then the participating elements are the generators. The participation factor is computed using the active power set point $TargetP$. +- If using `PROPORTIONAL_TO_GENERATION_REMAINING_MARGIN` then the participating elements are the generators. The participation factor is computed using the difference between the maximum active power target $MaxP$ with active power set point $TargetP$. +- If using `PROPORTIONAL_TO_GENERATION_PARTICIPATION_FACTOR` then the participating elements are the generators. The simulator uses the participation factors of the generators given by the [active power control extension](../../grid_model/extensions.md#active-power-control). +- If using `PROPORTIONAL_TO_LOAD` then the participating elements are the loads. The participation factor is computed using the active power $P0$. +- If using `PROPORTIONAL_TO_CONFORM_LOAD` then the participating elements are the loads which have a conform active power part. The participation factor is computed using the [load detail extension](../../grid_model/extensions.md#load-detail), which specifies the variable and the fixed parts of $P0$. The slack is distributed only on loads that have a variable part. If the extension is not available on a load, the whole $P0$ is considered as a variable. + +This default value is `PROPORTIONAL_TO_GENERATION_P_MAX`. + +**countriesToBalance** +The `countriesToBalance` property is an optional property that defines the list of [ISO-3166](https://en.wikipedia.org/wiki/ISO_3166-1) +country which participating elements are used for slack distribution. If the slack is distributed but this parameter is not set, the slack distribution is performed over all countries present in the network. + +**readSlackBus** +The `readSlackBus` is an optional property that defines if the slack bus has to be selected in the network through the [slack terminal extension](../../grid_model/extensions.md#slack-terminal). +The default value is `false`. + +**writeSlackBus** +The `writeSlackBus` is an optional property that says if the slack bus has to be written in the network using the [slack terminal extension](../../grid_model/extensions.md#slack-terminal) after a load flow computation. +The default value is `false`. + +**useReactiveLimits** +The `useReactiveLimits` property is an optional property that defines whether the load flow should take into account equipment's reactive limits. Applies to generators, batteries, static VAR compensators, dangling lines, and HVDC VSCs. +The default value is `true`. + +**phaseShifterRegulationOn** +The `phaseShifterRegulationOn` property is an optional property that defines whether phase shifter regulating controls should be simulated in the load flow. +The default value is `false`. + +**transformerVoltageControlOn** +The `transformerVoltageControlOn` property is an optional property that defines whether transformer voltage regulating controls should be simulated in the load flow. +The default value is `false`. + +**shuntCompensatorVoltageControlOn** +The `shuntCompensatorVoltageControlOn` property is an optional property that defines whether shunt compensator voltage regulating controls should be simulated in the load flow. +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 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 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 default value of this parameter is `true`. + +**dcPowerFactor** +The `dcPowerFactor` property is an optional property that defines the power factor used to convert current limits into active power limits in DC calculations. +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: +- [PowSyBl OpenLoadFlow](TODO) +- [DynaFlow](TODO) + +## Going further +To go further about the power flow with PowSyBl, check the following pages: +- [Run a power flow through an iTools command](../../user/itools/loadflow.md): Learn how to perform a power flow calculation from the command line +- [Load flow tutorial](../../developer/tutorials/loadflow.md) \ No newline at end of file diff --git a/docs/simulation/loadflow/loadflow_validation.md b/docs/simulation/loadflow/loadflow_validation.md new file mode 100644 index 00000000000..172b106ff2f --- /dev/null +++ b/docs/simulation/loadflow/loadflow_validation.md @@ -0,0 +1,132 @@ +# Load flow validation + +A load flow result is considered *acceptable* if it describes a feasible steady-state of a power system given its physics and its logics. +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. + +### Buses + +The first law of Kirchhoff must be satisfied for every bus for active and reactive power: + +$$\begin{equation} +\left| \sum_{branches} P + \sum_{injections} P \right| \leq \epsilon \\ +\left| \sum_{branches} Q + \sum_{injections} Q \right| \leq \epsilon \\ +\end{equation}$$ + +### Branches +Lines and two windings 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) + (P1,Q1)-> ____O/O__________________________-----__________________________O/O_____ <-(P2,Q2) + | ----- | + g1+j*b1 |_| |_| g2+j*b2 + | | + _|_ _|_ + _ _ + . . +``` + +- Power flow results: + - $(\|V_1\|, \theta_1)$ and $(\|V_2\|, \theta_2)$: Magnitude (kV) and angle ($°$) of the voltage at the sides 1 and 2, respectively. + - $(P_1, Q_1)$ and $(P_2, Q_2)$: Active power (MW) and reactive power (MVAr) injected in the branch on each side. +- Characteristics: + - $(\rho_1, \alpha_1)$ and $(\rho_2, \alpha_2)$: Magnitude (no unit) and angle ($°$) of the ideal transformers + ratios on each side. + - $(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: + +$(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. + +#### 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. + +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. +The adjustment is done by modifying the generation of the generators connected to the slack node of the network. +It may also be done by modifying the loads connected to the slack node. +The slack node is a computation point designated to be the place where adjustments are done. + +This way of performing the adjustment is the simplest solution from a mathematical point of view, but it presents several drawbacks. +In particular, it may not be enough in case of a large imbalance. +This is why other schemes have been developed, called "distributed slack nodes". + +Generators or loads are usually adjusted proportionally to a shift function to be defined. +Three keys have been retained for the validation ($g$ is a generator): +Usual ways of defining this function, for each equipment that may be involved in the compensation (generator or load), read: +- proportional to $P_{max}$: $F = f \times P_{max}$ +- proportional to ${targetP}$: $F = f \times targetP$ +- proportional to $P_{diff}$: $F = f (P_{max} - targetP)$ + +$f$ is a participation factor, per unit. For example, a usual definition is: $f\in\{0,1\}$: either the unit +participates or not. The adjustment is then done by doing: +$P <- P \times \hat{K} \times F$ +where $\hat{K}$ is a proportionality factor, usually defined for each unit by $\dfrac{P_{max}}{\sum{F}}$, $\dfrac{targetP}{\sum{F}}$ or $\dfrac{P_{diff}}{\sum{F}}$ +depending on the adjustment mode (the sums run over all the units participating in the compensation). + +##### Voltage and reactive power + +If the voltage regulation is deactivated, it is expected that: + +$\left| targetQ - Q \right| < \epsilon$ + +If the voltage regulation is activated, the generator is modeled as a $PV$ node. +The voltage target should be reached, except if reactive bounds are hit. Then, the generator is switched to $PQ$ node and the reactive power should be equal to a limit. +Mathematically speaking, one of the following 3 conditions should be met: + +\begin{align*} +|V - targetV| & \leq && \epsilon && \& && minQ & \leq & Q \leq maxQ \\ +V - targetV & < & -& \epsilon && \& && |Q-maxQ| & \leq & \epsilon \\ +targetV - V & < && \epsilon && \& && |Q-minQ| & \leq & \epsilon \\ +\end{align*} +$$ + +#### Loads +To be implemented, with tests similar to generators with voltage regulation. + +#### Shunts +A shunt is expected not to generate or absorb active power: + +$\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$ + +#### Static VAR Compensators +Static VAR Compensators behave like generators producing 0 active power except that their reactive bounds are expressed +in susceptance, so that they are voltage dependent. + +$targetP = 0$ MW + +- If the regulation mode is `OFF`, then $targetQ$ is constant +- If the regulation mode is `REACTIVE_POWER`, it behaves like a generator without voltage regulation +- 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$ + +#### HVDC lines +To be done. + +##### 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. + +##### LCC +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. +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. + +As a result, a state is a steady state only if the regulated value is within the deadband or if the tap position is at +minimum or maximum: this corresponds to a valid load flow result for the ratio tap changers tap positions. \ No newline at end of file diff --git a/docs/user/configuration/import-export-parameters-default-value.md b/docs/user/configuration/import-export-parameters-default-value.md new file mode 100644 index 00000000000..0f537575798 --- /dev/null +++ b/docs/user/configuration/import-export-parameters-default-value.md @@ -0,0 +1,23 @@ +# import-export-parameters-default-value +The `import-export-parameters-default-value` module is an optional module used by the `com.powsybl.iidm.import_.Importers` class to initialize the parameters passed to configure the importer. This module supports 3 different types of properties: +- Boolean +- String +- 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. + +## Examples + +**YAML configuration:** +```yaml +import-export-parameters-default-value: + iidm.import.xml.throw-exception-if-extension-not-found: true +``` + +**XML configuration:** +```xml + + true + +``` diff --git a/docs/user/configuration/index.md b/docs/user/configuration/index.md new file mode 100644 index 00000000000..26c7f746a44 --- /dev/null +++ b/docs/user/configuration/index.md @@ -0,0 +1,86 @@ +# Configuration + +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 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. + +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 +several properties. These properties can also be required or optional. Names in configuration files are case-sensitive. + +### Example + +**YAML configuration** +```yml +module1: + property1a: value1 + property1b: value2 + +module2: + property2a: value3 + property2b: value4 + property2c: value5 +``` + +**XML configuration** +```xml + + + value1 + value2 + + + value3 + value4 + value5 + + +``` + +### 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: + +| 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) +- [computation-local](computation-local.md) +- [default-computation-manager](default-computation-manager.md) +- [dynamic-simulation](dynamic-simulation.md) +- [dynamic-simulation-default-parameters](dynamic-simulation-default-parameters.md) +- [dynawo](dynawo.md) +- [dynawo-default-parameters](dynawo-default-parameters.md) +- [external-security-analysis-config](external-security-analysis-config.md) +- [groovy-dsl-contingencies](groovy-dsl-contingencies.md) +- [groovy-post-processor](../../grid_features/import_post_processor.md#groovy-post-processor) +- [import-export-parameters-default-value](import-export-parameters-default-value.md) +- [javaScriptPostProcessor](../../grid_features/import_post_processor.md#javascript-post-processor) +- [limit-violation-default-filter](limit-violation-default-filter.md) +- [load-flow](load-flow.md) +- [load-flow-action-simulator](load-flow-action-simulator.md) +- [load-flow-based-phase-shifter-optimizer](load-flow-based-phase-shifter-optimizer.md) +- [load-flow-default-parameters](../../simulation/loadflow/loadflow.md#generic-parameters) +- [loadflow-results-completion-parameters](loadflow-results-completion-parameters.md) +- [loadflow-validation](loadflow-validation.md) +- [local-app-file-system](local-app-file-system.md) +- [mapdb-app-file-system](mapdb-app-file-system.md) +- [network](network.md) +- [open-loadflow-default-parameters]() +- [remote-service](remote-service.md) +- [security](security.md) +- [security-analysis](security-analysis.md) +- [simulation-parameters](simulation-parameters.md) +- [table-formatter](table-formatter.md) diff --git a/docs/user/configuration/load-flow-action-simulator.md b/docs/user/configuration/load-flow-action-simulator.md new file mode 100644 index 00000000000..88648cea378 --- /dev/null +++ b/docs/user/configuration/load-flow-action-simulator.md @@ -0,0 +1,43 @@ +# load-flow-action-simulator +The `load-flow-action-simulator` module is used by the [action-simulator]() tool if it's configured to use the `LoadFlowActionSimulator` implementation. + +## Properties + +**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. + +**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. + +**load-flow-name** +The `load-flow-name` property is an optional property that defines the implementation name to use for running the load flow. +If this property is not set, the default load flow implementation is used. See [Loadflow Configuration](load-flow.md) to +configure the default load flow. + +**max-iterations** +Use the `max-iterations` parameter to limit the number of iteration needed to solve the violations. + +## Examples + +**YAML configuration:** +```yaml +load-flow-action-simulator: + copy-strategy: STATE + debug: false + ignore-pre-contingency-violations: false + load-flow-name: Mock + max-iterations: 10 +``` + +**XML configuration:** +```xml + + STATE + false + false + Mock + 10 + +``` diff --git a/docs/user/configuration/load-flow-based-phase-shifter-optimizer.md b/docs/user/configuration/load-flow-based-phase-shifter-optimizer.md new file mode 100644 index 00000000000..8a279d2efc2 --- /dev/null +++ b/docs/user/configuration/load-flow-based-phase-shifter-optimizer.md @@ -0,0 +1,25 @@ +# load-flow-based-phase-shifter-optimizer +The `load-flow-based-phase-shifter-optimizer` module is used by the `com.powsybl.action.util.LoadFlowBasedPhaseShifterOptimizer` class, +which is an implementation of the `com.powsybl.action.util.PhaseShifterOptimizer` interface. The `LoadFlowBasedPhaseShifterOptimizer` +tries to solve a current violation on a phase tap changer. + +## Required properties + +**load-flow-name** +The `load-flow-name` property is an optional property that defines the implementation name to use for running the load flow. +If this property is not set, the default load flow implementation is used. See [Loadflow Configuration](load-flow.md) to configure the default load flow. + +## Examples + +**YAML configuration:** +```yaml +load-flow-based-phase-shifter-optimizer: + load-flow-name: Mock +``` + +**XML configuration:** +```xml + + Mock + +``` diff --git a/docs/user/configuration/load-flow.md b/docs/user/configuration/load-flow.md new file mode 100644 index 00000000000..b4ee88920c6 --- /dev/null +++ b/docs/user/configuration/load-flow.md @@ -0,0 +1,31 @@ +# load-flow +The `load-flow` module is used to configure the load flow default implementation name. Each load flow implementation +provides a subclass of `com.powsybl.loadflow.LoadFlowProvider` correctly configured to be found by `java.util.ServiceLoader`. +A load flow provider exposes a name that can be used in the LoadFlow Java API to find a specific load flow implementation. +It can also be used to specify a default implementation in this platform config module. If only one `com.powsybl.loadflow.LoadFlowProvider` +is present in the classpath, there is no need to specify a default LoadFlow implementation name. In the case where more +than one `com.powsybl.loadflow.LoadFlowProvider` is present in the classpath, specifying the default implementation name +allows LoadFlow API user to use LoadFlow.run(...) and LoadFlow.runAsync(...) methods to run a load flow. Using these +methods when no default load flow name is configured and multiple implementations are in the classpath will throw an exception. +An exception is also thrown if no implementation at all is present in the classpath, or if specifying a load flow name that +is not present on the classpath. + +## Properties + +**default-impl-name** +Use the `default-impl-name` property to specify the name of the default load flow implementation. + +## Examples + +**YAML configuration:** +```yaml +load-flow: + default-impl-name: Mock +``` + +**XML configuration:** +```xml + + Mock + +``` diff --git a/docs/user/configuration/loadflow-results-completion-parameters.md b/docs/user/configuration/loadflow-results-completion-parameters.md new file mode 100644 index 00000000000..12d1d2c9008 --- /dev/null +++ b/docs/user/configuration/loadflow-results-completion-parameters.md @@ -0,0 +1,28 @@ +# loadflow-results-completion-parameters +The `loadflow-results-completion-parameters` module is used by the [loadflow-validation](../itools/loadflow-validation.md) +command and the [LoadFlowResultsCompletion](../../grid_features/import_post_processor.md) post processor. + +## Optional properties + +**apply-reactance-correction** +The `apply-reactance-correction` property is an optional property that defines whether the too small reactance values have to be fixed to `epsilon-x` value or not. To solve numeric issues with very small reactance values, it's necessary to set the too small values to a minimal value. The default value of this property is `false`. + +**epsilon-x** +The `epsilon-x` property is an optional property that defines the reactance value used for fixing. The default value of this property is `0.1`. + +## Examples + +**YAML configuration:** +```yaml +loadflow-results-completion-parameters: + apply-reactance-correction: true + epsilon-x: 0.1 +``` + +**XML configuration:** +```xml + + true + 0.1 + +``` diff --git a/docs/user/configuration/loadflow-validation.md b/docs/user/configuration/loadflow-validation.md new file mode 100644 index 00000000000..1c569da46ad --- /dev/null +++ b/docs/user/configuration/loadflow-validation.md @@ -0,0 +1,106 @@ +# loadflow-validation +The `loadflow-validation` module is used by the [loadflow-validation](../itools/loadflow-validation.md) command. It defines the parameters used during the validation of load flow results. + +## Optional properties + +**apply-reactance-correction** +The `apply-reactance-correction` property is an optional property that defines whether the too small reactance values have to be fixed to `epsilon-x` value or not. To solve numeric issues with very small reactance values, it's necessary to set the too small values to a minimal value. The default value of this property is `false`. + +**check-main-component-only** +The `check-main-component-only` property is an optional property that defines whether the validation checks are done only on the equipments in the main connected component or in all components. The default value of this property is `true`. + +**compare-results** +Set the `compare-results` property to true to compare the results of 2 validations, i.e. print output files with data of both ones. The default value of this property is `false`. + +**epsilon-x** +The `epsilon-x` property is an optional property that defines the value used to correct the reactance in flows validation. The default value of this property is `0.1`. + +**load-flow-name** +The `load-flow-name` property is an optional property that defines the implementation name to use for running the load flow. If this property is not set, the default load flow implementation is used. See [Loadflow Configuration](load-flow.md) to configure the default load flow. + +**Note**: In previous PowSyBl releases (before 3.0.0), this was configured by the `load-flow-factory` property with the full classname of the implementation. + +**no-requirement-if-reactive-bound-inversion** +The `no-requirement-if-reactive-bound-inversion` property is an optional property that defines whether the validation checks fail if there is a reactive bounds inversion (maxQ < minQ) or not. The default value of this property is `false`. + +**no-requirement-if-setpoint-outside-power-bounds** +The `no-requirement-if-setpoint-outside-power-bounds` property is an optional property that defines whether the validation checks fail if there is a setpoint outside the active power bounds (targetP < minP or targetP > maxP) or not. The default value of this property is `false`. + +**ok-missing-values** +The `ok-missing-values` property is an optional property that defines whether the validation checks fail if some parameters of connected components have `NaN` values or not. The default value of this property is `false`. + +**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: + +**Example of output in CSV format:** +```csv +id;p;q;v;nominalV;reactivePowerSetpoint;voltageSetpoint;connected;regulationMode;bMin;bMax;mainComponent;validation +CSPCH.TC1;-0,00000;93,6368;238,307;225,000;0,00000;238,307;true;VOLTAGE;-0,00197531;0,00493827;true;success +CSPDO.TC1;-0,00000;0,00000;240,679;225,000;0,00000;240,713;true;VOLTAGE;-0,00493827;0,00493827;true;success +... +``` + +**Example of output in CSV_MULTILINE format:** +```csv +id;characteristic;value +CSPCH.TC1;p;-0,00000 +CSPCH.TC1;q;93,6368 +CSPCH.TC1;v;238,307 +... +``` + +**table-formatter-factory:** +The `table-formatter-factory` property is an optional property that defines the `com.powsybl.commons.io.table.TableFormatterFactory` implementation to use for writing the output files. If this property is not set, the `com.powsybl.commons.io.table.CsvTableFormatterFactory` implementation is used. + +The available implementation of the `TableFormatterFactory` are: +- `com.powsybl.commons.io.table.CsvTableFormatterFactory`: to create a CSV file +- `com.powsybl.commons.io.table.AsciiTableFormatterFactory`: to render table in ASCII + +The table formatter can be configured by the [table-formatter](table-formatter.md) module. + +**threshold:** +The `threshold` property is an optional property that defines the margin used for values comparison. The default value of this property is `0`. + +**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. + +## Examples + +**YAML configuration:** +```yaml +loadflow-validation: + threshold: 0.1 + verbose: false + load-flow-name: Mock + table-formatter-factory: com.powsybl.commons.io.table.CsvTableFormatterFactory + epsilon-x: 0.1 + apply-reactance-correction: false + output-writer: CSV_MULTILINE + ok-missing-values: false + no-requirement-if-reactive-bound-inversion: false + compare-results: false + check-main-component-only: true + no-requirement-if-setpoint-outside-power-bounds: false +``` + +**XML configuration:** +```xml + + 0.1 + false + Mock + com.powsybl.commons.io.table.CsvTableFormatterFactory + 0.1 + false + CSV_MULTILINE + false + false + false + true + false + +``` diff --git a/docs/user/index.md b/docs/user/index.md index 39214726292..9d4f29da08d 100644 --- a/docs/user/index.md +++ b/docs/user/index.md @@ -6,7 +6,7 @@ In this section, you'll discover the basics about PowSyBl: how to install it, ru --- maxdepth: 1 --- - +configuration/index.md itools/index.md ``` diff --git a/docs/user/itools/convert_network.md b/docs/user/itools/convert_network.md index 0878e1b397e..83652e16908 100644 --- a/docs/user/itools/convert_network.md +++ b/docs/user/itools/convert_network.md @@ -1,6 +1,7 @@ # iTools convert-network -The `convert-network` command is used to convert a grid file from a format to another. The input format is automatically detected, whereas the output format must be specified. +The `convert-network` command is used to convert a grid file from a format to another. The input format is automatically +detected, whereas the output format must be specified. ## Usage ``` @@ -42,14 +43,14 @@ This option defines the format of the output file. The list of [supported format ### Optional arguments **\-\-export-parameters** -This option defines the path of the [exporter](../../glossary.md#exporter)'s configuration file. It's possible to overload one or many parameters using the `-E property=value` syntax. The list of supported properties depends on the [output format](../../grid_exchange_formats/index.md). +This option defines the path of the exporter's configuration file. It's possible to overload one or many parameters using the `-E property=value` syntax. The list of supported properties depends on the [output format](../../grid_exchange_formats/index.md). **\-\-import-parameters** -This option defines the path of the [importer](../../glossary.md#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). +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). ## Examples -This example shows how to convert a [UCTE-DEF](../../grid_exchange_formats/ucte/index.md) file to an [XIIDM](../../grid_exchange_formats/xiidm/index.md) file: +This example shows how to convert a [UCTE-DEF](../../grid_exchange_formats/ucte/index.md) file to an [XIIDM](../../grid_exchange_formats/iidm/index.md) file: ``` $> itools convert-network --input-file case-file.uct --output-format XIIDM --output-file case-file.xiidm ``` diff --git a/docs/user/itools/loadflow-validation.md b/docs/user/itools/loadflow-validation.md new file mode 100644 index 00000000000..4133f154632 --- /dev/null +++ b/docs/user/itools/loadflow-validation.md @@ -0,0 +1,350 @@ +--- +layout: default +latex: true +--- + +# iTools loadflow-validation + +The `loadflow-validation` command is used to validate load-flow results of a network. The command, besides validating +the results, also prints the data of the validated equipments in output files. +The consistency checks performed by the load flow validation may also be applied to results obtained with an optimal power flow or to the final state of a long dynamic simulation. + +* TOC +{:toc} + + +## Usage + +``` +$> itools loadflow-validation --help +usage: itools [OPTIONS] loadflow-validation --case-file + [--compare-case-file ] [--compare-results ] + [--help] [-I ] [--import-parameters ] + [--load-flow] --output-folder [--output-format + ] [--run-computation ] [--types + ] [--verbose] + +Available options are: + --config-name Override configuration file name + +Available arguments are: + --case-file case file path + --compare-case-file path to the case file to + compare + --compare-results compare results of two + validations, printing output + files with results of both + ones. Available comparisons + are [COMPUTATION (compare + the validation of a basecase + before and after the + computation), BASECASE + (compare the validation of + two basecases)] + --help display the help and quit + -I use value for given importer + parameter + --import-parameters the importer configuation + file + --load-flow run loadflow + --output-folder output folder path + --output-format output format [CSV, + CSV_MULTILINE] + --run-computation run a computation on the + network before validation, + available computations are + [loadflow, + loadflowResultsCompletion] + --types validation types [FLOWS, + GENERATORS, BUSES, SVCS, + SHUNTS, TWTS, TWTS3W] to + run, all of them if the + option if not specified + --verbose verbose output +``` + +### Required arguments + +**\-\-case-file** +Use the `--case-file` parameter to define the path of the case file. + +**\-\-output-folder** +Use the `--output-folder` parameter to define the path of the folder where the output files will be stored. + + +### 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 +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. + +**\-\-import-parameters** +Use the `--import-parameters` parameter to specify the path of the configuration file of the importer. It is possible to +overload one or many parameters using the `-I property=value` parameter. The properties depend on the input format. +Refer to the documentation page of each [importer](../../grid_exchange_formats/index.md) to know their specific configuration. + +**\-\-load-flow** +Use the `--load-flow` parameter to run a load-flow before the validation. This option is equivalent to +`--run-computation loadflow`. + +**\-\-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 +line, see examples below: + +**CSV** +``` +id;p;q;v;nominalV;reactivePowerSetpoint;voltageSetpoint;connected;regulationMode;bMin;bMax;mainComponent;validation +CSPCH.TC1;-0,00000;93,6368;238,307;225,000;0,00000;238,307;true;VOLTAGE;-0,00197531;0,00493827;true;success +CSPDO.TC1;-0,00000;0,00000;240,679;225,000;0,00000;240,713;true;VOLTAGE;-0,00493827;0,00493827;true;success +... +``` + +**CSV_MULTILINE** +``` +id;characteristic;value +CSPCH.TC1;p;-0,00000 +CSPCH.TC1;q;93,6368 +CSPCH.TC1;v;238,307 +... +``` + +**\-\-run-computation** +Use the `--run-computation` parameter to run a computation before the validation. The supported computations are: +- `loadflow`: run a load-flow +- `loadflowResultsCompletion`: compute the missing `P`, `Q`, `V` and $\theta$ values + +**\-\-types** +Use the `--types` parameter to define the types of checks to run. If this parameter is not set, run all the checks. +The supported types are `FLOWS`, `GENERATORS`, `BUSES`, `SVCS`, `SHUNTS`, `TWTS`. + +To learn more about the different checks, read the [loadflow validation](../../simulation/loadflow/loadflow_validation.md) documentation page. + +### Summary +The following table summarizes the possible combinations of `compare-results` and `run-computation` parameters, and the +corresponding case states validated and written in the output files. Some remarks: +- State 1 is the state analyzed in the first validation +- 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, +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 | + +## 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)). + +## 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 +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 +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. + +### 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 +the PowSyBl validation. + +### Branches +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 +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. + +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). + +### Three-windings transformers +To be implemented, based on a conversion into 3 two-windings transformers. + +### Generators + +#### Active power + +The load-flow validation of PowSyBl checks whether the adjustment of balances has been done consistently by the power flow. +The load-flow results do not include the adjustment mode used, nor the participation factors. They thus have to be inferred. +If deviations are perfect, the proportion factor $\hat{K}$ estimated for the right mode will +be the same for all the deviating units for which $P$ is strictly $P_{min}$ and $P_{max}$. Therefore, the inferred +deviation is the one for which the standard deviation of the estimated proportion factor is the lowest. + +Once the mode is determined, the new target can be computed for each unit. The following check is done: + +$$\left| \max(P_{min}, \min(P_{max}, (1+\hat{K} F(g)))) targetP - P \right| < \epsilon$$ + +#### Voltage and reactive power + +When the voltage regulation is disabled, the results' validity follows the condition below: + +$$\left| targetQ - Q \right| < \epsilon$$ + +On the other hand, when the voltage regulation is enabled, depending on the generator's mode, one of the three conditions should be respected: + +$$ +\begin{align*} + |V - targetV| & \leq && \epsilon && \& && minQ & \leq & Q \leq maxQ \\ + V - targetV & < & -& \epsilon && \& && |Q-maxQ| & \leq & \epsilon \\ + targetV - V & < && \epsilon && \& && |Q-minQ| & \leq & \epsilon \\ +\end{align*} +$$ + +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` +- 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. + +### Loads +To be implemented, with tests similar to generators with voltage regulation. + +### Shunts +The two following conditions must be fulfilled in valid results: + +$$ +\begin{align*} +\left| P \right| < \epsilon \\ +\left| Q + \text{#sections} * B V^2 \right| < \epsilon +\end{align*} +$$ + +### Static VAR Compensators +The following conditions must be fulfilled in valid results: +$targetP = 0$ MW +- If the regulation mode is `OFF`, then + $$\left| targetQ - Q \right| < \epsilon$$ +- If the regulation mode is `REACTIVE_POWER`, same checks as a generator without voltage regulation +- If the regulation mode is `VOLTAGE`, same checks as a generator with voltage regulation with the following bounds: +$$minQ = - Bmax * V^2$$ and $$maxQ = - Bmin V^2$$ + +### HVDC lines +To be done. + +#### VSC +Same checks as a generator. Besides, for stations paired by a cable: +$$\sum_{\text{stations}}{P} = \sum_{\text{stations}}{Loss} + Loss_{cable}$$ + +#### LCC +To be done. + +### Transformers with a ratio tap changer + +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) +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`: + +$$V_2(tap) = \rho_{tap} V_1$$ + +- With the next tap, the new voltage would be: + +$$V_2(tap+1) = \rho_{tap+1} V_1 = \frac{\rho_{tap+1}}{\rho_{tap}} V_2(tap)$$ + +We can therefore compute approximately the voltage increments corresponding to $tap-1$ and $tap+1$. + +- We then assume the *deadband* of the regulation to be equal to the voltage increase/decrease that can be performed with +taps $tap-1$ and $tap+1$: + +$$ +\begin{align*} + & \text{up deadband} = - \min(V_2(tap+1) - V_2(tap), V_2(tap-1) - V_2(tap)) \\ + & \text{down deadband} = \max(V_2(tap+1) - V_2(tap), V_2(tap-1) - V_2(tap)) \\ +\end{align*} +$$ + +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$$ + +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: +``` +$> itools loadflow-validation --case-file 20170322_1844_SN3_FR2.uct --output-folder /tmp/results +``` + +The validation results, printed to the standard output: +``` +Loading case 20170322_1844_SN3_FR2.uct +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: TWTS - result: success +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: FLOWS - result: fail +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: BUSES - result: fail +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: SVCS - result: success +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: SHUNTS - result: success +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: GENERATORS - result: fail +``` + +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 +arguments are needed: +- `load-flow` +- `compare_results`: COMPUTATION + +``` +$> itools loadflow-validation --case-file 20170322_1844_SN3_FR2.uct --output-folder tmp/loadFlowValidationResults +--verbose --output-format CSV --load-flow --compare-results COMPUTATION +``` + +The validation results, printed to the standard output: +``` +Loading case 20170322_1844_SN3_FR2.uct +Running pre-loadflow validation on network 20170322_1844_SN3_FR2.uct.uct +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: TWTS - result: success +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: GENERATORS - result: fail +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: FLOWS - result: fail +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: SHUNTS - result: success +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: BUSES - result: fail +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: SVCS - result: success +Running loadflow on network 20170322_1844_SN3_FR2.uct +Running post-loadflow validation on network 20170322_1844_SN3_FR2.uct +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: TWTS - result: success +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: GENERATORS - result: fail +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: FLOWS - result: fail +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: SHUNTS - result: success +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: BUSES - result: fail +Validate load-flow results of network 20170322_1844_SN3_FR2.uct - validation type: SVCS - result: success +``` + +Eventually, you will find in your output-folder one csv file for each validation type, containing the data pre and post +computation (load flow). + diff --git a/docs/user/itools/loadflow.md b/docs/user/itools/loadflow.md new file mode 100644 index 00000000000..e28ce3bc8aa --- /dev/null +++ b/docs/user/itools/loadflow.md @@ -0,0 +1,113 @@ +--- +layout: default +--- + +# 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. + +## Usage +``` +$> itools loadflow --help +usage: itools [OPTIONS] loadflow --case-file [-E ] + [--export-parameters ] [--help] [-I ] + [--import-parameters ] [--output-case-file ] + [--output-case-format ] [--output-file ] + [--output-format ] [--parameters-file ] + +Available options are: + --config-name Override configuration file name + +Available arguments are: + --case-file the case path +-E use value for given exporter + parameter + --export-parameters the exporter configuration file + --help display the help and quit +-I use value for given importer + parameter + --import-parameters the importer configuation file + --output-case-file modified network base name + --output-case-format modified network output format + [CGMES, AMPL, XIIDM] + --output-file loadflow results output path + --output-format loadflow results output format + [CSV, JSON] + --parameters-file loadflow parameters as JSON file +``` + +### Required options + +**\-\-case-file**: This option defines the path of the case file on which the power flow simulation is run. The [supported formats](../../grid_exchange_formats/index.md) depend on the execution class path. + +### Optional options + +**\-\-export-parameters** +This option defines the path of the exporter's configuration file. It's possible to overload one or many parameters using the `-E property=value` syntax. The list of supported properties depends on the [output format](../../grid_exchange_formats/index.md). + +**\-\-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). + +**\-\-output-case-file** +This option defines the path where to export the modified network. + +**\-\-output-case-format** +This option defines the format of the output case file. The list of [supported formats](../../grid_exchange_formats/index.md) are listed between brackets in the command help. This option is required if `--output-case-file` is used. + +**\-\-output-file** +This option defines the path where to export the [results](../../simulation/loadflow/loadflow.md#outputs) of the load flow. + +**\-\-output-format** +This option defines the format of the output file. The supported format are `CSV` and `JSON`. This option is required if the `--output-file` is used. + +**\-\-parameters-file** +This option defines the path of the [parameters](#parameters) file of the simulation. If this option is not used, the simulation is run with the default parameters. + +## Simulators + +The available power flow simulators implementations are described [here](../../simulation/loadflow/loadflow.md#implementations). + +## Parameters +The available parameters are described [here](../../simulation/loadflow/loadflow.md#parameters). + +## Results +The expected results are described in the [load flow documentation](../../simulation/loadflow/loadflow.md#outputs) + +## Examples +The following example shows how to run a power flow simulation, using the default configuration: +``` +$> itools loadflow --case-file case.xiidm +Loading network 'case.xiidm' +loadflow results: ++--------+-----------------------------------------------------------------------------------------+ +| Ok | Metrics | ++--------+-----------------------------------------------------------------------------------------+ +| true | {nbIter=4, dureeCalcul=0.001569, cause=0, contraintes=0, statut=OK, csprMarcheForcee=0} | ++--------+-----------------------------------------------------------------------------------------+ +Components results: ++------------------+-----------+-----------------+--------------+--------------------+ +| Component number | Status | Iteration count | Slack bus ID | Slack bus mismatch | ++------------------+-----------+-----------------+--------------+--------------------+ +| 0 | CONVERGED | 8 | BUS_0 | -0,00954794 | ++------------------+-----------+-----------------+--------------+--------------------+ +``` + +The following example shows how to run a power flow simulation, using a parameters file: +``` +$> itools loadflow --case-file case.xiidm --parameters-file loadflowparameters.json +loadflow results: ++--------+-----------------------------------------------------------------------------------------+ +| Ok | Metrics | ++--------+-----------------------------------------------------------------------------------------+ +| true | {nbIter=4, dureeCalcul=0.001569, cause=0, contraintes=0, statut=OK, csprMarcheForcee=0} | ++--------+-----------------------------------------------------------------------------------------+ +Components results: ++------------------+-----------+-----------------+--------------+--------------------+ +| Component number | Status | Iteration count | Slack bus ID | Slack bus mismatch | ++------------------+-----------+-----------------+--------------+--------------------+ +| 0 | CONVERGED | 8 | BUS_0 | -0,00954794 | ++------------------+-----------+-----------------+--------------+--------------------+ +``` + +## See also +TODO