Power System Blocks

security-analysis

The security-analysis command is used to detect security violations on pre-contingencies and post-contingencies states.

Usage

$>cd  <POWSYBL_HOME>/bin
$> ./itools security-analysis --help
usage: itools [OPTIONS] security-analysis --case-file <FILE>
       [--contingencies-file <FILE>] [--help] [--limit-types <LIMIT-TYPES>]
       [--output-file <FILE>] [--output-format <FORMAT>] [--parameters-file
       <FILE>] [--with-extensions <EXTENSIONS>]

Available options are:
    --config-name <CONFIG_NAME>   Override configuration file name
    --parallel                    Run command in parallel mode

Available arguments are:
    --case-file <FILE>               the case path
    --contingencies-file <FILE>      the contingencies path
    --external                       external execution
    --help                           display the help and quit
    --limit-types <LIMIT-TYPES>      limit type filter (all if not set)
    --output-file <FILE>             the output path
    --output-format <FORMAT>         the output format [JSON]
    --parameters-file <FILE>         loadflow parameters as JSON file
    --with-extensions <EXTENSIONS>   the extension list to enable

Allowed LIMIT-TYPES values are [CURRENT, LOW_VOLTAGE, HIGH_VOLTAGE,
LOW_SHORT_CIRCUIT_CURRENT, HIGH_SHORT_CIRCUIT_CURRENT, OTHER]
Allowed EXTENSIONS values are []

Required options

case-file

Use the --case-file parameter to specify the path of the case file.

Optional options

contingencies-file

Use the --contingencies-file parameter to specify the path of the contingencies file. If this parameter is not set, the security violations are checked on the N-state only.

external

Use the --external parameter to run the security analysis in an external process. Read the external-security-analysis-config documentation page to learn how to configure the external mode.

limit-types

Use the --limit-types parameter to filter certain types of violations. This parameter overrides the default configuration. The available LimitViolationType values are:

output-file

Use the --output-file parameter to specify the path of the output file. If this parameter is not set, the results are displayed to the console.

output-format

Use the --output-format parameter to specify the format of the output file. This parameter is required if the output-file parameter is used. The supported format are:

parameters-file

Use the --parameters-file parameter to specify the path of the configuration file.

with-extensions

Use the --with-extensions parameter to activate a list of com.powsybl.security.interceptors.SecurityAnalysisInterceptor implementations.

Configuration

To run a security analysis, one have to configure the the componentDefaultConfig module to indicate the implementations to use for:

YAML version

componentDefaultConfig:
    ContingenciesProviderFactory: com.powsybl.action.dsl.GroovyDslContingenciesProviderFactory
    SecurityAnalysisFactory: com.powsybl.security.SecurityAnalysisFactoryImpl
    LoadFlowFactory: com.powsybl.loadflow.mock.LoadFlowFactoryMock

XML version

<config>
    <componentDefaultConfig>
        <ContingenciesProviderFactory>com.powsybl.action.dsl.GroovyDslContingenciesProviderFactory</ContingenciesProviderFactory>
        <SecurityAnalysisFactory>com.powsybl.security.SecurityAnalysisFactoryImpl</SecurityAnalysisFactory>
        <LoadFlowFactory>com.powsybl.loadflow.mock.LoadFlowFactoryMock</LoadFlowFactory>
    </componentDefaultConfig>
</config>

To learn more about contingencies or available ContingenciesProvider read this documentation page.

To learn how to filter violations, read the limit-violation-default-filter module documentation page.

To learn more about configuration files, read the SecurityAnalysisParameters documentation page.

Examples

Example 1

The following example shows how to run security analysis to detect only pre-contingency violation, for a given network:

$> itools security-analysis --case-file 20170322_1844_SN3_FR2.uct

The analysis results will be printed to the standard output:

Loading network '20170322_1844_SN3_FR2.uct'
Pre-contingency violations:
+--------+---------------------+---------+---------+--------------+----------------+-----------------+------------+-----------+------------------+----------------+
| Action | Equipment (1)       | End     | Country | Base voltage | Violation type | Violation name  | Value      | Limit     | abs(value-limit) | Loading rate % |
+--------+---------------------+---------+---------+--------------+----------------+-----------------+------------+-----------+------------------+----------------+
|        | FFNGEN71 FFNHV111 1 | FFNHV17 | FR      |           27 | CURRENT        | Permanent limit | 15350.0808 | 9999.0000 |        5351.0808 |         153.52 |
+--------+---------------------+---------+---------+--------------+----------------+-----------------+------------+-----------+------------------+----------------+

Example 2

The following example shows how to run security-analysis to identify the post-contingency security status of given network:

$> cat contingencies.groovy
contingency('HV_line_1') {
    equipments 'NHV1_NHV2_1'
}
contingency('HV_line_2') {
    equipments 'NHV1_NHV2_2'
}
$> itools security-analysis --case-file eurostag_example.xiidm --contingencies-file contingencies.groovy
Loading network 'eurostag_example.xiidm'
Pre-contingency violations:
+--------+---------------+-----+---------+--------------+----------------+----------------+-------+-------+------------------+----------------+
| Action | Equipment (0) | End | Country | Base voltage | Violation type | Violation name | Value | Limit | abs(value-limit) | Loading rate % |
+--------+---------------+-----+---------+--------------+----------------+----------------+-------+-------+------------------+----------------+
Post-contingency limit violations:
+-------------+----------+--------+---------------+-------+---------+--------------+----------------+-----------------+-----------+-----------+------------------+----------------+
| Contingency | Status   | Action | Equipment (4) | End   | Country | Base voltage | Violation type | Violation name  | Value     | Limit     | abs(value-limit) | Loading rate % |
+-------------+----------+--------+---------------+-------+---------+--------------+----------------+-----------------+-----------+-----------+------------------+----------------+
| HV_line_1   | converge |        | Equipment (2) |       |         |              |                |                 |           |           |                  |                |
|             |          |        | NHV1_NHV2_2   | VLHV1 | FR      |          380 | CURRENT        | Permanent limit | 1008.9289 |  500.0000 |         508.9289 |         201.79 |
|             |          |        | NHV1_NHV2_2   | VLHV2 | FR      |          380 | CURRENT        | Permanent limit | 1047.8260 |  500.0000 |         547.8260 |         209.57 |
| HV_line_2   | converge |        | Equipment (2) |       |         |              |                |                 |           |           |                  |                |
|             |          |        | NHV1_NHV2_1   | VLHV1 | FR      |          380 | CURRENT        | Permanent limit | 1008.9289 | 1000.0000 |           8.9289 |         100.89 |
|             |          |        | NHV1_NHV2_1   | VLHV2 | FR      |          380 | CURRENT        | Permanent limit | 1047.8260 | 1000.0000 |          47.8260 |         104.78 |
+-------------+----------+--------+---------------+-------+---------+--------------+----------------+-----------------+-----------+-----------+------------------+----------------+

Maven configuration

To use the security-analysis command, add the following dependencies to the pom.xml file.

<dependency>
    <groupId>com.powsybl</groupId>
    <artifactId>powsybl-security-analysis-api</artifactId>
    <version>${powsybl.version}</version>
</dependency>

Security-analysis implementations

Slow implementation

Read this documentation page to learn how to configure powsybl to use the SecurityAnalysisImpl implementation, a load-flow based implementation for security limits detection.

Hades2

Read this documentation page to learn how to configure powsybl to use Hades2, a RTE load-flow tool, for security analysis.