PFSolver: SVC voltage-control outer loop

[leonardocarreras]

Adds the solver-side outer loop that holds each SVC bus at its voltage setpoint. Opt in via set_pf_solver_enforce_svc_control.

Builds on the pull request below it in the stack, which adds the SP domain SVC component itself.

[github-actions]

DPsim LLM review

Claim vs. code: matches the description.

Found 14 high, 31 medium, 2 low (0 anchored to lines below).

🔵 Optional / low-confidence (47)

• Incorrect sensitivity sign in SVC voltage-control loop [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:691
• Replace hard-coded epsilon with DOUBLE_EPSILON [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:668
• Replace hard-coded sensitivity threshold with DOUBLE_EPSILON [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:669
• Use DOUBLE_EPSILON for near-zero check on dV [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:696
• Mark PFSolver::SolveTask as external to prevent scheduler dropping [high · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolver.h:244
• Use of B(idx,idx) in hot path without bounds check [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:691
• Potential iterator invalidation in mSvcPrevQV during outer loop [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:712
• Missing override specifier on enforceSvcVoltageControl [high · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolverPowerPolar.h:80
• Missing override specifier on clearReactiveLimitState [high · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolverPowerPolar.h:82
• Expose new Simulation SVC control attribute to Python [high · 35% confidence · unconfirmed] in dpsim/src/pybind/main.cpp:256
• Add SPDX header to new Jupyter notebook [high · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb:1
• Add DCO sign-off to notebook commit [high · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb:188
• Missing finiteness checks for SVC setpoint and state values [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:678
• Potential division by zero when converting SVC per‑unit parameters [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:61
• Potential sample-delay in secant sensitivity update [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:693
• History update order can cause one-iteration delay [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:712
• SVC parameter units mismatch in notebook example [medium · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb:61
• Use absolute value of B(idx,idx) for SVC sensitivity seed [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:691
• Degenerate sensitivity fallback should be documented [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:699
• SVC history update uses old voltage before update [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:712
• Guard division by zero in secant sensitivity estimate [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:699
• Use Math::isFinite for QmaxPU and QminPU clamping [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:703
• Use Attribute::set to trigger downstream tasks when updating SVC reactive injection [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:715
• Store SVC per-unit Q_set_pu in Attribute to enable scheduler dependencies [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:712
• Use of DOUBLE_EPSILON for negligible double comparison [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:696
• SVC per-unit conversion after base voltage propagation [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolver.cpp:65
• SVC reactive power update uses absolute value of Q_new [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:715
• Missing virtual destructor in polymorphic base class PFSolver [medium · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolver.h:192
• Missing virtual destructor in polymorphic base class PFSolverPowerPolar [medium · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolverPowerPolar.h:102
• Missing override specifier on enforceSvcVoltageControl implementation [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:657
• Missing override specifier on clearReactiveLimitState implementation [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:725
• Rename mSvcPrevQV comment to match member name [medium · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolverPowerPolar.h:82
• Clarify comment on sensitivity seeding [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:688
• Use DEBUG level for verbose SVC control logging [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:718
• Use absolute value of diagonal susceptance for SVC sensitivity seed [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:691
• Check for negligible voltage change using DOUBLE_EPSILON [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:696
• Use DOUBLE_EPSILON for negligible reactive-injection change [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:709
• Add Python binding for new SVC control attribute [medium · 35% confidence · unconfirmed] in dpsim/src/pybind/main.cpp:256
• Clear notebook outputs before commit [medium · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb:1
• Incorrect reactive‑injection sensitivity dQ/dV used for SVC voltage control [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:691
• No validation of SVC Q‑limit ordering and finiteness [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:665
• Hard‑coded voltage tolerance should be configurable or use a defined constant [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:64
• SolveTask lacks explicit attribute dependencies for SVC state updates [medium · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolver.h:240
• Missing documentation for new SVC component [medium · 35% confidence · unconfirmed] in docs/hugo/content/en/docs/Models/Concepts
• Notebook test not registered in CI test suite [medium · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb
• Comment on sensitivity seeding could be more precise [low · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:688
• Re‑invented epsilon literals in SVC secant thresholds [low · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolver.h:100

Claim vs. implementation

• Claimed: Add an opt-in solver-side outer loop that enforces SVC bus voltage setpoints in power flow, alongside related SVC setup fixes and notebook cleanup.
• Done: Adds SVC tracking to the PF solver, converts SVC per-unit parameters after base-voltage propagation, and implements an opt-in outer loop that adjusts SVC reactive injections to hold voltage setpoints, exposed through Simulation and pybind plus a demo notebook.
• Difference: none

How this review was produced

13 specialized finder passes raised 47 findings over the diff and the full changed sources. After de-duplication, 47 were re-checked against the current file and the base-class / interface headers it inherits (code as truth), escalating survivors to a stronger model: 0 refuted as unsupported, 47 kept (47 tentative).

_{Automated, non-blocking review. May be wrong. Models: find mistral-small-4-119b-2603, gpt-oss-120b → verify gpt-5.4-mini → final gpt-5.5.}

[github-actions]

DPsim LLM review

Claim vs. code: matches the description.

Found 1 critical, 10 high, 27 medium, 4 low (0 anchored to lines below).

🔵 Optional / low-confidence (42)

• Incorrect reactive‑power‑vs‑voltage sensitivity sign and magnitude [critical · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:691
• Incorrect sensitivity sign in SVC voltage-control loop [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:691
• Replace hard-coded epsilon with DOUBLE_EPSILON [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:668
• Replace hard-coded sensitivity threshold with DOUBLE_EPSILON [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:670
• Missing task-dependency edge for SVC voltage-control side effect [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:657
• Use of B(idx,idx) inside the hot path without bounds check [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:691
• SVC history update uses stale voltage value [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:712
• Missing override specifier on enforceSvcVoltageControl [high · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolverPowerPolar.h:80
• Missing override specifier on clearReactiveLimitState [high · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolverPowerPolar.h:82
• Use absolute value of diagonal susceptance for SVC sensitivity seeding [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:691
• Potential NaN/Inf propagation from unvalidated SVC attributes [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:658
• Missing documentation of SVC control law [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:688
• Incorrect voltage scaling in notebook assertion [medium · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb:102
• Use absolute value of local susceptance for SVC sensitivity seed [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:691
• Use DOUBLE_EPSILON for negligible voltage change in secant sensitivity [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:696
• Use DOUBLE_EPSILON for negligible-double comparison [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:696
• Guard degenerate sensitivity with Math::isFinite before magnitude check [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:699
• Replace hard-coded zero threshold with DOUBLE_EPSILON [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolver.cpp:486
• Guard base-voltage propagation with Math::isFinite [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolver.cpp:464
• Clamp new SVC reactive injection using Math::isFinite on limits [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:702
• Attribute usage: Q_set_pu should be an Attribute only if infra needs it [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:657
• Parallel safety: mSvcPrevQV map accessed without synchronization [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:657
• SVC per-unit conversion after base-voltage propagation is not guarded against empty mSVCs [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolver.cpp:67
• Hard-coded heuristic thresholds in enforceSvcVoltageControl should be constants [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:667
• Unused variable in comment [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:67
• Use of DOUBLE_EPSILON without std namespace qualification [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:691
• Use of DOUBLE_EPSILON without std namespace qualification [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:709
• Degenerate sensitivity fallback uses unit gain [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:699
• SVC history update uses old voltage before update [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:712
• Add Python binding for SVC voltage-control setter/getter [medium · 35% confidence · unconfirmed] in dpsim/src/pybind/main.cpp:256
• Clear notebook outputs before commit [medium · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb:1
• Add SPDX header to new Jupyter notebook [medium · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb:1
• Use of ad‑hoc literal for voltage tolerance [medium · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolver.h:99
• Use of ad‑hoc literals for secant thresholds [medium · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolver.h:102
• Missing validation of damping factor [medium · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolver.h:101
• Redundant per‑unit conversion for SVC components [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolver.cpp:68
• Missing documentation page for new SP::Ph1::SVC component [medium · 35% confidence · unconfirmed] in docs/hugo/content/en/docs/Models/Concepts
• Notebook not registered in test suite [medium · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb
• SVC per-unit conversion after base-voltage propagation [low · 35% confidence · unconfirmed] in dpsim/src/PFSolver.cpp:68
• Voltage scaling in notebook uses complex() conversion [low · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb:102
• Missing documentation for SVC control parameters [low · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolver.h:98
• Comment typo and line break in SVC control description [low · 35% confidence · unconfirmed] in dpsim/include/dpsim/Simulation.h:63

Claim vs. implementation

• Claimed: Add a solver-side outer loop to enforce SVC bus voltage setpoints, opt-in via set_pf_solver_enforce_svc_control.
• Done: Adds SVC tracking to the powerflow solver, including an opt-in outer loop that adjusts SVC reactive injections toward voltage setpoints, plus API/pybind support and an example notebook.
• Difference: none

How this review was produced

13 specialized finder passes raised 42 findings over the diff and the full changed sources. After de-duplication, 42 were re-checked against the current file and the base-class / interface headers it inherits (code as truth), escalating survivors to a stronger model: 0 refuted as unsupported, 42 kept (42 tentative).

_{Automated, non-blocking review. May be wrong. Models: find mistral-small-4-119b-2603, gpt-oss-120b → verify gpt-5.4-mini → final gpt-5.5.}

[github-actions]

DPsim LLM review

Found 7 high, 25 medium, 3 low (0 anchored to lines below).

🔵 Optional / low-confidence (35)

• Incorrect sensitivity sign in SVC voltage-control loop [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:691
• Use absolute value of diagonal susceptance for SVC sensitivity seed [high · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:691
• Missing task dependency for SVC voltage-control side effects [high · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolver.h:244
• SolveTask execute does not declare dependencies on SVC control [high · 35% confidence · unconfirmed] in dpsim/src/PFSolver.cpp:670
• Missing override specifier on enforceSvcVoltageControl [high · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolverPowerPolar.h:80
• Missing override specifier on enforceSvcVoltageControl [high · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolver.h:170
• Add SPDX license header to new notebook [high · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb:1
• Sample-delay in secant sensitivity update [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:693
• Incorrect state update in SVC control loop [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:712
• Incorrect voltage scaling in verification step [medium · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb:102
• SVC updateReactivePowerInjection called without dependency edge [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:715
• Rename member variable to follow naming convention [medium · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolver.h:98
• Clarify explanatory comment for tolerance member [medium · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolver.h:99
• Clarify explanatory comment for enforceSvcVoltageControl [medium · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolverPowerPolar.h:79
• Clarify meaning of constant svcSecantDQFloor [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:668
• Clarify meaning of constant svcMinSensitivity [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:670
• Clarify SVC control behavior in notebook introduction [medium · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb:10
• Use DEBUG level for non-critical SVC control logging [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:718
• Use DEBUG level for non-critical PF outer-loop warning [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolver.cpp:659
• Add documentation page for SP::Ph1::SVC voltage control [medium · 35% confidence · unconfirmed] in docs/hugo/content/en/docs/Models/SP/SVC.md
• Add numerical assertions for SVC reactive-power injection when enforcement is off [medium · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb:165
• Avoid ad‑hoc literals for tolerance thresholds [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:667
• Solver task lacks attribute dependency declarations [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolver.cpp:640
• Potential per‑step allocation of SVC vector [medium · 35% confidence · unconfirmed] in dpsim/include/dpsim/PFSolver.h:81
• Redundant per‑step SVC per‑unit calculation [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:61
• Per‑step map clearing causing heap churn [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:66
• Duplicate per-unit conversion for SVC components [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:61
• Noisy INFO logs for bus type determination [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolver.cpp:209
• Verbose INFO log inside SVC voltage‑control loop [medium · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:718
• Missing documentation page for new SVC component [medium · 35% confidence · unconfirmed] in docs/hugo/content/en/docs/Models/Concepts
• SVC component not bound in Python API [medium · 35% confidence · unconfirmed] in dpsim/src/pybind/main.cpp:598
• Notebook test not registered in CI test suite [medium · 35% confidence · unconfirmed] in examples/Notebooks/Grids/PF_SVC_VoltageControl.ipynb:1
• Redundant per‑unit parameter calculation for SVC [low · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:61
• Logging inside hot‑path may affect determinism [low · 35% confidence · unconfirmed] in dpsim/src/PFSolverPowerPolar.cpp:718
• Typo in Doxygen comment for SVC control attribute [low · 35% confidence · unconfirmed] in dpsim/include/dpsim/Simulation.h:62

How this review was produced

13 specialized finder passes raised 35 findings over the diff and the full changed sources. After de-duplication, 35 were re-checked against the current file and the base-class / interface headers it inherits (code as truth), escalating survivors to a stronger model: 0 refuted as unsupported, 35 kept (35 tentative).

_{Automated, non-blocking review. May be wrong. Models: find mistral-small-4-119b-2603, gpt-oss-120b → verify gpt-5.4-mini → final gpt-5.5.}

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

❌ Patch coverage is 94.93671% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.71%. Comparing base (8326843) to head (a7f4b12).

Files with missing lines	Patch %	Lines
dpsim/src/Simulation.cpp	71.42%	2 Missing ⚠️
dpsim/include/dpsim/PFSolver.h	50.00%	1 Missing ⚠️
dpsim/src/PFSolverPowerPolar.cpp	98.14%	1 Missing ⚠️

Additional details and impacted files

@@                    Coverage Diff                     @@
##           feature/pf-statcom-svc     #657      +/-   ##
==========================================================
+ Coverage                   72.69%   72.71%   +0.01%     
==========================================================
  Files                         514      514              
  Lines                       33278    33353      +75     
  Branches                    17986    18028      +42     
==========================================================
+ Hits                        24193    24251      +58     
+ Misses                       9084     9039      -45     
- Partials                        1       63      +62     

☔ 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.