#710: Add longwave radiation diagnostics

[Zubair Maalick (zmaalick)]

Add two Group A (XIOS expression) diagnostics to the lfric_atm registry:

radiation__lw_up_clear_toa (TOA outgoing clear-sky longwave radiation)
radiation__lw_up_clear_surf (surface upwelling clear-sky longwave radiation)

Both are pointwise combinations of already-registered, already-written fields and require no Fortran:

lw_up_clear_toa = lw_up_clear_toa_rts + lw_up_toa - lw_up_toa_rts
lw_up_clear_surf = lw_up_clear_surf_rts + lw_up_toa - lw_up_toa_rts

These reproduce the UM STASH recipes m01s02i206 + m01s03i332 - m01s02i205 and m01s02i219 + m01s03i332 - m01s02i205 respectively, where the term (m01s03i332 - m01s02i205) is the every-timestep surface-temperature correction increment, expressed here as (lw_up_toa - lw_up_toa_rts).

The remaining diagnostics requested in issue #710 are already implemented (radiation__lw_up_surf, radiation__lw_net_surf, radiation__sw_up_surf, radiation__lw_up_clear_toa_rts).

PR Summary

Sci/Tech Reviewer:
Code Reviewer: Pierre Siddall (@Pierre-siddall)

Code Quality Checklist

• I have performed a self-review of my own code
• My code follows the project's style guidelines
• Comments have been included that aid understanding and enhance the readability of the code
• My changes generate no new warnings
• All automated checks in the CI pipeline have completed successfully

Testing

• I have tested this change locally, using the LFRic Apps rose-stem suite
• If any tests fail (rose-stem or CI) the reason is understood and acceptable (e.g. kgo changes)
• I have added tests to cover new functionality as appropriate (e.g. system tests, unit tests, etc.)
• Any new tests have been assigned an appropriate amount of compute resource and have been allocated to an appropriate testing group (i.e. the developer tests are for jobs which use a small amount of compute resource and complete in a matter of minutes)

trac.log

Security Considerations

• I have reviewed my changes for potential security issues
• Sensitive data is properly handled (if applicable)
• Authentication and authorisation are properly implemented (if applicable)

Performance Impact

• Performance of the code has been considered and, if applicable, suitable performance measurements have been conducted

AI Assistance and Attribution

• Some of the content of this change has been produced with the assistance of Generative AI tool name (e.g., Met Office Github Copilot Enterprise, Github Copilot Personal, ChatGPT GPT-4, etc) and I have followed the Simulation Systems AI policy (including attribution labels)

Documentation

• Where appropriate I have updated documentation related to this change and confirmed that it builds correctly

PSyclone Approval

• If you have edited any PSyclone-related code (e.g. PSyKAl-lite, Kernel interface, optimisation scripts, LFRic data structure code) then please contact the TCD Team

Sci/Tech Review

• I understand this area of code and the changes being added
• The proposed changes correspond to the pull request description
• Documentation is sufficient (do documentation papers need updating)
• Sufficient testing has been completed

(Please alert the code reviewer via a tag when you have approved the SR)

Code Review

• All dependencies have been resolved
• Related Issues have been properly linked and addressed
• CLA compliance has been confirmed
• Code quality standards have been met
• Tests are adequate and have passed
• Documentation is complete and accurate
• Security considerations have been addressed
• Performance impact is acceptable

[github-actions]

Hello Zubair Maalick (@zmaalick)! 👋

Thank you for your contribution. Since this is your first time contributing to this repository, we ask that you sign our Contributor Licence Agreement (CLA).

📄 You can read the CLA here.

To agree to the CLA, please add your details (GitHub username, Real Name, Affiliation, and Date) to the CONTRIBUTORS.md file (create one, if required) in the development branch for this PR. After signing the CLA, you won't need to do this again for future PRs.

[Zubair Maalick (zmaalick)]

Title

710: Implement longwave radiation diagnostics (clear-sky LW)

Closes #710

Diagnostics implemented

#	Field id	NetCDF name	Units	Group
1	radiation__lw_up_clear_toa	lw_up_clear_toa	W m-2	A — XML Expression
2	radiation__lw_up_clear_surf	lw_up_clear_surf	W m-2	A — XML Expression

Both are TOA / surface upwelling clear-sky longwave fluxes, added as XIOS
expression fields (Group A) built entirely from fields already present in
the registry. No Fortran or PSyclone code was required.

Of the eight diagnostics requested in the issue, six were already fully
implemented and are served by existing fields (see "Already implemented"
below); only these two clear-sky longwave fields were missing.

Implementation

Both diagnostics are Group A (XML Expression) — a single new
element each in field_def_diags.xml whose element body is an XIOS
expression over existing, already-written operand fields:

radiation__lw_up_clear_toa = radiation__lw_up_clear_toa_rts
+ radiation__lw_up_toa
- radiation__lw_up_toa_rts

radiation__lw_up_clear_surf = radiation__lw_up_clear_surf_rts
+ radiation__lw_up_toa
- radiation__lw_up_toa_rts

These reproduce the UM STASH recipes m01s02i206 + m01s03i332 - m01s02i205
(clear-sky TOA, diag 5) and m01s02i219[lev1] + m01s03i332 - m01s02i205
(clear-sky surface, diag 3). The correction term (m01s03i332 - m01s02i205)
is the every-timestep surface-temperature correction increment, which in
LFRic is exactly (radiation__lw_up_toa - radiation__lw_up_toa_rts).

The flag-gated clear_rts operands are auto-activated by XIOS when the
expression field is requested — the same mechanism already relied on by
radiation__lw_up_clear_toa_rts's neighbours and by the existing Group A
field orographic_drag__taux_orographic_drag (whose operands are likewise
flag-gated), so no force-activation is needed.

Already implemented (no work required)

Requested diagnostic (CF / time-op)	Served by existing field
surface upwelling LW (mean & inst)	radiation__lw_up_surf
net surface LW (mean)	radiation__lw_net_surf
surface upwelling SW (mean & inst)	radiation__sw_up_surf
clear-sky TOA outgoing LW (inst, raw)	radiation__lw_up_clear_toa_rts

In LFRic the mean/instantaneous distinction is a request-side XIOS
operation= choice rather than a separate field id, so the mean and
instantaneous rows of the issue collapse onto a single field each.

Files changed:

• applications/lfric_atm/metadata/field_def_diags.xml: two new radiation
  clear-sky longwave expression fields.

Similar existing diagnostics

orographic_drag__taux_orographic_drag (Group A) — an XML-expression sum of
two flag-gated operand fields (taux_orog_blk + taux_orog_gwd); comparable
because it demonstrates a Group A expression built on flag-gated operands,
exactly as here.

A second close analogue: microphysics__ls_prec (Group A) — a pointwise sum
of two sibling registry fields in the same W-m-2 / face style.

Code Review

Reviewed by Fable 5 against the LFRic Fortran coding standards.
Verdict: APPROVED (round 1)
No findings. The change touches no Fortran/.x90; registry attributes
(id, name, unit, domain_ref, long_name) and the expression operand ids
were all verified consistent with neighbouring entries.

Testing

• diag_tool.py check passes with no mismatched ids.
• field_def_diags.xml is well-formed XML.
• Fields radiation__lw_up_clear_toa (name: lw_up_clear_toa) and
  radiation__lw_up_clear_surf (name: lw_up_clear_surf) appear in NetCDF
  output when requested; all four operand ids are present in the registry.
• KGO impact: none — two new, unrequested registry entries; no existing
  field or checksum changes.

Related

Issue: #710
Plan: docs/plan/plan-issue-710.md

[iboutle]

Please can you pass this to James Manners (@mo-jmanners) for science review. Ticket still needs a few admin things doing, i.e. adding the trac.log output from running rose-stem, answering the questions and signing the CLA file. Thanks!