Apply the angle gate to the matrix-free switching sensitivity

[samtalki]

Stacked on #71 — base is ck/issue-63-energized-angle-gates, so this diff is just the two commits on top. GitHub will retarget to main when #71 merges.

Summary

• Add the gated angle difference terms to the matrix-free ∂K/∂sw in src/sens/vjp_jvp.jl, which Gate DC angle limits by energized branches #71 applied to the materialized Jacobians but not here.
• Assert both the inline and cached vjp/jvp paths in test_kkt_vjp_jvp.jl, for every (op, param) pair.
• Add a direct regression under the existing binding-angle network in test_angle_diff_duals.jl.
• Clarify the fractional-switching wording in the DC OPF math docs; drop a stray blank line.

The gap

calc_kkt_jacobian_switching carries three gated angle terms in ∂K/∂sw: the va block picks up dgate * (γ_ub - γ_lb) * aₑ, and each gamma block picks up its own complementary-slackness row. The matrix-free path in _dc_topo_vjp! / _dc_topo_jvp! covered only the nu_bal, nu_flow, and va blocks arising from B and W, so it dropped all three.

Consequence: jvp(prob, op, :sw, v) and vjp(prob, op, :sw, w) disagreed with calc_sensitivity(prob, op, :sw) whenever an angle limit was binding — and only on the cold-cache path. _dcopf_vjp! / _dcopf_jvp! short-circuit to a cached dz/dsw matrix multiply when one exists, so the same call returned different answers depending on whether calc_sensitivity had run first.

This predates #71. It surfaced while reviewing it, and #71 is the natural place to close it out since its own summary covers the switching parameter Jacobians.

Why only :sw

Both kernels previously served :sw and :b through one shared body, selected by passing net.b or net.sw as a bare coeff vector. :b genuinely has no angle-gate terms — #71 establishes that the effective gate is locally constant in b within a fixed energized regime, and zero by convention at the nonsmooth b == 0 boundary. That correct-for-:b omission is exactly what made the shared kernel misleading.

The kernels now take the parameter symbol and derive coeff themselves, so they can tell the two apart, and the gate terms are added on the :sw path only. _angle_difference_gate_dsw is reused rather than re-deriving the b == 0 rule, keeping one definition shared with the materialized Jacobian. The va contribution folds into the existing w_va accumulator, so neither path gains a matvec or an allocation.

Why CI was green

test_kkt_vjp_jvp.jl called calc_sensitivity immediately before each vjp/jvp comparison, warming prob.cache.dz_dsw so the comparison silently took the cached fast path and never reached the inline kernels. Separately, the binding-angle case in test_angle_diff_duals.jl only checked calc_sensitivity. The two conditions needed to expose this never co-occurred.

Both are addressed: the comparison loops now assert the inline path against a problem instance calc_sensitivity never sees, in addition to the cached path — covering every parameter, not just :sw.

Verification status

Nothing has been executed. There is no Julia toolchain available in the environment this was written in, and CI does not run on branch pushes — only on pull_request. Opening this PR is what triggers the first run.

The signs of each added term were derived by hand against the corresponding entry in calc_kkt_jacobian_switching, under the out = -(∂K/∂p)ᵀ·u convention that the existing terms in the same function follow. That is reasoning, not a passing suite. Please read the CI result on this PR as the actual evidence.

Once green, the chain is: matrix-free :sw ≡ materialized Jacobian (new tests) ≡ finite differences (#71's existing FD loop in the same testset).

---

Generated by Claude Code