Expose a unified KKT layout interface

[cameronkhanpour]

Summary

• Add and export kkt_layout as the primary KKT shape interface.
• Support both network and problem inputs for DC and AC formulations.
• Keep kkt_dims and kkt_indices as thin, backward-compatible conveniences.
• Route internal callers that need both values through one layout result.
• Document and test the unified API, including multi-island DC resizing.

Why

KKT dimensions and named index ranges were exposed through separate entry points even though callers commonly need both. Returning them together establishes one source of truth and prevents the two views of a layout from drifting apart.

Impact

Callers can now use dim, idx = kkt_layout(net_or_prob) uniformly for DC and AC systems. Existing kkt_dims and kkt_indices calls, including the legacy integer overloads, remain supported.

Validation

• julia --project=. -e "using Pkg; Pkg.test()"
• SITE_BUILD=true julia --project=docs docs/make.jl
• Verified DC and AC network/problem agreement, public exports, legacy overloads, and multi-island layout growth.

Closes #62

[github-actions]

Benchmark Results (Julia v1)

Time benchmarks

	main	6572064...	main / 6572064...
ac_opf/kkt_jacobian/case30.m	2.34 ± 0.035 ms	2.41 ± 0.041 ms	0.971 ± 0.022
ac_opf/kkt_param/case30.m/switching	0.0879 ± 0.0072 ms	0.0904 ± 0.0079 ms	0.972 ± 0.12
dc_opf/kkt_jacobian/case30.m/cost_linear	0.2 ± 0.011 μs	0.21 ± 0.01 μs	0.952 ± 0.069
dc_opf/kkt_jacobian/case30.m/cost_quadratic	0.13 ± 0.02 μs	0.13 ± 0.02 μs	1 ± 0.22
dc_opf/kkt_jacobian/case30.m/demand	0.3 ± 0.091 μs	0.341 ± 0.13 μs	0.88 ± 0.43
dc_opf/kkt_jacobian/case30.m/flowlimit	0.321 ± 0.1 μs	0.35 ± 0.12 μs	0.917 ± 0.42
dc_opf/kkt_jacobian/case30.m/full	12.2 ± 16 μs	26 ± 17 μs	0.471 ± 0.67
dc_opf/kkt_jacobian/case30.m/susceptance	0.0771 ± 0.0042 ms	0.0788 ± 0.0037 ms	0.978 ± 0.07
parser/case30.m	0.0618 ± 0.011 ms	0.0617 ± 0.014 ms	1 ± 0.29
time_to_load	1.57 ± 0.0076 s	1.57 ± 0.014 s	0.996 ± 0.01

Memory benchmarks

	main	6572064...	main / 6572064...
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.081 k allocs: 0.0824 MB	1
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

[samtalki]

LGTM