Troubleshooting convergence failures

Power flow calculations can fail to converge when network topology or component data prevents the iterative solver from finding a solution.

Understanding convergence

What convergence means:

Iterative power flow solver reaches stable solution
Voltage and power values stop changing between iterations
All buses have valid voltage magnitudes and angles
Power balance achieved throughout network

Newton-Raphson method:

Iterative algorithm used by PandaPower
Starts with voltage initialization (flat start: 1.0 pu all buses)
Updates voltages based on power mismatches
Repeats until mismatches below tolerance
Typically converges in 3-6 iterations

Convergence criteria:

Voltage change <1e-6 pu between iterations
Power mismatch <1e-6 MW/MVAR
Maximum 100 iterations
Failure if criteria not met

Common convergence failures

No slack bus:

Error: "No reference bus defined"
Cause: No component designated as slack bus
Solution: Ensure utility feed or generator exists and is slack bus

Islanded network:

Error: "Isolated components detected"
Cause: Components not connected to slack bus
Solution: Create connections to main network or add second source

Extreme voltage levels:

Error: "Voltage initialization failed" or "Voltage out of range"
Cause: Mismatched voltage ratings between connected components
Solution: Check transformer primary/secondary voltages match connected buses

Negative or zero loads:

Error: "Invalid load values"
Cause: Load active or reactive power set to negative or zero inappropriately
Solution: Verify load values are positive for consumption

Missing component data:

Error: "Required parameter missing"
Cause: Component missing voltage, power, or impedance data
Solution: Complete all required fields before running calculation

Debugging convergence issues

Step 1: Run validation

Click Validate Network before calculation.
Review validation warnings and errors.
Fix blocking issues (missing source, orphaned components).
Address warnings (voltage mismatches, incomplete data).

Step 2: Check slack bus

Verify at least one utility feed or generator exists.
For utility feed: confirm is_slack_bus property true.
For generator: ensure connected to bus and rated voltage specified.
Only one slack bus per connected network.

Step 3: Verify network connectivity

Trace power path from slack bus to all loads.
Check for orphaned components (no path to source).
Verify all transformers have both primary and secondary connected.
Ensure no broken connections.

Step 4: Inspect component data

Open debug panel (Cmd/Ctrl+Shift+D).
Select each component and verify required properties.
Look for null values in voltage, power, or impedance fields.
Check for unreasonable values (e.g., 999999 kV).

Step 5: Review voltage levels

Check all buses have realistic voltage ratings.
Verify transformers connect compatible voltage levels.
Ensure no direct connection between incompatible voltages.
Typical levels: 0.48, 4.16, 13.8 kV (not 4.8 or 14 kV).

Step 6: Export debug data

Click Export Power Flow Debug in debug panel.
Review debug-exports/pf-debug-[timestamp].md.
Check "Request Parameters" section for input data.
Look for error messages in "Results" section.

Specific error solutions

"Newton-Raphson did not converge":

Network too complex or ill-conditioned
Try reducing load levels temporarily
Check for very high or very low impedances
Verify transformer impedance percentages reasonable (3-8%)

"Voltage magnitude diverging":

Voltage growing unbounded or collapsing
Often caused by incorrect transformer tap settings
Check load power factors (must be 0.5-1.0 range)
Verify reactive power compensation not excessive

"Power mismatch too large":

Generation doesn't match load + losses
Check load active power values
Verify generator ratings
Confirm slack bus can supply required power

"Singular jacobian matrix":

Mathematical issue in network structure
Often from duplicate buses at same location
Check for zero impedance branches
Verify no parallel components with identical parameters

"No external grid":

No slack bus providing voltage reference
Add utility feed component
Or designate generator as slack bus
Check slack bus is actually connected

Network topology issues

Radial vs meshed networks:

Radial (tree structure): Always converges if data correct
Meshed (loops): May require more iterations
Multiple sources: Ensure compatible voltage and phase angle

Transformer connections:

Both primary and secondary must connect
Check vector group matches system configuration
Verify tap position reasonable (-10% to +10%)

Long cables:

Very long cables (>10km) may cause voltage drop issues
Break into segments if needed
Check cable impedance parameters reasonable

Parallel components:

Parallel cables: Ensure impedances identical or use single equivalent
Parallel transformers: Match impedances and tap settings

Load modeling issues

Constant power loads:

Most loads modeled as constant P and Q
Can cause convergence issues at low voltage
Try reducing load if convergence fails

Motor loads:

High reactive power draw affects convergence
Check power factor realistic (0.8-0.95)
Verify motor rated voltage matches bus

Unbalanced loads:

Single-phase loads on three-phase system
ekx uses balanced (positive sequence) analysis
Cannot model detailed unbalance

Voltage initialization

Flat start (default):

All buses initialized to 1.0 pu voltage
Most common method
Works for most networks

If flat start fails:

Network may need better initial guess
Currently no alternative initialization in ekx
Simplify network or fix data issues

Convergence with large networks

Network size limits:

PandaPower handles 1000+ buses
Convergence time increases with size
More iterations needed for complex networks

Improving large network convergence:

Reduce network to essential components
Remove components far from area of interest
Use equivalent impedances for distant networks
Break into smaller subsystems if possible

Tolerance settings

Default tolerances (not adjustable in current version):

Voltage: 1e-6 pu
Power: 1e-6 MW/MVAR
Max iterations: 100

Future: Adjustable settings planned for:

Looser tolerances for difficult networks
More iterations for complex systems
Alternative solver algorithms

When to contact support

Contact support if:

Network validates correctly but won't converge
Same network converged before but fails now
Error message unclear or unhelpful
Convergence fails with minimal network

Include in support request:

Power flow debug export file
Description of network (# buses, # components)
What changed before failure (if previously worked)
Full error message text

Workarounds for difficult networks

Simplify temporarily:

Remove non-critical loads.
Replace complex sections with equivalent impedances.
Use single large load instead of many small loads.
Run simplified network to verify basic connectivity.
Add complexity back gradually.

Adjust component values:

Start with lower load values (50% of actual).
Gradually increase load to full value.
Check convergence at each step.
Identifies which component causes issue.

Check alternative source:

If utility feed as slack, try generator.
Or vice versa.
May indicate source data issue.

Prevention best practices

During network building:

Complete component data before connecting
Validate frequently (after each major change)
Use realistic voltage levels
Follow standard connection patterns

Before running calculation:

Run validation warnings check
Verify slack bus exists
Check all loads have power values
Confirm transformer voltages match

Good modeling practices:

Use standard voltage levels (not arbitrary values)
Keep transformer impedances 3-8% range
Set realistic power factors (0.8-0.95)
Avoid extremely long cables (>50km)

Understanding power flow - How power flow works
Running power flow - Execution steps
Validation warnings - Pre-calculation checks
Debug panel - Data inspection