fix(3ph): report missing zero sequence parameters with a descriptive error

[Houmgaor]

Fixes #3069.

runpp_3ph and the unbalanced short-circuit calculation need zero sequence parameters that runpp does not. Only s_sc_max_mva and rx_max were checked; the remaining ext_grid and line parameters raised a bare KeyError from pd2ppc_zero.

While working on this I found a third variant that #3069 does not list: when the column exists but holds no value. create_cigre_network_mv() + add_zero_impedance_parameters(net) is such a case — the CABLE_CIGRE_MV and OHL_CIGRE_MV standard types carry no zero sequence data, so the columns are created and filled with None. On develop that net fails with TypeError: unsupported operand type(s) for *: 'NoneType' and 'float'.

Changes

_check_zero_sequence_parameters collects all the required ext_grid and line parameters in one place and reports them together, in the message style pandapower already uses for s_sc_max_mva:

Zero sequence parameters are needed for unbalanced calculations:
 net.ext_grid is missing the column(s) ['x0x_max', 'r0x0_max']
 net.line is missing the column(s) ['r0_ohm_per_km', 'x0_ohm_per_km', 'c0_nf_per_km']
 Try:
  net.ext_grid['x0x_max'] = 1.0
  net.ext_grid['r0x0_max'] = 0.1
  net.line['r0_ohm_per_km'] = 0.1
  net.line['x0_ohm_per_km'] = 0.1
  net.line['c0_nf_per_km'] = 0.0
 For lines and transformers that have a standard type, the zero sequence parameters can be
 taken from the standard type library with pandapower.add_zero_impedance_parameters(net).

The example values are the ones add_zero_impedance_parameters applies. Undefined values are reported separately, and only for elements in service, so values that are never read are not required. The check is case aware, so the unbalanced short circuit reports the _min parameters when case="min".

It runs once, before the network is converted, rather than at each call site. Both entry points into the zero sequence network are covered: _pd2ppc(sequence=0) for runpp_3ph and _pd2ppc_zero for the short circuit.

Schema

Following @KS-HTK's pointer in the issue:

• added r0x0_min and x0x_min to ext_grid. They were missing entirely, although the PowerFactory converter writes them and the shipped IEEE European LV networks contain them.
• tagged s_sc_max_mva and rx_max as 3ph, so the generated dependency group is now exactly what runpp_3ph requires: ['s_sc_max_mva', 'rx_max', 'r0x0_max', 'x0x_max']. Previously the group omitted the two parameters that runpp_3ph needs most.

I did not enable the commented out sc and 3ph dependency checks in line_schema. They are commented out on develop and on release/v4.0.0, so it looks deliberate, and enabling them would require g0_us_per_km, which is tagged sc/3ph but is not read by any calculation. Happy to include that if you want it.

Verification

New parametrized test in test_runpp_3ph.py covering each missing parameter group, the undefined value case, and that out of service elements are exempt.

Since this check runs on every unbalanced conversion, I also compared full result tables before and after on real networks:

Network	Size	Result
CIGRE MV with all DER, runpp_3ph	15 bus / 15 line / 2 trafo	identical
IEEE European LV asymmetric, on peak 566	907 bus / 905 line	identical
runpp_3ph Validation.json (PowerFactory reference)	7 bus / 4 line	identical
CIGRE MV 1ph short circuit, case=max and case=min	15 bus each	identical

Worst absolute difference across all tables: 0.0, with identical NaN patterns. The loadflow, shortcircuit, converter, networks, api, opf, estimation and toolbox suites pass. No new ruff findings.

Target branch

Opened against develop as CONTRIBUTING.md asks, and because the bug affects 3.5.x users today. Note that develop and release/v4.0.0 diverged at v3.4.0 and neither is a superset (35 commits on develop are not on release/v4.0.0, 49 the other way), so this will not reach the 4.0 milestone on its own.

The code changes cherry-pick onto release/v4.0.0 cleanly; only three spots conflict, all trivial: the changelog, the cim metadata added to ext_grid.py, and doc/elements/ext_grid_par.csv, which is deleted there since the tables are generated from the schemas by doc/_exts/save_element_tables.py (which means the schema addition documents r0x0_min/x0x_min automatically on 4.0). Just say the word and I will open the companion PR against release/v4.0.0, or retarget this one.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 72.14%. Comparing base (6184290) to head (240d24e).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #3089      +/-   ##
===========================================
+ Coverage    72.12%   72.14%   +0.02%     
===========================================
  Files          355      355              
  Lines        39378    39410      +32     
===========================================
+ Hits         28400    28431      +31     
- Misses       10978    10979       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Houmgaor]

CI note: the two red checks, relying (3.10) and warnings (3.14, 1), fail in exactly the same places on develop — pandapipes test_convert_format[0.1.0-True] and the test_geo.py collection error (see runs 31077902497 and 31089826331). No new failures from this PR, everything else is green.

[KS-HTK]

I understand that github reports develop and v4.0.0 as diverged but the last commits to v4.0.0 are a merge from develop.

[KS-HTK]

Please use google style docstring.

I am aware that pandapower is currently a mix of different doc string styles, but longterm everything should be using the google style docstring, as this has been the best version for rendering in read the docs so far.

[Houmgaor]

I followed the style in the rest of the file, I can change for this function only but that will be inconsistent with the rest of the file.

[KS-HTK]

The file only has one other docstring using this style, please do convert the docstring to google style even if it is inconsistent with the other docstring. These are internal use functions anyway and will never appear in the docs. I would rather have this already in the style that should be applied to all of pandapower than having to convert it later at some point.

[KS-HTK]

There is a function for checking the existance of a column in the table, it will add the table and column if they do not exist (with default value if available). See pandapower.create._utils.add_column_to_df (on branch release/v4.0.0).

[Houmgaor]

pandapower.create._utils.add_column_to_df adds a column rather that raising the error. The former may add default values (x0x_max/s_sc_max_mva) and create false short-circuits, so I'd rather raise for the code. Also, the function is only on v4 if you still want to use it, so the PR would need a rebase if you want the feature there.

[KS-HTK]

Default Values should not be "hidden" in the code. They should be added to the pandera metadata and used from there.

[Houmgaor]

I agree with the idea, but metadata is on v4 only. I can rebase.

[Houmgaor]

Thanks for the reviews @KS-HTK . I opened the PR against develop per guidelines, I can open against v4 if better on your side.

[KS-HTK]

So this is the part where I will leave the decission to you, new features should be done against release/v4.0.0 for now, as we are working on moving develop to that stage. But bugfixes can be added to devlop. If you deem it required for the next minor release and can not accept a delay you may continue with the PR against develop, otherwise I would prefer it if most PRs going forward are against release/v4.0.0 as this will making the switch easier for us in the near future.

It will require a update for release/v4.0.0 at some point, might as well be now if it is not a critical issue.

[sonarqubecloud]

Quality Gate failed

Failed conditions
3.1% Duplication on New Code (required ≤ 3%)
B Reliability Rating on New Code (required ≥ A)
C Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE