Add online mixed-layer tracer budget diagnostics

[rmholmes]

Integrates three-dimensional tracer budget process terms across the mixed layer at every model time step and divides by the mixed layer depth, enabling accurate online computation of the mixed-layer tracer budget (Holmes and Malan, article submitted to JAMES). Uses some existing mixed layer routines in ocean_tracer_diag_mod.

Two core routines added to ocean_tracer_diag_mod:
compute_budget_mld — MLD-averages a 3D tendency field
compute_tracer_at_mlb — linearly interpolates a tracer to the MLD base

Mixed layer budget tracer diagnostics:
temp/salt_in_mld — MLD-averaged tracer concentration (times rho0)
temp/salt_at_mlb — tracer at the MLD base (C_ent)

MLD-averaged tracer budget process diagnostics:
temp/salt_tendency_in_mld — total tracer tendency
temp/salt_advection_in_mld — resolved advective convergence
temp/salt_submeso_in_mld — submesoscale parameterized advection
temp/salt_vdiffuse_diff_cbt_in_mld — vertical diffusion
temp/salt_vdiffuse_diff_cbt_conv_in_mld — convective vertical diffusion
temp/salt_vdiffuse_k33_in_mld — along-isopycnal K33 mixing
temp/salt_vdiffuse_sbc_in_mld — surface boundary condition flux
temp/salt_nonlocal_KPP_in_mld — nonlocal KPP
temp/salt_rivermix_in_mld — river mixing
neutral_physics_ndiffuse_in_mld — neutral diffusion
neutral_physics_gm_in_mld — GM mesoscale eddy parameterization
frazil_3d_in_mld — frazil ice formation
sw_heat_in_mld — shortwave penetration below surface
swflx/lw_heat/sens_heat/evap_heat_in_mld — individual surface heat flux components
net_sfc_heating_in_mld — total surface heat flux
sfc_hflux_pme_in_mld — P-E+R tracer flux at surface
pme_river_in_mld — P-E+R mass flux within MLD
temp/salt_eta_smooth_in_mld — SSH smoother tendency within MLD

GVC-to-Eulerian correction terms (see Holmes and Malan appendix):
eta_t_tendency_times_temp/salt_in_mld — ∂η/∂t × MLD-avg tracer
pme_river_times_temp/salt_in_mld — P-E+R × MLD-avg tracer
eta_smoother_times_temp/salt_in_mld — SSH smoother × MLD-avg tracer
s_surf_ent_temp/salt — z* coordinate entrainment at MLD
base: (1-H/(D+η)) × ∂η/∂t × C_ent

Testing diagnostics:
eta_t_tendency_times_temp/salt_at_mlb — ∂η/∂t × tracer at MLD base

For more information including analysis code see:

• https://github.com/rmholmes/access-om2-sst-budget, in particular the Theory_and_Diagnostics.ipynb notebook.
• Holmes and Malan, journal article submitted to JAMES.

The changes in this commit were developed on an older version of MOM5. Claude Sonnet 4.6 assisted in porting them onto the current ACCESS-NRI MOM5 codebase (upstream/upstream-master) by extracting a patch from the development branch, applying it with conflict resolution, and improving inline Fortran documentation in the new code.

Addresses the mixed layer budget diagnostics part (not the hat-averaging part) of #77

[rmholmes]

Ok @dougiesquire , how's this?

[dougiesquire]

Thanks @rmholmes - looks good. I've kicked off a "prerelease" build of ACCESS-OM2 with your MOM5 changes here. With luck, that will create a set of executables we can test shortly. Note, if you wish to use the prerelease infrastucture to do this sort of thing yourself in the future, there are some instructions here.

(Note, I'm working on the assumption that we want a version of ACCESS-OM2 with your changes to test etc before we review and merge your code)

[rmholmes]

Thanks @dougiesquire . Yes - we definitely want to test it before merging. For that, I will just want to run a few years of a 1-degree IAF simulation (with a modified diag_table) and do some analysis on it to check that everything is working.

[dougiesquire]

The prerelease build has completed and I've just pushed a branch to the access-om2-configs repo that's based on the 1deg_jra55_iaf configuration but uses the prerelease version. For future reference, changing the ACCESS-OM2 version in the configuration is as simple as modifying a few lines in the config.yaml file:

modules:
  use:
      - /g/data/vk83/modules
+     - /g/data/vk83/prerelease/modules
  load:
-     - access-om2/2026.05.000
+     - access-om2/pr151-1
      - model-tools/fre-nctools/2024.05-1

...

manifest:
  reproduce:
-   exe: True
+   exe: False

You can clone the configuration branch using Payu, something like:

payu clone \
    --branch rmholmes-diag-1deg_jra55_iaf \
    https://github.com/ACCESS-NRI/access-om2-configs.git \
    <name-of-exp-dir>

[rmholmes]

@dougiesquire I added a few more changes to account for diagnostics that are not active in the 1/4-degree config but are in the 1-degree config. How would I test a config with these updates (I had a quick look but it wasn't obvious to me).

[dougiesquire]

Hi @rmholmes. We can just change the MOM5 commit hash in this PR to your most recent one. That will trigger a new prerelease build that you can then use in your configuration.

I can make the change now to show you what I mean, but in the future if you want to do this yourself I can give you permission (let me know).

[dougiesquire]

Change made. Pushing that change has triggered a new OM2 build Once that completes the CI will add a new comment to the PR like this one.

[dougiesquire]

The new build has now completed. To use it in your config, change the following in your config.yaml:

modules:
  use:
      - /g/data/vk83/modules
      - /g/data/vk83/prerelease/modules
  load:
-     - access-om2/pr151-1
+     - access-om2/pr151-3
      - model-tools/fre-nctools/2024.05-1

[rmholmes]

Perfect, thanks @dougiesquire ! Hopefully I don't need too many more updates, but if I do I'll ask for the appropriate permissions.