Short circuit API
Introduction
When a short circuit occurs in a network, the currents on equipment can be so high that they exceed their rated values. Simulating faults on the network is important to verify that the short circuits are well detected and do not damage the equipments.
The short circuit API allows to compute the currents and voltages on a network after a fault. For the moment, no simulator is available to compute the analysis, but it is possible to plug one to this API.
Parameters
Available parameters
The parameters to be used for the short circuit calculation should be defined in the config.yml file. For example, here are some valid short circuit parameters:
short-circuit-parameters:
with-voltage-result: false
with-feeder-result: true
with-limit-violations: true
study-type: TRANSIENT
with-fortescue-result: false
min-voltage-drop-proportional-threshold: 20
Available parameters in the short circuit API are stored in com.powsybl.shortcircuit.ShortCircuitParameters. They are all optional.
with-limit-violations
This property indicates whether limit violations should be returned after the computation. The violations that should be used are LOW_SHORT_CIRCUIT_CURRENT and HIGH_SHORT_CIRCUIT_CURRENT.
It can be used to filter results where the computed short circuit current is too high or too low. The default value is true.
with-fortescue-result
This property indicates if the computed results, like currents and voltages, should be returned only in three-phased magnitude or detailed with magnitude and angle on each phase.
According to this property, different classes to return results can be used. If it is set to false, the classes MagnitudeFaultResult, MagnitudeFeederResult and MagnitudeShortCircuitBusResult should be used.
If the property is true, the classes FortescueFaultResult, FortescueFeederResult and FortescueShortCircuitBusResult should be used. All these classes are in com.powsybl.shortcircuit.
The default value is true.
with-feeder-result
This property indicates if the contributions of each feeder to the short circuit current at the fault node should be computed.
If the property is set to true, the results can be stored in class com.powsybl.shortcircuit.FeederResult.
The default value is true.
study-type
This property indicates the type of short circuit study. It can be:
SUB_TRANSIENT: it is the first stage of the short circuit, right when the fault happens. The subtransient reactance of generators will be used.TRANSIENT: the second stage of the short circuit, before the system stabilizes. The transient reactance of generators will be used.STEADY_STATE: the last stage, once all transient effects are gone.
The default value is TRANSIENT. The transient and subtransient reactances of the generators are stored in the short circuit generator extension.
with-voltage-result
This property indicates if the voltage profile should be computed on every node of the network. The results, if this property is true, should be stored in class com.powsybl.shortcircuit.ShortCircuitBusResult. The default value is true.
min-voltage-drop-proportional-threshold
This property indicates a threshold to filter the voltage results. Only the nodes where the voltage drop due to the short circuit is above this property are be kept.
The voltage drop is calculated as the ratio between the initial voltage magnitude on the node and the voltage magnitude on the node after the fault. The default value is 0.
FaultParameters
It is possible to override parameters for each fault by creating an instance of com.powsybl.shortcircuit.FaultParameters. This object will take the fault to which it applies and all the parameters
for this specific fault. One FaultParameters corresponds to one Fault.
A list of FaultParameters can be given as an input to the API with specific parameters for one or multiple faults. If a fault has no FaultParameters corresponding, then the general parameters will be used.
Inputs
The API takes as inputs:
A network
It is the network on which the computation will be done.
A list of faults
The API takes as input a list of faults on which the calculation should be done. Faults on nodes and on lines are supported.
Each fault can either be an instance of com.powsybl.shortcircuit.BusFault or com.powsybl.shortcircuit.BranchFault.
The attributes to fill of a BusFault are:
| Attribute | Type | Unit | Required | Default value | Description |
|---|---|---|---|---|---|
| id | String | - | yes | - | The id of the fault |
| elementId | String | - | yes | - | The id of the bus on which the fault will be simulated (bus/view topology) |
| r | double | Ω | no | 0 | The fault resistance to ground |
| x | double | Ω | no | 0 | The fault reactance to ground |
| connection | ConnectionType | - | no | ConnectionType.SERIES |
The way the resistance and reactance of the fault are connected to the ground: in series or in parallel |
| faultType | FaultType | - | no | FaultType.THREE_PHASE |
The type of fault simulated: can be three-phased or single-phased |
The attributes to fill of a BranchFault are:
| Attribute | Type | Unit | Required | Default value | Description |
|---|---|---|---|---|---|
| id | String | - | yes | - | The id of the fault |
| elementId | String | - | yes | - | The id of the branch on which the fault will be simulated |
| r | double | Ω | no | 0 | The fault resistance to ground |
| x | double | Ω | no | 0 | The fault reactance to ground |
| connection | ConnectionType | - | no | ConnectionType.SERIES |
The way the resistance and reactance of the fault are connected to the ground: in series or in parallel |
| faultType | FaultType | - | no | FaultType.THREE_PHASE |
The type of fault simulated: can be three-phased or single-phased |
| proportionalLocation | double | % | yes | - | The position where the fault should be simulated, in percent of the line |
A list of FaultParameters
Optionally, it is possible to specify a list of FaultParameters. Each FaultParameter will override the default parameters for a given fault.
For more information on parameters, see above.
Outputs
The results of the short circuit analysis are stored in com.powsybl.shortcircuit.ShortCircuitAnalysisResult. This class gathers the results for every fault, they are accessible either by the ID of the fault or the ID of the element on which the fault is simulated.
For each fault, an object com.powsybl.shortcircuit.FaultResult is returned.
Depending on with-fortescue-result, the returned result should either be an instance of com.powsybl.shortcircuit.MagnitudeFaultResult or com.powsybl.shortcircuit.FortescueFaultResult.
Both classes contain the following attributes:
| Attribute | Type | Unit | Required | Default value | Description |
|---|---|---|---|---|---|
| fault | Fault | - | yes | - | The fault that was simulated |
| status | Status | - | yes | - | The status of the computation, see below for more details |
| shortCircuitPower | double | MVA | yes | - | The value of the short circuit power |
| timeConstant | Duration | - | yes | - | The duration before reaching the permanent short circuit current |
| feederResults | List |
- | no | Empty list | A list of FeederResult, should not be empty if the parameter with-feeder-result is set to true. |
| limitViolations | List |
- | no | Empty list | A list of LimitViolation, should be empty if the parameter with-limit-violations is set to false. |
| shortCircuitBusResults | List |
- | no | Empty list | A list of ShortCircuitBusResult, should be empty if the parameter with-voltage-result is set to false. |
However, in these classes, the short circuit current and voltage are represented differently.
In MagnitudeFaultResult, the additional attributes are:
| Attribute | Type | Unit | Required | Default value | Description |
|---|---|---|---|---|---|
| current | double | kA | yes | - | The three-phased magnitude of the computed short circuit current |
| voltage | double | kV | yes | - | The three-phased magnitude of the computed short circuit voltage |
In FortescueFaultResult, they are:
| Attribute | Type | Unit | Required | Default value | Description |
|---|---|---|---|---|---|
| current | FortescueValue |
kA | yes | - | The magnitude and angle of the computed short circuit current detailed on the three phases |
| voltage | FortescueValue |
kV | yes | - | The magnitude and angle of the computed short circuit voltage detailed on the three phases |
The status of the computation
This status can be:
SUCCESS: the computation went as planned and the results are full considering the parameters.NO_SHORTCIRCUIT_DATA: this status should be returned if no short circuit data are available in the network, i.e. the subtransient or transient reactance of generators and the minimum and maximum admissible short circuit currents.SOLVER_FAILURE: the computation failed because of an error linked to the solver.FAILURE: the computation failed for any other reason.
FeederResults
This field contains the contributions of each feeder to the short circuit current as a list. It should only be returned if with-feeder-result is set to true.
Depending on the value of with-fortescue-result, it should be an instance of com.powsybl.shortcircuit.MagnitudeFeederResult or com.powsybl.shortcircuit.FortescueFeederResult.
The attributes of MagnitudeFeederResults are:
| Attribute | Type | Unit | Required | Default value | Description |
|---|---|---|---|---|---|
| connectableId | String | - | yes | - | ID of the feeder |
| current | double | kA | yes | - | Three-phased current magnitude of the feeder participating to the short circuit current at the fault point |
The attributes of FortescueFeederResuts are:
| Attribute | Type | Unit | Required | Default value | Description |
|---|---|---|---|---|---|
| connectableId | String | - | yes | - | ID of the feeder |
| current | FortescueValue |
kA | yes | - | Current magnitudes and angles on the three phases of the feeder participating to the short circuit current at the fault point |
LimitViolations
This field contains a list of all the violations after the fault. This implies to have defined in the network the maximum or the minimum acceptable short circuit currents on the voltage levels.
Then, with comparing to the computed short circuit current, two types of violations can be created: LOW_SHORT_CIRCUIT_CURRENT and HIGH_SHORT_CIRCUIT_CURRENT.
This list should be empty if the property with-limit-violations is set to false.
ShortCircuitBusResults
This field contains a list of voltage results on every bus of the network after simulating the fault. It should be empty if with-voltage-result is set to false.
The value of the property with-voltage-drop-threshold allows to filter these results by keeping only those where the voltage drop is higher than this defined threshold.
Depending on the value of with-fortescue-result, the list should contain instances of either com.powsybl.shortcircuit.MagnitudeShortCircuitBusResult or com.powsybl.shortcircuit.FortescueShortCircuitBusResult objects.
The attributes of MagnitudeShortCircuitBusResult are:
| Attribute | Type | Unit | Required | Default value | Description |
|---|---|---|---|---|---|
| voltageLevelId | String | - | yes | - | ID of the voltage level containing the bus |
| busId | String | - | yes | - | ID of the bus |
| initialVoltageMagnitude | double | kV | yes | - | Magnitude of the three-phased voltage before the fault |
| voltageDropProportional | double | % | yes | - | Voltage drop after the fault |
| voltage | double | kV | yes | - | Magnitude of the three-phased voltage after the fault |
The attributes of FortescueShortCircuitBusResult are:
| Attribute | Type | Unit | Required | Default value | Description |
|---|---|---|---|---|---|
| voltageLevelId | String | - | yes | - | ID of the voltage level containing the bus |
| busId | String | - | yes | - | ID of the bus |
| initialVoltageMagnitude | double | kV | yes | - | Magnitude of the three-phased voltage before the fault |
| voltageDropProportional | double | % | yes | - | Voltage drop after the fault |
| voltage | FortescueValue |
kV | yes | - | Magnitudes and angles of the voltage on the three phases after the fault |