# Copyright (c) 2023, RTE (http://www.rte-france.com)
# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
# SPDX-License-Identifier: MPL-2.0
#
from __future__ import annotations
import warnings
from typing import List, Dict
from pypowsybl import _pypowsybl
from pypowsybl.security import ContingencyContainer
from .sensitivity_analysis_result import DEFAULT_MATRIX_ID, TO_REMOVE
from pypowsybl._pypowsybl import PyPowsyblError, ContingencyContextType, SensitivityFunctionType, SensitivityVariableType
from .zone import Zone
class SensitivityAnalysis(ContingencyContainer):
""" Base class for sensitivity analysis. Do not instantiate it directly!"""
def __init__(self, handle: _pypowsybl.JavaHandle):
ContingencyContainer.__init__(self, handle)
self.functions_ids: Dict[str, List[str]] = {}
self.function_data_frame_index: Dict[str, List[str]] = {}
[docs] def set_zones(self, zones: List[Zone]) -> None:
"""
Define zones that will be used in branch flow factor matrix.
Args:
zones: a list of zones
"""
_zones = []
for zone in zones:
_zones.append(_pypowsybl.Zone(zone.id, list(zone.shift_keys_by_injections_ids.keys()),
list(zone.shift_keys_by_injections_ids.values())))
_pypowsybl.set_zones(self._handle, _zones)
@staticmethod
def _process_variable_ids(variables_ids: List) -> tuple:
flatten_variables_ids = []
branch_data_frame_index = []
for variable_id in variables_ids:
if isinstance(variable_id, str): # this is an ID
flatten_variables_ids.append(variable_id)
branch_data_frame_index.append(variable_id)
elif isinstance(variable_id, tuple): # this is a power transfer
if len(variable_id) != 2:
raise PyPowsyblError('Power transfer factor should be describe with a tuple 2')
flatten_variables_ids.append(variable_id[0])
flatten_variables_ids.append(variable_id[1])
branch_data_frame_index.append(variable_id[0] + ' -> ' + variable_id[1])
branch_data_frame_index.append(TO_REMOVE)
else:
raise PyPowsyblError(f'Unsupported factor variable type {type(variable_id)}')
return (flatten_variables_ids, branch_data_frame_index)
def set_branch_flow_factor_matrix(self, branches_ids: List[str], variables_ids: List[str]) -> None:
"""
.. deprecated:: 0.14.0
Use :meth:`add_branch_flow_factor_matrix` instead.
Defines branch active power flow factor matrix, with a list of branches IDs and a list of variables.
A variable could be:
- a network element ID: injections, PSTs, dangling lines and HVDC lines are supported
- a zone ID
- a couple of zone ID to define a transfer between 2 zones
Args:
branches_ids: IDs of branches for which active power flow sensitivities should be computed
variables_ids: variables which may impact branch flows,to which we should compute sensitivities
"""
warnings.warn("set_branch_flow_factor_matrix is deprecated, use add_branch_flow_factor_matrix instead",
DeprecationWarning)
self.add_branch_flow_factor_matrix(branches_ids, variables_ids)
[docs] def add_branch_flow_factor_matrix(self, branches_ids: List[str], variables_ids: List[str],
matrix_id: str = DEFAULT_MATRIX_ID) -> None:
"""
Defines branch active power flow factor matrix, with a list of branches IDs and a list of variables.
A variable could be:
- a network element ID: injections, PSTs, dangling lines and HVDC lines are supported
- a zone ID
- a couple of zone ID to define a transfer between 2 zones
Args:
branches_ids: IDs of branches for which active power flow sensitivities should be computed
variables_ids: variables which may impact branch flows,to which we should compute sensitivities
matrix_id: The matrix unique identifier, to be used to retrieve the sensibility value
"""
self.add_factor_matrix(branches_ids, variables_ids, [], ContingencyContextType.ALL,
SensitivityFunctionType.BRANCH_ACTIVE_POWER_1, SensitivityVariableType.AUTO_DETECT, matrix_id)
[docs] def add_precontingency_branch_flow_factor_matrix(self, branches_ids: List[str], variables_ids: List[str],
matrix_id: str = DEFAULT_MATRIX_ID) -> None:
"""
Defines branch active power flow factor matrix for the base case, with a list of branches IDs and a list of variables.
A variable could be:
- a network element ID: injections, PSTs, dangling lines and HVDC lines are supported
- a zone ID
- a couple of zone ID to define a transfer between 2 zones
Args:
branches_ids: IDs of branches for which active power flow sensitivities should be computed
variables_ids: variables which may impact branch flows,to which we should compute sensitivities
matrix_id: The matrix unique identifier, to be used to retrieve the sensibility value
"""
self.add_factor_matrix(branches_ids, variables_ids, [], ContingencyContextType.NONE,
SensitivityFunctionType.BRANCH_ACTIVE_POWER_1, SensitivityVariableType.AUTO_DETECT, matrix_id)
[docs] def add_postcontingency_branch_flow_factor_matrix(self, branches_ids: List[str], variables_ids: List[str],
contingencies_ids: List[str],
matrix_id: str = DEFAULT_MATRIX_ID) -> None:
"""
Defines branch active power flow factor matrix for specific post contingencies states, with a list of branches IDs and a list of variables.
A variable could be:
- a network element ID: injections, PSTs, dangling lines and HVDC lines are supported
- a zone ID
- a couple of zone ID to define a transfer between 2 zones
Args:
branches_ids: IDs of branches for which active power flow sensitivities should be computed
variables_ids: variables which may impact branch flows,to which we should compute sensitivities
contingencies_ids: List of the IDs of the contingencies to simulate
matrix_id: The matrix unique identifier, to be used to retrieve the sensibility value
"""
self.add_factor_matrix(branches_ids, variables_ids, contingencies_ids, ContingencyContextType.SPECIFIC,
SensitivityFunctionType.BRANCH_ACTIVE_POWER_1, SensitivityVariableType.AUTO_DETECT, matrix_id)
def add_factor_matrix(self, functions_ids: List[str], variables_ids: List[str], contingencies_ids: List[str],
contingency_context_type: ContingencyContextType,
sensitivity_function_type: SensitivityFunctionType,
sensitivity_variable_type: SensitivityVariableType = SensitivityVariableType.AUTO_DETECT,
matrix_id: str = DEFAULT_MATRIX_ID) -> None:
"""
Defines branch active power factor matrix, with a list of branches IDs and a list of variables.
A variable could be:
- a network element ID: injections, PSTs, dangling lines and HVDC lines are supported
- a zone ID
- a couple of zone ID to define a transfer between 2 zones
sensitivity_function_type can be:
- BRANCH_ACTIVE_POWER_1
- BRANCH_CURRENT_1
- BRANCH_REACTIVE_POWER_1
- BRANCH_ACTIVE_POWER_2
- BRANCH_CURRENT_2
- BRANCH_REACTIVE_POWER_2
- BRANCH_ACTIVE_POWER_3
- BRANCH_CURRENT_3
- BRANCH_REACTIVE_POWER_3
sensitivity_variable_type can be:
- INJECTION_ACTIVE_POWER
- INJECTION_REACTIVE_POWER
- TRANSFORMER_PHASE
- BUS_TARGET_VOLTAGE
- HVDC_LINE_ACTIVE_POWER
- TRANSFORMER_PHASE_1
- TRANSFORMER_PHASE_2
- TRANSFORMER_PHASE_3
Args:
functions_ids: functions for which the sensitivities for the sensitivity_function_type should be computed
variables_ids: variables which may impact functions,to which we should compute sensitivities
contingencies_ids: List of the IDs of the contingencies to simulate
contingency_context_type: the contingency context type it could be ALL, NONE or SPECIFIC
sensitivity_function_type: the function type of sensitivity to compute
sensitivity_variable_type: the variable type of sensitivity to compute, automatically guessed (best effort) if value is AUTO_DETECT
matrix_id: The matrix unique identifier, to be used to retrieve the sensibility value
"""
(flatten_variables_ids, function_data_frame_index) = self._process_variable_ids(variables_ids)
_pypowsybl.add_factor_matrix(self._handle, matrix_id, functions_ids,
flatten_variables_ids, contingencies_ids, contingency_context_type,
sensitivity_function_type, sensitivity_variable_type)
self.functions_ids[matrix_id] = functions_ids
self.function_data_frame_index[matrix_id] = function_data_frame_index