iTools compare security analysis results#

The compare-security-analysis-results command is used to compare security-analysis results, stored in JSON.

The outcome of the comparison is success if the results are equivalent, fail otherwise.

This tool compares for the pre-contingency state and for all the post-contingency states of the two results:

  • the outcome (convergence/divergence) of the load flow computations

  • the values of the constraints violations

Two security analysis results are considered equivalent if all the following conditions are satisfied:

  • for all the pre-contingency and post-contingency states, the corresponding (i.e., related to the same state) outcome of the load flow computation is the same

  • for all the constraint violations, the difference of value of a corresponding (i.e., related to the same contingency and equipment) violation is less than a predefined threshold

  • if a constraint violation is contained in just one result, the violation is less than a predefined threshold

  • if a contingency is contained in just one result, all the post-contingency violations are less than a predefined threshold

The comparison process can optionally output in a CSV file all the compared values (pre- and post-contingency load flow computation outcomes, and related constraints violations), with a corresponding comparison result (equivalent,different). See example below.

Contingency;StatusResult1;StatusResult2;Equipment;End;ViolationType;ViolationNameResult1;ValueResult1;LimitResult1;ViolationNameResult2;ValueResult2;LimitResult2;ActionsResult1;ActionsResult2;Comparison
;converge;converge;;;;;;;;;;;;equivalent
;;;NHV1_NHV2_1;ONE;CURRENT;;1100,00;950,000;;1100,09;950,000;;;equivalent
contingency1;converge;converge;;;;;;;;;;;;equivalent
contingency1;;;NHV1_NHV2_1;ONE;CURRENT;;1100,00;950,000;;1100,09;950,000;;;equivalent
contingency1;;;NHV1_NHV2_1;TWO;CURRENT;;1100,00;950,000;;1101,00;950,000;;;different
contingency2;converge;converge;;;;;;;;;;;;equivalent
contingency2;;;NHV1_NHV2_1;ONE;CURRENT;;1100,00;950,000;;1100,09;950,000;;;equivalent
contingency2;;;NHV1_NHV2_2;ONE;CURRENT;;1100,00;950,000;;1100,09;950,000;;;equivalent

Usage#

$> itools compare-security-analysis-results --help
usage: itools [OPTIONS] compare-security-analysis-results [--help] --output-file
       <FILE> --result1-file <FILE> --result2-file <FILE> [--threshold
       <THRESHOLD>]

Available options are:
    --config-name <CONFIG_NAME>   Override configuration file name

Available arguments are:
    --help                    display the help and quit
    --output-file <FILE>      output file path, where the comparison results
                              will be stored
    --result1-file <FILE>     security analysis result 1 file path
    --result2-file <FILE>     security analysis result 2 file path
    --threshold <THRESHOLD>   threshold used for results comparison, default is 0.0

Required parameters#

--output-file
This parameter defines the path of the output file, where the comparison results will be stored.

--result1-file
This parameter defines the path of the JSON file containing the first security analysis result.

--result2-file
This parameter defines the path of the JSON file containing the second security analysis result.

Optional parameters#

threshold#

Use the --threshold parameter to specify the threshold used for comparing values of the two security analysis results. Default value is 0.

Examples#

This example shows how to compare two security analysis results and to store the comparison results in the $HOME/comparison_results.csv file:

$> itools compare-security-analysis-results --result1-file $HOME/result1.json --result2-file $HOME/result2.json --output-file $HOME/comparison_results.csv
Comparison result: fail

This example shows how to specify the threshold to be used in the comparison:

$> itools compare-security-analysis-results --result1-file $HOME/result1.json --result2-file $HOME/result2.json --output-file $HOME/comparison_results.csv  --threshold 0.1
Comparison result: success