Security Analysis

Overview

The Security Analysis module performs N-1 security analysis to identify violations that occur after contingencies (outages of network elements). It evaluates the network’s ability to withstand single or multiple element failures while maintaining operational constraints.

Creating Security Analysis

create_analysis

Create a security analysis instance.

pp.security.create_analysis() -> SecurityAnalysis

return

SecurityAnalysis

A new security analysis instance

Example:

import pypowsybl as pp

network = pp.network.create_ieee14()
analysis = pp.security.create_analysis()

SecurityAnalysis Class

The SecurityAnalysis class allows you to configure and run security analysis on a network.

Adding Contingencies

add_single_element_contingency

Add a contingency involving a single network element.

analysis.add_single_element_contingency(
    contingency_id: str,
    element_id: str
)

contingency_id

str

required

Unique identifier for the contingency

element_id

str

required

ID of the network element to trip (line, transformer, generator, etc.)

Example:

analysis.add_single_element_contingency('LINE_1_OUTAGE', 'LINE_1')
analysis.add_single_element_contingency('GEN_2_OUTAGE', 'GEN_2')

add_multiple_elements_contingency

Add a contingency involving multiple network elements.

analysis.add_multiple_elements_contingency(
    contingency_id: str,
    element_ids: List[str]
)

contingency_id

str

required

Unique identifier for the contingency

element_ids

List[str]

required

List of network element IDs to trip simultaneously

Example:

analysis.add_multiple_elements_contingency(
    'DOUBLE_OUTAGE',
    ['LINE_1', 'LINE_2']
)

Adding Monitored Elements

add_monitored_elements

Add elements to be monitored by the security analysis.

analysis.add_monitored_elements(
    contingency_context_type: ContingencyContextType = ContingencyContextType.ALL,
    contingency_ids: List[str] = None,
    branch_ids: List[str] = None,
    voltage_level_ids: List[str] = None,
    three_windings_transformer_ids: List[str] = None
)

contingency_context_type

ContingencyContextType

default:"ALL"

When to monitor the elements:

ALL: Monitor for all contingencies
NONE: Monitor only in N situation (pre-contingency)
SPECIFIC: Monitor for specific contingencies

contingency_ids

List[str]

List of contingency IDs for which to monitor (used with SPECIFIC context)

branch_ids

List[str]

List of branch IDs to monitor

voltage_level_ids

List[str]

List of voltage level IDs to monitor

three_windings_transformer_ids

List[str]

List of three-winding transformer IDs to monitor

Example:

# Monitor specific branches for all contingencies
analysis.add_monitored_elements(
    branch_ids=['LINE_1', 'LINE_2', 'LINE_3']
)

# Monitor elements only in pre-contingency state
analysis.add_precontingency_monitored_elements(
    branch_ids=['LINE_4', 'LINE_5']
)

# Monitor for specific contingencies
analysis.add_postcontingency_monitored_elements(
    contingency_ids=['LINE_1_OUTAGE', 'LINE_2_OUTAGE'],
    branch_ids=['LINE_6']
)

Running Analysis

run_ac

Run an AC security analysis.

analysis.run_ac(
    network: Network,
    parameters: Parameters = None,
    provider: str = '',
    report_node: ReportNode = None
) -> SecurityAnalysisResult

network

Network

required

Network on which to run the security analysis

parameters

Parameters

Security analysis parameters

provider

str

default:""

Security analysis implementation provider. If empty, uses default

report_node

ReportNode

Reporter for execution reports

return

SecurityAnalysisResult

Security analysis result containing violations and monitored elements information

Example:

import pypowsybl as pp

network = pp.network.create_ieee14()
analysis = pp.security.create_analysis()

# Add contingencies
analysis.add_single_element_contingency('LINE_1_OUT', 'L1-2-1')
analysis.add_single_element_contingency('LINE_2_OUT', 'L1-5-1')

# Run analysis
result = analysis.run_ac(network)

# Check for violations
print(f"Pre-contingency violations: {len(result.pre_contingency_result.limit_violations)}")
for contingency_result in result.post_contingency_results:
    print(f"Contingency {contingency_result.contingency_id}: "
          f"{len(contingency_result.limit_violations)} violations")

run_dc

Run a DC security analysis.

analysis.run_dc(
    network: Network,
    parameters: Parameters = None,
    provider: str = '',
    report_node: ReportNode = None
) -> SecurityAnalysisResult

Parameters are identical to run_ac. DC security analysis uses simplified DC power flow for faster computation.

Parameters

Parameters Class

Configure security analysis execution.

pp.security.Parameters(
    load_flow_parameters: pp.loadflow.Parameters = None,
    increased_violations_parameters: IncreasedViolationsParameters = None,
    provider_parameters: dict = None
)

load_flow_parameters

pp.loadflow.Parameters

Load flow parameters used for security analysis calculations. See Load Flow Parameters

increased_violations_parameters

IncreasedViolationsParameters

Define what violations should be considered increased between N and post-contingency situations

provider_parameters

dict

Provider-specific parameters as key-value pairs

Example:

import pypowsybl as pp

lf_params = pp.loadflow.Parameters(
    distributed_slack=True
)

sa_params = pp.security.Parameters(
    load_flow_parameters=lf_params
)

result = analysis.run_ac(network, parameters=sa_params)

IncreasedViolationsParameters

Define thresholds for identifying increased violations.

pp.security.IncreasedViolationsParameters(
    flow_proportional_threshold: float = 0.1,
    low_voltage_proportional_threshold: float = 0.0,
    low_voltage_absolute_threshold: float = 0.0,
    high_voltage_proportional_threshold: float = 0.0,
    high_voltage_absolute_threshold: float = 0.0
)

flow_proportional_threshold

float

default:"0.1"

Proportional threshold for flow violations (default 10%)

low_voltage_proportional_threshold

float

default:"0.0"

Proportional threshold for low voltage violations

low_voltage_absolute_threshold

float

default:"0.0"

Absolute threshold for low voltage violations (in kV)

high_voltage_proportional_threshold

float

default:"0.0"

Proportional threshold for high voltage violations

high_voltage_absolute_threshold

float

default:"0.0"

Absolute threshold for high voltage violations (in kV)

Results

SecurityAnalysisResult

Contains the complete results of a security analysis.

pre_contingency_result

PreContingencyResult

Results for the N situation (no contingency)

post_contingency_results

List[PostContingencyResult]

List of results for each contingency

limit_violations

DataFrame

DataFrame of all limit violations across all contingencies

branch_results

DataFrame

DataFrame with power flow results for monitored branches

bus_results

DataFrame

DataFrame with voltage results for monitored buses

PostContingencyResult

Results for a single contingency.

contingency_id

str

ID of the contingency

status

ComputationStatus

Computation status:

CONVERGED: Load flow converged
MAX_ITERATION_REACHED: Maximum iterations reached
FAILED: Computation failed

limit_violations

DataFrame

DataFrame of limit violations for this contingency

Example:

result = analysis.run_ac(network)

# Access pre-contingency violations
pre_violations = result.pre_contingency_result.limit_violations
print(f"Pre-contingency violations: {len(pre_violations)}")

# Access post-contingency results
for pc_result in result.post_contingency_results:
    if pc_result.status == pp.security.ComputationStatus.CONVERGED:
        violations = pc_result.limit_violations
        print(f"{pc_result.contingency_id}: {len(violations)} violations")
        if len(violations) > 0:
            print(violations[['subject_id', 'limit_type', 'value', 'limit']])

Provider Management

get_provider_names

Get the list of available security analysis providers.

pp.security.get_provider_names() -> List[str]

return

List[str]

List of available provider names

get_default_provider

Get the current default security analysis provider.

pp.security.get_default_provider() -> str

return

str

Name of the default provider

set_default_provider

Set the default security analysis provider.

pp.security.set_default_provider(provider: str)

provider

str

required

Name of the provider to set as default

Enumerations

ContingencyContextType

ALL: Apply to all contingencies
NONE: Apply to N situation only (pre-contingency)
SPECIFIC: Apply to specific contingencies

ComputationStatus

CONVERGED: Computation converged successfully
MAX_ITERATION_REACHED: Maximum iterations reached
FAILED: Computation failed

ConditionType

Types of conditions for contingencies:

TRUE_CONDITION
ANY_VIOLATION_CONDITION
AT_LEAST_ONE_VIOLATION_CONDITION

ContingencyContainer

Base class providing contingency management methods (inherited by SecurityAnalysis).

get_contingencies

Get the list of defined contingencies.

analysis.get_contingencies() -> DataFrame

return

DataFrame

DataFrame containing all defined contingencies with their elements

Core

Advanced

Integrations

Utilities

Overview

Creating Security Analysis

create_analysis

SecurityAnalysis Class

Adding Contingencies

add_single_element_contingency

add_multiple_elements_contingency

Adding Monitored Elements

add_monitored_elements

Running Analysis

run_ac

run_dc

Parameters

Parameters Class

IncreasedViolationsParameters

Results

SecurityAnalysisResult

PostContingencyResult

Provider Management

get_provider_names

get_default_provider

set_default_provider

Enumerations

ContingencyContextType

ComputationStatus

ConditionType

ContingencyContainer

get_contingencies

See Also

Build docs developers (and LLMs) love

Core

Advanced

Integrations

Utilities

​Overview

​Creating Security Analysis

​create_analysis

​SecurityAnalysis Class

​Adding Contingencies

​add_single_element_contingency

​add_multiple_elements_contingency

​Adding Monitored Elements

​add_monitored_elements

​Running Analysis

​run_ac

​run_dc

​Parameters

​Parameters Class

​IncreasedViolationsParameters

​Results

​SecurityAnalysisResult

​PostContingencyResult

​Provider Management

​get_provider_names

​get_default_provider

​set_default_provider

​Enumerations

​ContingencyContextType

​ComputationStatus

​ConditionType

​ContingencyContainer

​get_contingencies

​See Also

Build docs developers (and LLMs) love

Overview

Creating Security Analysis

create_analysis

SecurityAnalysis Class

Adding Contingencies

add_single_element_contingency

add_multiple_elements_contingency

Adding Monitored Elements

add_monitored_elements

Running Analysis

run_ac

run_dc

Parameters

Parameters Class

IncreasedViolationsParameters

Results

SecurityAnalysisResult

PostContingencyResult

Provider Management

get_provider_names

get_default_provider

set_default_provider

Enumerations

ContingencyContextType

ComputationStatus

ConditionType

ContingencyContainer

get_contingencies

See Also