Skip to main content

​
Overview

The Load Flow module provides functions to run AC and DC power flow calculations on power networks. Load flow analysis computes the steady-state voltages, currents, and power flows in the network.

​
Running Load Flow

​
run_ac

Run an AC load flow on a network. 
pp.loadflow.run_ac(
    network: Network,
    parameters: Parameters = None,
    provider: str = '',
    report_node: ReportNode = None
) -> List[ComponentResult]
​
network
Network
required
The network on which to run the load flow
​
parameters
Parameters
Load flow parameters to customize the calculation
​
provider
str
default:""
The load flow implementation provider. If empty, uses the default provider
​
report_node
ReportNode
Reporter to create an execution report
​
return
List[ComponentResult]
A list of component results, one for each component of the network
Example: 
import pypowsybl as pp

network = pp.network.create_ieee14()
results = pp.loadflow.run_ac(network)

for result in results:
    print(f"Component {result.component_num}: {result.status}")
    print(f"  Iterations: {result.iteration_count}")
    print(f"  Slack bus active power: {result.slack_bus_active_power_mismatch}")

​
run_dc

Run a DC load flow on a network. 
pp.loadflow.run_dc(
    network: Network,
    parameters: Parameters = None,
    provider: str = '',
    report_node: ReportNode = None
) -> List[ComponentResult]
Parameters are identical to run_ac. DC load flow is a simplified calculation that assumes:
  • All voltages are at nominal values
  • Only active power flows are calculated
  • Line resistances and reactive power are ignored
Example: 
import pypowsybl as pp

network = pp.network.create_ieee14()
results = pp.loadflow.run_dc(network)

​
run_ac_async

Run an AC load flow asynchronously. 
pp.loadflow.run_ac_async(
    network: Network,
    variant_id: str = 'InitialState',
    parameters: Parameters = None,
    provider: str = '',
    report_node: ReportNode = None
) -> Future
​
network
Network
required
The network on which to run the load flow
​
variant_id
str
default:"InitialState"
The variant ID to use for the calculation
​
parameters
Parameters
Load flow parameters
​
provider
str
default:""
The load flow implementation provider
​
report_node
ReportNode
Reporter for execution reports
​
return
Future
A future that will contain the list of component results

​
Parameters

​
Parameters Class

The Parameters class configures load flow calculations. 
pp.loadflow.Parameters(
    voltage_init_mode: VoltageInitMode = None,
    transformer_voltage_control_on: bool = None,
    use_reactive_limits: bool = None,
    phase_shifter_regulation_on: bool = None,
    twt_split_shunt_admittance: bool = None,
    shunt_compensator_voltage_control_on: bool = None,
    read_slack_bus: bool = None,
    write_slack_bus: bool = None,
    distributed_slack: bool = None,
    balance_type: BalanceType = None,
    dc_use_transformer_ratio: bool = None,
    countries_to_balance: list = None,
    component_mode: ComponentMode = None,
    dc_power_factor: float = None,
    hvdc_ac_emulation: bool = None,
    provider_parameters: dict = None
)
​
voltage_init_mode
VoltageInitMode
Resolution starting point:
  • UNIFORM_VALUES: Flat start (all voltages at 1.0 pu)
  • DC_VALUES: Use DC load flow results as starting point
​
transformer_voltage_control_on
bool
Enable transformer voltage control simulation. The initial tap position is used as the starting point
​
use_reactive_limits
bool
Whether to enforce reactive power limits on generators
​
phase_shifter_regulation_on
bool
Enable phase shifter regulation simulation
​
shunt_compensator_voltage_control_on
bool
Enable voltage control of shunt compensators
​
distributed_slack
bool
Distribute active power slack across the network. When True, active power mismatch is distributed according to balance_type
​
balance_type
BalanceType
How to distribute active power slack:
  • PROPORTIONAL_TO_LOAD: Distribute on loads
  • PROPORTIONAL_TO_GENERATION_P_MAX: Distribute on generators proportional to Pmax
  • PROPORTIONAL_TO_GENERATION_P: Distribute on generators proportional to current P
​
component_mode
ComponentMode
Which network components to compute:
  • MAIN_SYNCHRONOUS: Only main synchronous component
  • MAIN_CONNECTED: Only main connected component
  • ALL_CONNECTED: All connected components
​
dc_use_transformer_ratio
bool
In DC mode, whether to include transformer ratios in the calculation
​
dc_power_factor
float
Power factor used to convert current limits to active power limits in DC calculations
​
hvdc_ac_emulation
bool
Enable AC emulation of HVDC links
​
provider_parameters
dict
Provider-specific parameters as key-value pairs
Example: 
import pypowsybl as pp
from pypowsybl.loadflow import VoltageInitMode, BalanceType

parameters = pp.loadflow.Parameters(
    voltage_init_mode=VoltageInitMode.DC_VALUES,
    transformer_voltage_control_on=True,
    use_reactive_limits=True,
    distributed_slack=True,
    balance_type=BalanceType.PROPORTIONAL_TO_GENERATION_P_MAX
)

network = pp.network.create_ieee14()
results = pp.loadflow.run_ac(network, parameters=parameters)

​
Results

​
ComponentResult

Represents the result of a load flow calculation for one network component.
​
component_num
int
The component number
​
status
ComponentStatus
The status of the calculation:
  • CONVERGED: Calculation converged successfully
  • MAX_ITERATION_REACHED: Maximum iterations reached
  • FAILED: Calculation failed
​
iteration_count
int
Number of iterations performed
​
slack_bus_active_power_mismatch
float
Active power mismatch at the slack bus (in MW)
​
slack_bus_id
str
ID of the slack bus

​
SlackBusResult

Detailed information about the slack bus.
​
id
str
ID of the slack bus
​
active_power_mismatch
float
Active power mismatch (in MW)

​
Validation

​
run_validation

Validate that network data is consistent with AC load flow equations. 
pp.loadflow.run_validation(
    network: Network,
    validation_types: List[ValidationType] = None,
    validation_parameters: ValidationParameters = None
) -> ValidationResult
​
network
Network
required
The network to validate
​
validation_types
List[ValidationType]
Types of data to check. If None, all types are checked:
  • BUSES: Bus voltage and phase validation
  • FLOWS: Branch flow validation
  • GENERATORS: Generator validation
  • SVCS: Static VAR compensator validation
  • SHUNTS: Shunt compensator validation
  • TWTS: Two-winding transformer validation
  • TWTS3W: Three-winding transformer validation
​
validation_parameters
ValidationParameters
Parameters for the validation
​
return
ValidationResult
Validation result containing DataFrames for each validation type

​
Provider Management

​
get_provider_names

Get the list of available load flow providers. 
pp.loadflow.get_provider_names() -> List[str]
​
return
List[str]
List of available provider names

​
get_default_provider

Get the current default load flow provider. 
pp.loadflow.get_default_provider() -> str
​
return
str
Name of the default provider (typically ‘OpenLoadFlow’)

​
set_default_provider

Set the default load flow provider. 
pp.loadflow.set_default_provider(provider: str)
​
provider
str
required
Name of the provider to set as default

​
get_provider_parameters

Get provider-specific parameters. 
pp.loadflow.get_provider_parameters(provider: str = None) -> DataFrame
​
provider
str
Provider name. If None, uses the default provider
​
return
DataFrame
DataFrame with columns: category_key, description, type, default, possible_values
Example: 
import pypowsybl as pp

# Get OpenLoadFlow parameters
params = pp.loadflow.get_provider_parameters('OpenLoadFlow')
print(params['description']['slackBusSelectionMode'])
print(params['default']['slackBusSelectionMode'])

​
Enumerations

​
VoltageInitMode

  • UNIFORM_VALUES: Flat start (all voltages at 1.0 pu)
  • DC_VALUES: Use DC load flow as starting point

​
BalanceType

  • PROPORTIONAL_TO_LOAD: Distribute slack on loads
  • PROPORTIONAL_TO_GENERATION_P_MAX: Distribute on generators by Pmax
  • PROPORTIONAL_TO_GENERATION_P: Distribute on generators by current P

​
ComponentMode

  • MAIN_SYNCHRONOUS: Main synchronous component only
  • MAIN_CONNECTED: Main connected component only
  • ALL_CONNECTED: All connected components

​
ComponentStatus

  • CONVERGED: Calculation converged
  • MAX_ITERATION_REACHED: Maximum iterations reached
  • FAILED: Calculation failed

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us