fix(fair2): idealised conc-driven PI ERF + empty-bundle splice

[benmsanderson]

What

Fixes the two FaIR2 idealised-experiment issues surfaced while wiring the AR7 WG1 Ch5 ensemble onto the conc-driven adapters, plus docs and a regression test. Stacked on feat/fair2-ciceroscmpy2-adapters-and-runmode-nonfork.

Issue 1 — _splice_bundle_with_user KeyError on empty bundle

Idealised scenarios (abrupt-4xCO2, 1pctCO2, esm-flat10*) have no RCMIP3 emissions baseline, so _rcmip3_to_fair_emissions_df returns an empty, column-less frame. When the user also supplied Emissions|* rows, _splice_bundle_with_user hit KeyError: 'scenario' at bundle_df["scenario"].isin(...) (the if spliced_df.empty fallback is unreachable — the KeyError fires first). Short-circuit to the user's rows when the bundle is empty. Two unit regressions added (no FaIR run).

Issue 2 — +1.53 W/m² preindustrial ERF residual

Decomposed the residual on an abrupt-4xCO2 conc-driven run: it is a constant aerosol ERF offset (+0.64 W/m² in the mini calibration; +1.53 with the AR7 1.4.1 calibration), not leaking non-CO2 emissions.

Root cause: FaIR evaluates emissions-driven forcing (aerosols especially) relative to each species' baseline_emissions. The idealised path left non-CO2 species at zero emissions (the co2_only zeroing / _zero_fill_fair_arrays), so the anomaly was 0 − baseline_emissions → a constant spurious forcing. Zero emissions is not the PI reference.

Fix: for idealised scenarios, pin non-CO2 emissions-mode species to baseline_emissions (CO2 sources excluded — they are concentration-driven). The anomaly, and hence the PI forcing, becomes ~0.

Verified (mini calibration, abrupt-4xCO2 conc-driven), non-CO2 ERF at the 1850 branch point:

component	before	after
Aerosols	+0.644	+0.003
CH4	−0.065	+0.000
non-CO2 (total − CO2)	+0.414	+0.001

Non-idealised runs are untouched — the existing ssp245 modern-adapter snapshots are unchanged.

Docs

New "Idealised experiments and the non-conc-species baseline" page documenting how each adapter (MAGICC7 / FaIR2 / CICEROSCMPY2) treats non-conc species in conc-driven runs, and recommending the explicit esm-piControl emissions overlay for reproducible cross-model idealised runs.

Tests

• test_rcmip3.py: empty-bundle splice + end-to-end build_emissions_df for an idealised scenario with a user overlay (CO2 survives, non-CO2 zeroed).
• test_idealised_pi_erf.py: FaIR2 idealised non-CO2 ERF ~0 at the PI branch point (env-gated on the full RCMIP3 bundle).

Notes / follow-ups

• Fix approach: chose hold-at-baseline (true zero PI anomaly) over zero-the-forcing or accept-an-offset. This changes the idealised non-CO2 inputs vs the old (buggy) zeroing — relevant to ECS diagnostics.
• Cross-adapter PI-ERF test is FaIR2-only. MAGICC7 needs an explicit esm-piControl overlay for idealised runs (no auto-detection); CICEROSCMPY2 exposes only component-wise ERF (no plain total/CO2 pair). A true cross-adapter assertion is a follow-up.
• A smaller, separate ozone term drifts to ~−0.15 W/m² by 2000 on abrupt-4xCO2 (EESC/precursor chemistry from the bundle's prescribed non-PI concentrations) — not the PI residual; worth a follow-up look.

🤖 Generated with Claude Code