A solver family's cached data is one object, not eighteen members

[BDonnot]

One commit, fresh from dev_0.13.2. Replaces #184, which took the opposite approach (add checks that the eighteen loose members agree) and is closed.

The problem, concretely

pre_process_solver fills in containers you hand it. Two callers hand it different ones:

// LSGrid::ac_pf -- passes the grid's own members
pre_process_solver(Vinit, acSbus_, Ybus_ac_, id_me_to_ac_solver_, ...);

// BaseBatchSolverSynch::prepare_solver_input_base -- passes the BATCH's members
_grid_model.pre_process_solver(Vinit, Sbus_, Ybus_, id_me_to_solver_, ...);

Six of the nine outputs were parameters. Three were not. At the top of _pre_process_solver_impl:

RealVect & slack_weights = is_ac ? slack_weights_ac_ : slack_weights_dc_;
SolverBusIdVect & bus_pv = is_ac ? bus_pv_ac_ : bus_pv_dc_;
SolverBusIdVect & bus_pq = is_ac ? bus_pq_ac_ : bus_pq_dc_;

Hardcoded to the grid's members whatever the caller passed for the rest. One call, output split across two objects. The tell was already sitting in the batch:

bus_pv_ = _grid_model.get_ac_pv_solver();   // reach back into the grid to collect
bus_pq_ = _grid_model.get_ac_pq_solver();   // the other half of my own output
slack_weights_ = _grid_model.get_ac_slack_weights_solver();
// TODO copies are made here, which is not ideal

Three consequences, all silent:

1. A batch build wrote its pv-pq split and slack weights into the grid's cache, next to a Ybus built for a different bus labelling — and the grid went on claiming that mixture was reusable. Checked against dev_0.13.2: need_reset_solver() stays false across such a build.
2. The reuse guard sized one owner's containers against the other's. Sizes agree far more often than labellings do, so a caller reusing its containers with a "nothing changed" control would have skipped fillpv_pq and stamped this grid's split onto its system — converged, plausible, wrong.
3. _algo.reset() / tell_solver_control() fired on the grid's own algorithm for a solve it would never perform, discarding a factorization its next powerflow would have reused.

Nothing reaches any of this today. The batch works on a private LSGrid copy and always calls tell_all_changed() first. Both are accidents; neither is written down as a requirement, and the obvious next optimisation in there (keep Ybus across scenarios) removes the second one.

The fix: make them one object

src/core/SolverSideCache.hpp, split by type, not lifetime:

	contents
SolverBusLayout	labelling, slack, pv-pq split, connectivity snapshot, allow_reuse, algo_needs_rebuild — everything whose type doesn't mention the family's scalar
SolverSideCache<T>	the above, plus mat and inj. cplx_type → AC (Ybus/Sbus), real_type → DC (Bbus/Pbus)

The split exists so the batch — which runs AC or DC, never both — can name the family-agnostic half: 82 of its 150 call sites don't care which family, and go through active_layout() instead of a ternary at every use.

LSGrid holds ac_cache_ / dc_cache_. pre_process_solver / pre_process_dc_solver take one cache reference. There is no way to hand either function half of one.

What this deletes rather than adds

• The reuse guard is cache.is_usable(nb_bus) — one place, instead of eight comparisons written inline against a mix of two objects' members.
• "Is this my cache?" is &c == &ac_cache_, two overloads picked by the family's own type. Solver-side data of a powerflow belongs to exactly one owner #184 needed nine pointer comparisons and a throw on a partial match; that whole function is gone.
• _mark_cache_valid / prevent_*_cache_reuse / init_bus_status lose their if(ac) x_ac_ else x_dc_ bodies.
• BaseBatchSolverSynch's eleven loose members become its own two caches; the read-back above, and its three copies, are gone.

It's also the extension point: remote / shared voltage-control layouts, HVDC droop data — add a field and it inherits the lifetime, invalidation and consistency rules of everything already there.

DualAlgoControl deliberately stays put. It's threaded through every element-container mutator signature and is already correctly per-family.

Behaviour changes (all in the foreign-build path)

• A build into a caller's cache never reuses. solver_control, the snapshot init_bus_status() raises its flags against, and those flags all describe this grid and say nothing about someone else's cache.
• It retires this grid's cache for that family afterwards. The labelling and the split still have to be published — the NR extensions read them back through lsgrid_ptr rather than from what the solver was handed, including bus_pq, which fill_voltage_control_solver_data needs and which the old write-through supplied by accident. Publishing the matrix too would mean copying it, so what remains is a view for the extensions, not a cache: snapshot cleared, control raised, next own powerflow rebuilds.
• The grid's own algorithm is no longer reset or reconfigured for a solve it will never perform.

⚠️ ABI

This changes LSGrid's member layout. The note that sat on _forced_ref_slack_bus_id ("declared LAST so existing member offsets are unchanged — ABI-stable for the gpusim2grid cross-module LSGrid cast") cannot survive regrouping scattered members. docs/solver_plugin.rst already requires the same version of headers at runtime ("different BaseAlgo layout ... undefined behaviour"), and 1.0.0 already carries several [BREAKING] entries — so this is flagged in the changelog rather than worked around. gpusim2grid must be rebuilt against these headers.

Cost — measured

Callgrind slope, 200→1200 powerflows on the exotic-elements IEEE14 grid (so construction cancels):

	dev_0.13.2	this branch	delta
AC powerflow	839 340 instr/pf	839 541	+200 (+0.024 %)
DC, warm cache	28 095 instr/pf	28 309	+214 (+0.76 %)

The DC row is the floor — the cheapest powerflow this library can run.

Roughly two thirds of that is not this change: a per-function diff of the two profiles puts +74/pf in compute_results_tsc_rxha_no_amps and +60/pf in an Eigen::Ref helper, neither of which the diff touches — inlining decisions that moved when the translation unit was recompiled. Wall clock shows nothing: run-to-run spread on one unchanged binary (2464 → 2744 ns on the same DC case) exceeds the gap between the two binaries.

Tests

• test_cache_reuse.cpp, "the structural half … unset_changes" — the existing [unset_changes] sections all reach it through allow_cache_reuse(false), i.e. both families off, so the family that runs is stopped by is_usable's first line (if(!allow_reuse)) and those sections pass with the rest of is_usable deleted. Leaving one family automatic is what exercises the structural checks. Verified: gutting is_usable to return allow_reuse; makes it SIGSEGV.
• test_cache_reuse.cpp, "a build into someone else's cache …" — a foreign build fills the caller's cache completely, publishes what the extensions read, and retires the grid's. The need_reset_solver() assertion is the one that separates this from dev_0.13.2.
• test_batch_voltage_control.cpp — the source grid solves identically on both sides of a TimeSeries and a ContingencyAnalysis.

210 test cases / 5815 assertions pass under Release, C++14 (LS2G_CXX_STANDARD=14), ASan+UBSan, and valgrind (0 errors, no leaks).

The python layer could not be exercised locally (no pybind11 / numpy on the machine this ran on) — CircleCI's test_legacy_* jobs cover it. No python-visible API changed; pre_process_solver was never bound, and every &LSGrid:: symbol the bindings reference still resolves.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01UtvkqXMvgCig75gruZCs7u

---

Generated by Claude Code