[DOCUMENTED] design note: enforcing control limits inside the Newton-Raphson

[BDonnot]

	added	removed
Docs + changelog	+597	-0
total	+597	-0

Docs only. No code changes, nothing implemented. Two files touched versus dev_1.0.1:
CHANGELOG.rst (a [TODO] entry) and docs/dev_notes/nr_control_limits.md (new).

What this is

It is the companion to outer_loop_checks_missing_data.md. That note asks the detection
question — what a post-solve "would this outer loop have fired?" check needs — and ends
several sections on the same sentence in different words: "b_min / b_max are checked,
not enforced", "this only becomes meaningful the day the limit is enforced". This
note is a proposal for that day.

The argument

docs/comparison_with_pypowsybl.rst ends its "outer loops" section on an open question:
whether a given OLF outer loop could be folded into the inner NR formulation the way
distributed slack was, or fundamentally needs iteration around the solve. The note argues
it is largely not case-by-case — five controls are the same mathematical object:

control	resource	box	regulated quantity
distributed slack	generator P	[get_min_p, get_max_p]	system active power balance
PV ↔ PQ	generator Q	[min_q_, max_q_]	bus voltage magnitude
ratio tap changer	ratio ρ	[rho_min, rho_max]	bus voltage magnitude (deadband)
area interchange	area generation	per-machine limits	area net export
secondary voltage control	group Q	per-machine limits	pilot bus voltage

Each is a bounded control resource complementary to a regulated quantity, which is a
complementarity condition, which can be written as a projection (normal-map) row and
solved by a semismooth Newton. One mechanism, instantiated five times. Only tap
discreteness (as opposed to tap limits) genuinely needs iteration around the solve.

The note covers why the classical heuristics cycle — two tests evaluated on two different
iterates, and with two coupled controls no correct ordering exists, which is why OLF
exposes transformerVoltageControlMode — the NCP / semismooth machinery and its
convergence theorem, one instantiation per control, and two adjacent questions: OLF's
state-dependent slack weights (balanceType) and the hydro produce / absorb mode case.

Why it might matter here specifically

• Every pin / release is a value inside a fixed sparsity pattern, so one analyze +
  refactorize survives a whole sweep. The pv/pq vector disappears entirely, which makes
  has_pv_changed() structurally unable to fire on a reactive-limit event —
  set_switchable_vm_buses / set_pv_pinned_buses stop being workarounds and become the
  formulation.
• VoltageControl already reserves both Jacobian slots the three-way branch needs
  (h_vm_, h_slope_), and its stranded path is a hand-rolled instance of the same row
  swap — for a lone controller the reactive-limit case would cost zero new rows, columns
  or nonzeros.
• Hvdc is the existing precedent for an extension owning a state-dependent contribution
  without touching Ybus, which is what a continuous tap ratio needs.

Costs, stated in the note and not benchmarked

Dimension growth on the common grid (free in the batch path where the union layout is
already reserved, real for a plain ac_pf); the per-control scaling constant, whose
omission is why textbook implementations fail on real grids; degeneracy exactly at a bound
and the smoothing homotopy that cures it; non-uniqueness of the AC solution set, which
this does not fix; and tap discreteness. Also a short section on why no production load
flow works this way.

History of this branch, for review

The commits are worth skipping — review the merged result. Two things went wrong and
were corrected:

1. The first commit's note claimed generators have no active power limits. True at the
   branch point, false on current dev_1.0.1: set_p_limits / get_min_p /
   get_max_p exist, and GenPCheck / BusQCheck already detect violations. The
   second commit merges dev_1.0.1 and reframes the note around the
   detection → enforcement split — which improved the plan: step 1 is now "enforce the
   limits that exist", with GenPCheck as a ready-made oracle, since every row it flags
   today is a row enforcement should silence.
2. That same commit put the note in docs/dev_notes/ (matching the convention that
   directory established: not built, not in the toctree, not cross-referenced from the
   built docs) but failed to remove the toctree entry and the :ref: the first commit
   had added — a broken docs build, caught in review. Fixed in c9d4389; see the two
   resolved threads for the mechanism.

Other content corrections from the sibling note's findings: tap control, area interchange
and secondary voltage control are blocked on the model, not the formulation (a
transformer stores no regulated bus / target / deadband; there is no Area concept, no
control zones or pilot points). And a section on how enforcement interacts with
BusQCheck's per-bus argument — the check is per bus because the per-machine split is a
convention, whereas enforcement is genuinely per machine, so the two should not be
expected to agree machine-by-machine until it exists.

Verification

• git diff --stat origin/dev_1.0.1...HEAD touches exactly CHANGELOG.rst and
  docs/dev_notes/nr_control_limits.md; no docs/*.rst mentions nr_control_limits.
• RST validated with docutils: CHANGELOG.rst produces the same 11 warnings as
  origin/dev_1.0.1, i.e. no new ones. The docs were not built (no Sphinx in the
  container), but nothing added here is built — Sphinx's default source_suffix does not
  pick up .md.
• Re-verified against the merged base that the VoltageControl ledger slots, the
  stranded row swap, TrafoContainer's "no discrete tap", HvdcLineContainer's "does
  NOT stamp the AC active power in Sbus" and _masked_slack_weights all still read as the
  note describes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CDrx7k9yW7ppP16bid8ZDN

[BDonnot]

check the ref in the docs

[BDonnot]

ok