feat(magicc7): concentration-driven mode for CO2 / CH4 / N2O

[benmsanderson]

What

Brings the MAGICC7 adapter to parity with the FaIR2 / CICEROSCMPY2 adapters' RunMode.CONCENTRATION_DRIVEN support, so a single openscm_runner.run.run call can drive all three models from Atmospheric Concentrations|* inputs.

v1 scope: CO2 / CH4 / N2O only — the three species MAGICC7 exposes via per-gas FILE_<gas>_CONC + <gas>_SWITCHFROMCONC2EMIS_YEAR cfg flags. F-gases / Montreal halocarbons (bundled-array flags) are deferred; user overlay rows for unsupported species fall through to the SCEN7 emissions path. Per-gas mixed mode mirrors FaIR2: a gas is concentration-driven only when every scenario in the batch supplies it.

rcmip3_bundle_path is required for conc-driven runs (matches FaIR2 / CICEROSCMPY2). Baseline + overlay: load the RCMIP3 baseline and overlay user-supplied concentration rows on top (year-by-year, user wins).

Key implementation note

MAGICC reads every *_CONC.IN as a contiguous annual series over its full internal window (its shipped files are ANNUALSTEPS=1, 801 rows, 1700–2500). The writer resamples whatever (possibly sparse) trajectory it has onto that grid before writing, or the Fortran readdata routine hits end-of-file at runtime.

Verification

Verified end-to-end against the real MAGICC v7.5.3 binary (ssp245):

mode	GSAT @ 2100 (CS=3, member 1)
emissions-driven	~2.77 K
concentration-driven	~2.88 K

Same ballpark, as expected for the physically-consistent bundle. Tests:

• tests/unit/adapters/test_magicc7_concentrations.py — pure-Python cfg-key + overlay-merge semantics (no binary).
• tests/integration/test_magicc7.py — conc-file-writing smoke, rcmip3_bundle_path-required guard, and a binary-driven end-to-end test (test_conc_driven_end_to_end_runs_the_binary) so the annual-grid contract can't regress silently.

Notes

• No changelog/*.md entry yet — will add with this PR number.
• Draft: stacked on feat/fair2-ciceroscmpy2-adapters-and-runmode-nonfork.

🤖 Generated with Claude Code

[znichollscr]

@benmsanderson for part 2, here's the prompt I would use in case it helps

Adding support for the F-Gases and Montreal Protocol Halogens should be quite straightforward. You need to set the fgas_switchfromconc2emis_year and mhalo_switchfromconc2emis_year to the end of the simulation (or a really big number like 10_000 is also fine). Then you need to write all the concentration files and fill the written files into the FGAS_FILES_CONC and MHALO_FILES_CONC input lists. The order of these files must match the FGAS_NAMES and MHALO_NAMES lists. If you do this for a CMIP6 scenario, e.g. ssp245, you can check your written configuration against the files that are already shipped with the magicc bundle, e.g. run/rcmip/MAGTUNE_SSP245.CFG. When you do this, you will notice that no file is specified for HALON1202. If HALON1202 is not in the RCMIP3 protocol, then this is the correct behaviour: MAGICC will us its default HALON1202 values instead (not ideal as it doesn't vary by scenario, but fine as this is a minor gas). If HALON1202 is in the RCMIP3 protocol, then these concentrations should be written too (and you might get a different result from what is in run/rcmip/MAGTUNE_SSP245.CFG).

You can check that this works by requesting the concentrations as outputs (i.e. requesting the Atmospheric Concentrations|Species variable for each species that is concentration-driven as output) and checking that what is returned as output matches what was passed in.

Per-gas mixed mode mirrors FaIR2: a gas is concentration-driven only when every scenario in the batch supplies it

I thought we removed this?

Same ballpark, as expected for the physically-consistent bundle

If you want to go really deep, you can check that we reproduce the values in AR6 Ch. 7 Table SM.7.2 (I think, from memory) for one of the SSPs - those runs are concentration-driven and should be fully reproducible (I have code that actually reproduces them somewhere, which I can pull out for the SOD if claude goes round in circles).

[benmsanderson]

Awesome - this is great @znichollscr - and good point on using the ar6 table as reference. We have a proto version of an equivalent table in Ch5.5 now, so we'll definitely have something on those lines- but the original code would be useful. Sent from Outlook for Android<https://aka.ms/AAb9ysg>

…

________________________________ From: znichollscr ***@***.***> Sent: Saturday, 20 June 2026 02:09:34 To: openscm/openscm-runner ***@***.***> Cc: Ben Sanderson ***@***.***>; Mention ***@***.***> Subject: Re: [openscm/openscm-runner] feat(magicc7): concentration-driven mode for CO2 / CH4 / N2O (PR #104) [https://avatars.githubusercontent.com/u/114576287?s=20&v=4]znichollscr left a comment (openscm/openscm-runner#104)<#104 (comment)> @benmsanderson<https://github.com/benmsanderson> for part 2, here's the prompt I would use in case it helps Adding support for the F-Gases and Montreal Protocol Halogens should be quite straightforward. You need to set the fgas_switchfromconc2emis_year and mhalo_switchfromconc2emis_year to the end of the simulation (or a really big number like 10_000 is also fine). Then you need to write all the concentration files and fill the written files into the FGAS_FILES_CONC and MHALO_FILES_CONC input lists. The order of these files must match the FGAS_NAMES and MHALO_NAMES lists. If you do this for a CMIP6 scenario, e.g. ssp245, you can check your written configuration against the files that are already shipped with the magicc bundle, e.g. run/rcmip/MAGTUNE_SSP245.CFG. When you do this, you will notice that no file is specified for HALON1202. If HALON1202 is not in the RCMIP3 protocol, then this is the correct behaviour: MAGICC will us its default HALON1202 values instead (not ideal as it doesn't vary by scenario, but fine as this is a minor gas). If HALON1202 is in the RCMIP3 protocol, then these concentrations should be written too (and you might get a different result from what is in run/rcmip/MAGTUNE_SSP245.CFG). You can check that this works by requesting the concentrations as outputs (i.e. requesting the Atmospheric Concentrations|Species variable for each species that is concentration-driven as output) and checking that what is returned as output matches what was passed in. Per-gas mixed mode mirrors FaIR2: a gas is concentration-driven only when every scenario in the batch supplies it I thought we removed this? Same ballpark, as expected for the physically-consistent bundle If you want to go really deep, you can check that we reproduce the values in AR6 Ch. 7 Table SM.7.2 (I think, from memory) for one of the SSPs - those runs are concentration-driven and should be fully reproducible (I have code that actually reproduces them somewhere, which I can pull out for the SOD if claude goes round in circles). — Reply to this email directly, view it on GitHub<#104?email_source=notifications&email_token=AENSZZERQAIYGGV6GAYB5ET5AXI35A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINZVGU2TOMZQGE3KM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-4755573016>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AENSZZAXIM5I4CPXPZIVL5L5AXI35AVCNFSNUABFKJSXA33TNF2G64TZHMZDIOBTG44TKMZYHNEXG43VMU5TINZQGQYDEOBZGQZ2C5QC>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[benmsanderson]

Alright then @znichollscr

1. The intersection rule — gone. MAGICC writes its own cfg + CONC.IN per scenario, so it never needed FaIR2's "every scenario must supply the gas" constraint. It's now per-scenario: a gas can be conc-driven in one scenario and emissions-driven in another. (Side effect: MAGICC's now more permissive than FaIR2 here, since FaIR2 still has the rule — I'll keep this PR magicc-only, but we can work to harmonise the approach in Feat/fair2 ciceroscmpy2 adapters and runmode nonfork #97 )

2. F-gases + Montreal halocarbons — done your way: FGAS_FILES_CONC / MHALO_FILES_CONC ordered to FGAS_NAMES / MHALO_NAMES, shared switch-year at 10000, HALON1202 slot left empty → MAGICC default (matches MAGTUNE_SSP245.CFG). There's a test cross-checking the name lists against the binary's MAGCFG_DEFAULTALL.CFG. Since each group shares one switch-year, conc-driving is all-or-nothing within a group, so I fill the whole group from the baseline and warn on unexpected empty slots.
   Current behaviour: if the group is conc-driven but the bundle is missing a trajectory for some species in it (e.g. in RCMIP - HALON1202 always; potentially others if a bundle is incomplete), the adapter will "warn-and-use-defaults" : leave that species' slot empty → fill it from MAGICC's own built-in default concentration, and we emit a warnign naming the species. So the gas is still concentration-driven, just from MAGICC's default values rather than the scenario's. alternative is to switch to emis driven for the whole group (or just fail, I guess)

Verified against real MAGICC v7.5.3 — which caught a bug: pymagicc checks the CONC.IN variable against the species token in the filename using its own naming (HFC134a, not HFC134A), so anything with a case difference blew up. Fixed the writer to use convert_magicc7_to_openscm_variables. Your round-trip check (conc in == conc out) is now in the end-to-end test.

5. AR6 reproduction — took your Table 7.SM.x suggestion and built an (opt-in) validation harness: load the AR6 600-member drawnset, run conc-driven, rebase GSAT to 1995–2014, compare percentiles. With the full RCMIP3 bundle + full ensemble the medians reproduce the MAGICC7 column almost exactly:

period SSP245 relative to 1995-2014, 600 members ours (5/50/95) AR6 MAGICC7
2021-2040 0.42 / 0.64 / 1.13 0.45 / 0.64 / 0.89
2041-2060 0.74 / 1.14 / 2.01 0.79 / 1.13 / 1.60
2081-2100 1.15 / 1.82 / 3.30 1.21 / 1.82 / 2.67
Medians match to ≤0.01 °C (validates the conc-driven path incl. the F-gas/MHalo arrays end-to-end). The 95th runs wide because I'm running the raw drawnset unweighted — I think the published ranges are the constrained/weighted distribution, which would explain the heavy upper tail with the median unchanged. This is where your reproduction code would help — mainly to confirm the constraint weights (and that I've got the concentration inputs right).

-Also added a short docs page comparing conc-driven support across the three models — species coverage is at parity across models with this PR.