Skip to main content

​
Overview

The Short Circuit module performs short-circuit analysis to compute fault currents and voltages when faults occur in the network. It supports bus faults and branch faults with configurable fault impedances.

​
Creating Short Circuit Analysis

​
create_analysis

Create a short-circuit analysis instance. 
pp.shortcircuit.create_analysis() -> ShortCircuitAnalysis
​
return
ShortCircuitAnalysis
A new short-circuit analysis instance
Example: 
import pypowsybl as pp

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

​
ShortCircuitAnalysis Class

The ShortCircuitAnalysis class allows you to configure and run short-circuit analysis on a network.

​
Defining Faults

​
set_faults

Define faults to be analyzed in the short-circuit simulation. 
analysis.set_faults(
    df: DataFrame = None,
    **kwargs
)
​
df
DataFrame
Faults defined as a DataFrame with columns: id, element_id, r, x, proportional_location, fault_type
​
kwargs
keyword arguments
Alternatively, define faults as keyword arguments. All arrays must have the same length:
  • id: Fault identifier
  • element_id: ID of the bus or branch on which the fault occurs
  • r: Fault resistance to ground in Ohm (optional)
  • x: Fault reactance to ground in Ohm (optional)
  • proportional_location: Location of fault on branch as percentage (0.0-1.0, for branch faults only)
  • fault_type: Either ‘BUS_FAULT’ or ‘BRANCH_FAULT’
Example: 
import pypowsybl as pp
import pandas as pd

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

# Define single fault as keyword arguments
analysis.set_faults(
    id='FAULT_1',
    element_id='VL1_0',
    r=0.0,
    x=0.0,
    fault_type='BUS_FAULT'
)

# Define multiple faults as keyword arguments
analysis.set_faults(
    id=['FAULT_1', 'FAULT_2'],
    element_id=['VL1_0', 'VL2_0'],
    r=[0.0, 0.1],
    x=[0.0, 0.2],
    fault_type=['BUS_FAULT', 'BUS_FAULT']
)

# Define faults as DataFrame
faults_df = pd.DataFrame({
    'id': ['FAULT_1', 'FAULT_2'],
    'element_id': ['VL1_0', 'VL2_0'],
    'r': [0.0, 0.0],
    'x': [0.0, 0.0],
    'fault_type': ['BUS_FAULT', 'BUS_FAULT']
})
analysis.set_faults(df=faults_df)

​
set_bus_fault

Convenience method to define a bus fault. 
analysis.set_bus_fault(
    bus_id: str,
    element_id: str,
    r: float,
    x: float
)
​
bus_id
str
required
Fault identifier
​
element_id
str
required
ID of the bus on which the fault occurs
​
r
float
required
Fault resistance to ground in Ohm
​
x
float
required
Fault reactance to ground in Ohm

​
set_branch_fault

Convenience method to define a branch fault. 
analysis.set_branch_fault(
    branch_id: str,
    element_id: str,
    r: float,
    x: float,
    proportional_location: float
)
​
branch_id
str
required
Fault identifier
​
element_id
str
required
ID of the branch (line or transformer) on which the fault occurs
​
r
float
required
Fault resistance to ground in Ohm
​
x
float
required
Fault reactance to ground in Ohm
​
proportional_location
float
required
Location of the fault on the branch as a percentage (0.0 = side 1, 1.0 = side 2)
Example: 
# Bus fault at bus VL1_0 with zero impedance
analysis.set_bus_fault(
    bus_id='FAULT_BUS_1',
    element_id='VL1_0',
    r=0.0,
    x=0.0
)

# Branch fault at 50% along line L1-2-1
analysis.set_branch_fault(
    branch_id='FAULT_LINE_1',
    element_id='L1-2-1',
    r=0.1,
    x=0.2,
    proportional_location=0.5
)

​
Running Analysis

​
run

Run the short-circuit analysis. 
analysis.run(
    network: Network,
    parameters: Parameters = None,
    provider: str = '',
    report_node: ReportNode = None
) -> ShortCircuitAnalysisResult
​
network
Network
required
Network on which to run the short-circuit analysis
​
parameters
Parameters
Short-circuit analysis parameters
​
provider
str
default:""
Short-circuit analysis implementation provider. If empty, uses default
​
report_node
ReportNode
Reporter for execution reports
​
return
ShortCircuitAnalysisResult
Short-circuit analysis result containing fault currents and voltages
Example: 
import pypowsybl as pp

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

# Define fault
buses = network.get_buses()
analysis.set_bus_fault(
    bus_id='FAULT_1',
    element_id=buses.index[0],
    r=0.0,
    x=0.0
)

# Run analysis
result = analysis.run(network)

# Access results
fault_results = result.fault_results
print(fault_results[['fault_id', 'current', 'voltage_magnitude']])

​
Parameters

​
Parameters Class

Configure short-circuit analysis execution. 
pp.shortcircuit.Parameters(
    with_feeder_result: bool = None,
    with_limit_violations: bool = None,
    with_voltage_result: bool = None,
    min_voltage_drop_proportional_threshold: float = None,
    study_type: ShortCircuitStudyType = None,
    with_fortescue_result: bool = None,
    initial_voltage_profile_mode: InitialVoltageProfileMode = None,
    provider_parameters: dict = None
)
​
with_feeder_result
bool
default:"False"
Whether to calculate the contributions of each feeder to the short-circuit current at the fault node
​
with_limit_violations
bool
default:"False"
Whether to return limit violations. When True, returns buses where the short-circuit current exceeds limits
​
with_voltage_result
bool
default:"False"
Whether to calculate the voltage profile on every node of the network
​
min_voltage_drop_proportional_threshold
float
default:"0.0"
Threshold for filtering voltage results. Only nodes with voltage drop greater than this threshold are retained
​
study_type
ShortCircuitStudyType
default:"TRANSIENT"
Type of short-circuit study:
  • SUB_TRANSIENT: Sub-transient period
  • TRANSIENT: Transient period
  • STEADY_STATE: Steady-state
​
with_fortescue_result
bool
default:"False"
Whether currents and voltages should be detailed with magnitude and angle on each phase (symmetrical components)
​
initial_voltage_profile_mode
InitialVoltageProfileMode
default:"NOMINAL"
How the computation is initialized:
  • NOMINAL: Use nominal voltages
  • CONFIGURED: Use configured voltage profile
  • PREVIOUS_VALUE: Use previous calculated values
​
provider_parameters
dict
Provider-specific parameters as key-value pairs
Example: 
import pypowsybl as pp
from pypowsybl.shortcircuit import ShortCircuitStudyType

parameters = pp.shortcircuit.Parameters(
    with_feeder_result=True,
    with_voltage_result=True,
    with_limit_violations=True,
    study_type=ShortCircuitStudyType.SUB_TRANSIENT,
    min_voltage_drop_proportional_threshold=0.05
)

result = analysis.run(network, parameters=parameters)

​
Results

​
ShortCircuitAnalysisResult

Contains the results of a short-circuit analysis.
​
fault_results
DataFrame
DataFrame with short-circuit results for each fault. Columns include:
  • fault_id: Fault identifier
  • current: Short-circuit current magnitude (in A)
  • voltage_magnitude: Voltage magnitude at fault location (in kV)
  • short_circuit_power: Short-circuit power (in MVA) And more depending on parameters…
​
feeder_results
DataFrame
DataFrame with contributions from each feeder (if with_feeder_result=True). Columns include:
  • fault_id: Fault identifier
  • connector_id: ID of the connecting element
  • current: Current contribution magnitude (in A)
​
limit_violations
DataFrame
DataFrame with limit violations (if with_limit_violations=True)
​
voltage_results
DataFrame
DataFrame with voltage profile (if with_voltage_result=True)
​
fortescue_results
DataFrame
DataFrame with three-phase results (if with_fortescue_result=True)
Example: 
result = analysis.run(network, parameters=parameters)

# Access fault results
fault_results = result.fault_results
print("Fault Results:")
print(fault_results[['fault_id', 'current', 'voltage_magnitude']])

# Access feeder contributions (if requested)
if result.feeder_results is not None:
    feeder_results = result.feeder_results
    print("\nFeeder Contributions:")
    print(feeder_results[['fault_id', 'connector_id', 'current']])

# Access voltage results (if requested)
if result.voltage_results is not None:
    voltage_results = result.voltage_results
    print("\nVoltage Profile:")
    print(voltage_results.head())

​
Provider Management

​
get_provider_names

Get the list of available short-circuit analysis providers. 
pp.shortcircuit.get_provider_names() -> List[str]
​
return
List[str]
List of available provider names

​
get_default_provider

Get the current default short-circuit analysis provider. 
pp.shortcircuit.get_default_provider() -> str
​
return
str
Name of the default provider

​
set_default_provider

Set the default short-circuit analysis provider. 
pp.shortcircuit.set_default_provider(provider: str)
​
provider
str
required
Name of the provider to set as default

​
get_provider_parameters_names

Get the list of provider-specific parameter names. 
pp.shortcircuit.get_provider_parameters_names(provider: str = None) -> List[str]
​
provider
str
Provider name. If None, uses default provider
​
return
List[str]
List of parameter names

​
Enumerations

​
ShortCircuitStudyType

Type of short-circuit study:
  • SUB_TRANSIENT: Sub-transient period (first few cycles after fault)
  • TRANSIENT: Transient period
  • STEADY_STATE: Steady-state short-circuit conditions

​
InitialVoltageProfileMode

How the voltage profile is initialized:
  • NOMINAL: Use nominal voltages for all buses
  • CONFIGURED: Use configured voltage profile from extensions
  • PREVIOUS_VALUE: Use previously calculated voltage values (e.g., from load flow)

​
Notes

The current implementation supports three-phase bus faults where the fault resistance and reactance, when specified, are connected to ground in series.
For accurate results, ensure that the network includes the necessary short-circuit data such as generator transient/sub-transient reactances. These may need to be configured via network extensions.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us