feat: add grouped pst example

[BenjPetr]

Signed-off-by: Benjamin Petrick 170433522+BenjPetr@users.noreply.github.com

Checklist

Please check if the PR fulfills these requirements:

• PR Title follows conventional commit messages
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)
• All commits in this PR are DCO signed-off (see CONTRIBUTING.md)

Does this PR already have an issue describing the problem?

grouped PST example

What is the new behavior (if this is a feature change)?

Does this PR introduce a breaking change?

• Yes
• [x ] No

[Copilot]

Pull request overview

This PR introduces support and examples for grouped / parallel PST tap optimization across the importer → DC solver preprocessing → topology optimizer pipeline, including persistence of PST grouping metadata into processed-grid artifacts and ActionSet.

Changes:

• Add import-time detection of parallel linear PST groups (PyPowSyBl path), persist group labels/masks into processed-grid artifacts, and thread them into DC solver StaticInformation + ActionSet.
• Extend optimizer configuration and mutation logic to optionally enforce equal tap updates within configured PST groups, with new integration tests validating N-0 improvement on grouped PST example grids.
• Update docs/READMEs to clarify the “processed grid folder” artifact flow and backend support limitations (grouped PST optimization supported only for PyPowSyBl/PowsyBl-imported artifacts).

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Update repo-level overview to mention grouped PST optimization and processed-grid artifact flow.
packages/topology_optimizer_pkg/tests/test_ac_dc_integration.py	Add integration test validating grouped PST optimizer improves N-0 DC overload and keeps group members equal.
packages/topology_optimizer_pkg/tests/dc/repertoire/test_discrete_map_elites.py	Remove inline grid fixture (moved to shared conftest).
packages/topology_optimizer_pkg/tests/dc/genetic_functions/test_mutate_nodal_inj.py	Add grouped-PST mutation tests and additional nodal injection mutation coverage.
packages/topology_optimizer_pkg/tests/dc/genetic_functions/test_initialization.py	Update initialization tests for new optimizer flag wiring.
packages/topology_optimizer_pkg/tests/conftest.py	Add grouped PST grid fixtures and shared 3-node PST grid fixture.
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/interfaces/messages/dc_params.py	Add enable_parallel_pst_group_optim parameter and validator constraints.
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/dc/genetic_functions/mutation/mutate_nodal_inj.py	Implement grouped PST mutation path using group mask.
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/dc/genetic_functions/mutation/config.py	Add grouped PST optimization metadata to mutation config with validation.
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/dc/genetic_functions/initialization.py	Thread grouped-PST flag into static info verification/update and mutation config creation.
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/dc/genetic_functions/genotype.py	Make deduplication robust to empty PST tap arrays.
packages/topology_optimizer_pkg/README.md	Document PST grouping behavior and backend limitations.
packages/interfaces_pkg/tests/test_stored_action_set.py	Add tests for PSTRange pst_group defaulting + persistence roundtrip.
packages/interfaces_pkg/tests/test_backend.py	Update BackendInterface test stub for new PST grouping methods + typo fix.
packages/interfaces_pkg/src/toop_engine_interfaces/stored_action_set.py	Add pst_group to PSTRange with backward-compatible defaulting.
packages/interfaces_pkg/src/toop_engine_interfaces/messages/preprocess/preprocess_commands.py	Minor formatting tweak.
packages/interfaces_pkg/src/toop_engine_interfaces/folder_structure.py	Rename/add mask filenames for PST linearity and group labels.
packages/interfaces_pkg/src/toop_engine_interfaces/backend.py	Extend BackendInterface with controllable PST ids + parallel PST group mask/id accessors.
packages/interfaces_pkg/README.md	Document Stored Action Set now persisting PST grouping metadata.
packages/importer_pkg/tests/pypowsybl_import/test_powsybl_masks.py	Add tests for PST group labeling and linear PST filtering; update mask naming.
packages/importer_pkg/src/toop_engine_importer/pypowsybl_import/preprocessing.py	Ensure deterministic trafo ordering for stats/N-1 def via id sorting helper.
packages/importer_pkg/src/toop_engine_importer/pypowsybl_import/powsybl_masks.py	Add linear PST detection and parallel PST grouping via step-table comparison; persist pst_group_labels.
packages/importer_pkg/src/toop_engine_importer/pypowsybl_import/loadflow_based_current_limits.py	Sort transformer frame by id for deterministic behavior.
packages/importer_pkg/README.md	Clarify processed-grid artifact flow and grouped PST support constraints.
packages/grid_helpers_pkg/tests/powsybl/test_powsybl_example_grids.py	Add test for grouped PST example grid convergence across linear/nonlinear variants.
packages/grid_helpers_pkg/src/toop_engine_grid_helpers/powsybl/powsybl_helpers.py	Add helper to sort PowSyBl element frames by id.
packages/grid_helpers_pkg/src/toop_engine_grid_helpers/powsybl/powsybl_asset_topo.py	Exclude BUSBAR_SECTION injections in bus-breaker station builder.
packages/grid_helpers_pkg/src/toop_engine_grid_helpers/powsybl/example_grids.py	Add grouped PST example grid generator and minor dtype normalization fixes.
packages/dc_solver_pkg/tests/test_example_grids.py	Add tests ensuring grouped/parallel PST masks propagate into network_data and static_information.
packages/dc_solver_pkg/tests/preprocessing/test_write_aux_data.py	Add test persisting PST groups into ActionSet and verifying clipped ranges.
packages/dc_solver_pkg/tests/preprocessing/test_preprocess.py	Add tests for nonlinear PST exclusion behavior w.r.t. grouping; add log capture.
packages/dc_solver_pkg/tests/preprocessing/test_powsybl_helpers.py	Update PST mask column names; add linear/nonlinear detection tests for grouped PST grid.
packages/dc_solver_pkg/tests/preprocessing/test_powsybl_backend.py	Use xiidm-backed fixture; add backend tests for parallel PST grouping metadata.
packages/dc_solver_pkg/tests/preprocessing/test_parallel_pst_groups.py	Add unit tests for building 2D PST group mask + labels from per-PST labels.
packages/dc_solver_pkg/tests/preprocessing/test_convert_to_jax.py	Extend load/save validation path in convert-to-jax flow.
packages/dc_solver_pkg/tests/postprocessing/test_postprocess_powsybl.py	Include grouped PST example in PST-change postprocessing tests.
packages/dc_solver_pkg/tests/jax/test_nodal_inj_optim.py	Add nodal injection optimization test for parallel PST groups.
packages/dc_solver_pkg/tests/conftest.py	Add fixtures for parallel PST and grouped PST processed-grid folders; add xiidm-backed case57 fixture.
packages/dc_solver_pkg/src/toop_engine_dc_solver/preprocess/preprocess.py	Carry parallel PST group metadata through branch-dimension reduction and nonlinear PST exclusion.
packages/dc_solver_pkg/src/toop_engine_dc_solver/preprocess/powsybl/powsybl_helpers.py	Rename PST controllability column to pst_linear and add pst_group to BranchModel schema.
packages/dc_solver_pkg/src/toop_engine_dc_solver/preprocess/powsybl/powsybl_backend.py	Load PST linearity + group labels masks; expose group mask/ids via backend.
packages/dc_solver_pkg/src/toop_engine_dc_solver/preprocess/parallel_pst_groups.py	Add helper to build boolean group mask + ids from integer labels.
packages/dc_solver_pkg/src/toop_engine_dc_solver/preprocess/pandapower/pandapower_backend.py	Implement grouping methods as unsupported (None) and update mask filename usage.
packages/dc_solver_pkg/src/toop_engine_dc_solver/preprocess/network_data.py	Add parallel PST group metadata to NetworkData and persist group ids into ActionSet PST ranges.
packages/dc_solver_pkg/src/toop_engine_dc_solver/preprocess/convert_to_jax.py	Thread PST group mask into NodalInjectionInformation.
packages/dc_solver_pkg/src/toop_engine_dc_solver/jax/types.py	Add parallel_pst_group_mask to nodal injection info and enable_parallel_pst_group_optim to solver config.
packages/dc_solver_pkg/src/toop_engine_dc_solver/jax/nodal_inj_optim.py	Remove unused solver_config parameter.
packages/dc_solver_pkg/src/toop_engine_dc_solver/jax/inputs.py	Persist/load grouped-PST config and masks in static_information.hdf5 with compatibility fallback.
packages/dc_solver_pkg/src/toop_engine_dc_solver/jax/compute_batch.py	Update nodal injection optimization call signature after removing solver_config arg.
packages/dc_solver_pkg/src/toop_engine_dc_solver/example_grids.py	Add grouped PST processed-grid generator and update mask naming for PST linearity/groups.
packages/dc_solver_pkg/README.md	Document processed-grid artifact flow and grouped PST support constraints.
packages/contingency_analysis_pkg/README.md	Clarify contingency definition lifecycle across convert_file and load_grid.
docs/usage.md	Update workflow doc to emphasize processed-grid folder + artifact creation steps.
docs/quickstart.md	Mention processed-grid workflow and artifacts produced by load_grid.
docs/index.md	Update docs landing page for grouped PST support and refined roadmap.
docs/importer/worker/worker.md	Expand importer worker documentation to list artifacts and PST grouping support.
docs/importer/pypowsybl/index.md	Document PyPowSyBl path as the supported path for parallel PST grouping identification.
docs/importer/pandapower/index.md	Document PandaPower path as unsupported for grouped PST optimization.
docs/importer/network_graph/index.md	Clarify limitation scope around PST mapping vs PST grouping identification.
docs/dc_solver/quickstart.md	Clarify processed-grid prerequisites and grouped PST support limits.
docs/dc_solver/preprocessing.md	Expand preprocessing artifact table and document grouped PST behavior and constraints.
.pre-commit-hooks/sensitive-files-whitelist.txt	Whitelist data/case57_xiidm/grid.xiidm.

[sonarqube-mccs]

Quality Gate passed

Issues
0 New issues
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
97.5% Coverage on New Code
8.4% Duplication on New Code

See analysis details on SonarQube