Add tap regulator control side topology validation to Python validator

[Copilot]

Tap regulator control side errors (controlling from non-source side towards source) are currently only caught during C++ power flow calculation. This adds Python-side validation to detect these configuration errors before model construction.

Changes

New validation error: InvalidTapRegulatorControlSideError

• Raised when transformer controlled from side farther from sources

Topology validation: validate_tap_regulator_control_side_topology()

• Builds directed graph: regulated transformer edges point from non-control → control side
• Runs Dijkstra from sources to compute node distances
• Flags transformers where non-control side unreachable (∞) but control side reachable (finite)
• Handles 2-winding and 3-winding transformers

Integration: Called from validate_transformer_tap_regulator()

Example

from power_grid_model.validation import validate_input_data

input_data = {
    ComponentType.node: [...],
    ComponentType.source: [...],  # source at node 0
    ComponentType.transformer: [...],  # from node 0 to node 1
    ComponentType.transformer_tap_regulator: [
        # Invalid: controlling from from_side towards source
        {"id": 4, "regulated_object": 3, "control_side": BranchSide.from_side}
    ]
}

errors = validate_input_data(input_data)
# Returns: InvalidTapRegulatorControlSideError with transformer ID 4

Previously this error only surfaced during calculate_power_flow() with cryptic C++ exception. Now caught during input validation with clear transformer IDs.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[FEATURE] Add tap regulator control side validation to data validator</issue_title>
<issue_description>## Summary

Add validation to the Python data validator to detect invalid tap regulator control side configuration
before running power flow calculations. This validation should catch cases where a transformer is being
controlled from the non-source side towards the source side, which is currently only detected during
runtime calculation.

Related Issues and PRs

• Origin: Issue [FEATURE] Power flow calculation. Case of incorrectly specified transformer tap_regulator control_side #1263 - Power flow calculation. Case of incorrectly specified transformer
  tap_regulator control_side
• Short-term solution: PR Extend regulated transformer control side error #1273 - Extend regulated transformer control side error, PR Report unique ID in trafrmer regulate side error message #1279 - Report unique ID in transformer regulate side error message
• Current status: Runtime error messages now include transformer IDs, but this information is only made available as error message during calculation.

Problem Statement

Current Behavior

Currently, when a tap regulator has an invalid control side configuration (controlling from non-source
side towards source side), the error is only detected during power flow calculation in the C++ core:

AutomaticTapInputError: Automatic tap changer has invalid configuration. 
The transformer is being controlled from non source side towards source side.
Transformer IDs: [123, 456, 789]

Why This Is a Problem

1. Late error detection: Errors are only discovered after the model is constructed and calculation
   begins, wasting computation time

2. Poor development experience: Developers must wait for calculation to start before discovering
   data issues

3. Incomplete validation workflow: The Python data validator doesn't catch this error, creating a
   gap in pre-calculation validation

4. Inconsistent with best practices: The documentation recommends validating data before
   construction, but this specific check is missing

User Impact

For users with large models (e.g., 50+ transformers with tap regulators):

• Cannot validate all input data (wrt this regulated side) before construction
• Must rely on trial-and-error with calculations to find configuration issues
• Difficult to integrate into automated data validation pipelines

Proposed Solution

Add a new validation check in the Python data validator
(src/power_grid_model/validation/_validation.py) to detect invalid tap regulator control side
configurations.

Validation Logic

The validation should check for each transformer_tap_regulator in topology:

1. Identify the regulated transformer (using regulated_object field)

2. Determine the trafo-topology:

   • Simplified trafo graph: build with shortest distance in mind

3. Validate control side:

   • The control_side must point to a side that is closer to or at the source
   • If controlling from a side that is farther from the source, append trafo user side ID
   • raise a validation error containing these trafo user side IDs

Backward Compatibility

• New validation should be additive only
• Existing validation should continue to work
• Consider adding a warning first, then making it an error in a future release

</issue_description>

<agent_instructions>This issue will require a new topo graph building with reference to the c++ side transformer graph in tap_position_optimizer. Make sure to understand that front first. Create a branch for this: copilot-playground/add-transformer-regulated-side-check-in-python-validator</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@Jerry-Jinfeng-Guo I will experiment with Copilot in the issue to see if she's up to the task.

• Fixes [FEATURE] Add tap regulator control side validation to data validator #1292

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud