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 source:

Cause: No utility feed or generator is connected
Solution: Connect a utility feed or generator to the network

Islanded network:

Error: "Isolated components detected"
Cause: Components not connected to a utility feed or generator
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: Review pre-analysis validation

Start power flow. EKX checks the network before it runs the calculation.
Review the issues in the validation dialog.
Fix blocking issues, such as a missing source or disconnected network.
Review any warnings before proceeding.

Step 2: Check the source

Verify at least one utility feed or generator exists.
For a generator: ensure it is connected to a bus and its rated voltage is entered.

Step 3: Verify network connectivity

Trace the power path from the source 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

Select each component and verify its required properties in the edit panel.
Look for blank 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).

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 the source can supply the 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 source providing the voltage reference
Add a utility feed or a generator
Check the source 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%)

Cable too small for its load:

Message: "Cable CBL cannot deliver the 222 kVA connected beyond it at 480 V"
Cause: the conductor's resistance over its length drops the voltage so far that no solution exists. A cable added through the API keeps the smallest conductor in its series until sizing runs.
Solution: choose a larger conductor or more parallel runs, or apply sizing

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

Tolerances (not adjustable):

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

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

Use the feedback button (bug icon, bottom right of the editor) to send a report. It attaches the current page's diagnostics and, when available, a project export.

Include in the report:

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.

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:

Review the pre-analysis validation dialog before proceeding
Verify a utility feed or generator is connected
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
Pre-analysis validation - Issues shown before a study runs
Debug panel - Data inspection