fix(backend): diagram-path LF outer-loop cap 20→100 + RONCI/BEON reproducibility docs

[marota]

What

• Fix: raise OpenLoadFlow's maxOuterLoopIterations to 100 on the backend's diagram / overload load-flow path.
• Docs + script: a reproducibility reference for the P.SAOL31RONCI → BEON L31CPVAN overload case (small + full French grid, incl. the CHALOY631 remedial action).

Why

The N-1 diagram / overload path runs create_olf_rte_parameter() (lib make_env_utils), which keeps OpenLoadFlow's stock maxOuterLoopIterations=20. On the full French grid the IncrementalTransformerVoltageControl outer loop needs ~40–50 iterations to settle after tripping P.SAOL31RONCI, so slow-mode AC returned MAX_ITERATION_REACHED / null flows (the "diverges, null flows everywhere" the operator hit when running without fast mode). The lib's grid2op analysis path (_create_default_lf_parameters) already raises this to 100 — only the diagram path was left at 20.

The change

recommender_service._run_ac_with_fallback now forces maxOuterLoopIterations=100. This is the single choke point behind every create_olf_rte_parameter() call site (_get_n_variant, _get_contingency_variant, diagram_mixin ×2), so one edit covers all of them.

• Convergence-only: grids that already converged are unchanged.
• The grid2op analysis path is untouched (the lib already uses 100).

Verification

• Real backend on the full grid, contingency P.SAOL31RONCI:
  • Slow mode: now CONVERGES → 95.84 % (BEON L31CPVAN; was null flows).
  • Fast mode: unchanged at 95.38 %.
• Backend pytest: 886 pass; the 2 failures are pre-existing (verified identical with the change reverted — a superposition golden-trace drift + a 422 integration-setup test, both unrelated to LF iterations).
• scripts/reproduce_ronci_overload.py reproduces all three reference values via the Hades2 SecurityAnalysis recipe to < 0.04 A (reduced N-1 98.75 %, full N-1 96.10 %, full + CHALOY631 96.03 %).

Reviewer notes

• Exact 96.10 % is RTE's Hades2 solver. pypowsybl-rte provides the bridge (and registers the Hades2 provider) but the native Hades2 module is not configured here, so the converged OpenLoadFlow value lands at 95.84–96.08 %. The remaining ~0.1 % between run_ac (95.99 %) and the SecurityAnalysis reference (96.08 %) is entirely the SA-only contingencyPropagation flag — a SecurityAnalysis-internal effect that is not reproducible by opening breakers in run_ac (tested; documented in the doc's factor-2 section).
• The small grid (config_small_grid) is intentionally left as-is — it is a 93-VL Dijon reduction whose post-contingency redistribution doesn't preserve the full-grid flow.
• Full write-up: docs/architecture/ronci-beon-reproducibility.md.

🤖 Generated with Claude Code