Gate DC angle limits by energized branches

[cameronkhanpour]

Summary

• Gate DC phase-angle difference limits with an effective switching value that is zero whenever b[e] * sw[e] == 0.
• Apply the same gate to solved dual handling, KKT residuals, the analytical KKT Jacobian, switching and susceptance parameter Jacobians, and LMP congestion decomposition.
• Document the fixed-regime derivative convention around the nonsmooth b == 0 boundary.
• Add zero-susceptance bridge, KKT, Jacobian, congestion, and finite-difference regressions.

Root cause

The energized-island partition treated a branch as open when b[e] * sw[e] == 0, but the phase-angle limits were gated by sw alone. A zero-susceptance branch could therefore split the topology while still coupling the endpoint angles, leaving the solved model inconsistent with its KKT and sensitivity systems.

Impact

Zero-susceptance branches no longer constrain angles or contribute spurious angle-limit duals across otherwise independent islands. Energized and fractionally switched branches retain their existing angle-limit scaling.

Within a fixed energized regime, the effective gate has switching derivative one when b != 0 and susceptance derivative zero. The analytical convention at the nonsmooth b == 0 boundary is also zero and is documented explicitly.

Validation

• Full package suite: 2,949 assertions passed.
• Phase-angle difference suite: 118 assertions passed.
• Documentation build passed with doctests and cross-reference checks.
• Fixed-KKT finite-difference errors were below 8e-9 for switching and below 3e-10 for susceptance near zero on both signs of b.
• A zero-susceptance bridge with an excluding raw angle interval now solves as two independent islands with zero angle duals.

Closes #63

[github-actions]

Benchmark Results (Julia v1)

Time benchmarks

	main	c079143...	main / c079143...
ac_opf/kkt_jacobian/case30.m	2.75 ± 0.2 ms	2.75 ± 0.2 ms	1 ± 0.1
ac_opf/kkt_param/case30.m/switching	0.0826 ± 0.015 ms	0.0835 ± 0.015 ms	0.99 ± 0.25
dc_opf/kkt_jacobian/case30.m/cost_linear	0.214 ± 0.008 μs	0.215 ± 0.011 μs	0.995 ± 0.063
dc_opf/kkt_jacobian/case30.m/cost_quadratic	0.109 ± 0.007 μs	0.109 ± 0.006 μs	1 ± 0.085
dc_opf/kkt_jacobian/case30.m/demand	0.416 ± 0.22 μs	0.435 ± 0.12 μs	0.956 ± 0.57
dc_opf/kkt_jacobian/case30.m/flowlimit	0.649 ± 0.3 μs	0.596 ± 0.29 μs	1.09 ± 0.73
dc_opf/kkt_jacobian/case30.m/full	17.8 ± 14 μs	15.9 ± 15 μs	1.12 ± 1.3
dc_opf/kkt_jacobian/case30.m/susceptance	0.0765 ± 0.013 ms	0.0768 ± 0.012 ms	0.995 ± 0.23
parser/case30.m	0.0616 ± 0.0096 ms	0.0616 ± 0.011 ms	1 ± 0.23
time_to_load	1.77 ± 0.033 s	1.81 ± 0.0083 s	0.98 ± 0.019

Memory benchmarks

	main	c079143...	main / c079143...
ac_opf/kkt_jacobian/case30.m	0.033 M allocs: 1.17 MB	0.033 M allocs: 1.17 MB	1
ac_opf/kkt_param/case30.m/switching	1.48 k allocs: 0.603 MB	1.48 k allocs: 0.603 MB	1
dc_opf/kkt_jacobian/case30.m/cost_linear	6 allocs: 0.328 kB	6 allocs: 0.328 kB	1
dc_opf/kkt_jacobian/case30.m/cost_quadratic	6 allocs: 0.328 kB	6 allocs: 0.328 kB	1
dc_opf/kkt_jacobian/case30.m/demand	6 allocs: 1.42 kB	6 allocs: 1.42 kB	1
dc_opf/kkt_jacobian/case30.m/flowlimit	6 allocs: 1.89 kB	6 allocs: 1.89 kB	1
dc_opf/kkt_jacobian/case30.m/full	0.081 k allocs: 0.0824 MB	0.083 k allocs: 0.0828 MB	0.995
dc_opf/kkt_jacobian/case30.m/susceptance	2.28 k allocs: 0.291 MB	2.28 k allocs: 0.291 MB	1
parser/case30.m	0.082 k allocs: 4.58 kB	0.082 k allocs: 4.58 kB	1
time_to_load	0.149 k allocs: 11.1 kB	0.149 k allocs: 11.1 kB	1