Add RESSURF, the surface energy flux residual, as a derived variable

[brianpm-ucar]

Closes #167.

RESTOM was already in the ADF; this adds RESSURF, the surface energy flux residual, so it can go in the AMWG table:

RESSURF = FSNS - FLNS - SHFLX - (Lv+Lf)*QFLX + Lf*1e3*(PRECC+PRECL-PRECSC-PRECSL)

with Lv = 2.501e6 and Lf = 3.337e5 J/kg (CAM shr_const). These are the same terms as CAM's own energy budget (check_energy_chng.F90), so the snow term is included as in CAM.

Changes

• lib/adf_derive.py: a RESSURF branch next to RESTOM.
• lib/adf_variable_defaults.yaml and ..._era5-1deg.yaml: RESSURF entry (copied from RESTOM, category "Sfc energy flux"), derivable_from lists the eight time series. The header note now mentions the two formula variables.
• lib/test/unit_tests/test_adf_derive.py: one test for the formula and the file name with cam.h0 and cam.h0a.

To use it, add RESSURF to diag_var_list. The run needs all eight variables in the same history stream; if one is missing, RESSURF is skipped with a message. It is not added to the example config.

Testing

• pytest lib/test/unit_tests: 264 passed. black is clean.
• Model-vs-model run (CAM7 cam.h0a vs CAM6 cam.h0, 2 years each), RESSURF and RESTOM only: it finished with no errors, the derived files carry the right stream name, and the table row and lat/lon maps were made. The derived field matches a direct recomputation from the raw time series exactly.
• Global mean RESSURF is close to RESTOM in both cases (0.056 vs 0.103 W/m2 for the coupled CAM7 case; 4.12 vs 4.18 W/m2 for the AMIP baseline), as expected.

Not checked

• Whether the colour range (copied from RESTOM, ±100 W/m2) suits land and sea ice.
• CI-pinned black 25.11.0; I ran 26.5.1.

Claude-assisted: written with Claude Code, and reviewed by a separate read-only Claude agent following AGENTS.md (no blocking findings; its non-blocking findings are fixed in this PR).

🤖 Generated with Claude Code