MetOffice / MetOffice/lfric_apps
soil_moisture diagnostic mislabelled units kg kg-1 (should be kg m-2 / SMCL)
- Dominant language
- Fortran
- Stars
- 31
- Forks
- 118
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 8
Description
## Summary
The `soil_moisture` field is written to LFRic output/checkpoint files with a `units` attribute of **`kg kg-1`**, but the field is actually **SMCL — soil moisture content per layer in `kg m-2`** (= θ · ρ_water · Δz_layer). The units metadata should be corrected to `kg m-2`.
## Evidence that the field is `kg m-2` (SMCL), not `kg kg-1`
`soil_moisture` is JULES' `smcl_soilt` prognostic (UM STASH 9), which is a per-layer moisture *content* in `kg m-2`, not a mass fraction:
- `interfaces/jules_interface/source/kernel/process_soil_kernel_mod.F90` — the interface documents the argument as `kg m-2`, and the moisture-bounding logic builds its limits as `θ · dzsoil · rho_water` and compares them **directly** against `soil_moisture`:
```fortran
!> @param[in,out] soil_moisture Soil moisture content (kg m-2)
...
smc_min = 0.1_r_def * soil_moist_wilt(map_2d(1)) * dzsoil(n) * rho_water
smc_max = soil_moist_sat(map_2d(1)) * dzsoil(n) * rho_water
```
This is only dimensionally consistent if `soil_moisture` is `kg m-2`.
- `interfaces/jules_interface/source/kernel/jules_extra_kernel_mod.F90` maps it one-to-one onto `smcl_soilt` (annotated `kg m-2`), and `jules_exp_kernel_mod.F90` copies it into `soil_layer_moisture` (`kg m-2`).
- STASH identity: `applications/lfricinputs/source/common/lfricinp_stashmaster_mod.f90` — `stashcode_soil_moist = 9` (UM STASH 9 = SMCL, `kg m-2` per layer).
So the physics unambiguously treats `soil_moisture` as `kg m-2`; the `kg kg-1` label on the written field is incorrect.
## Where this was observed
The mislabelled `units = "kg kg-1"` attribute appears on `soil_moisture` in LFRic UGRID output — e.g. UK-domain `restartLFRicAtm_*` checkpoints and GAL9 global dumps.
## Suggested fix
Correct the `units` metadata for `soil_moisture` (STASH 9 / `smcl_soilt`) in the field/diagnostic definition that drives the written attribute, from `kg kg-1` to `kg m-2`.
## Impact
Purely a metadata/label correction — the stored values are already SMCL (`kg m-2`) and are used correctly by the physics; only the written `units` string is wrong. Downstream tools that trust the `units` attribute (rather than the STASH/field identity) would mis-scale the data.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the named STASH and JULES interface files, especially applications/lfricinputs/source/common/lfricinp_stashmaster_mod.f90 and the soil-moisture kernel files, then locate the field or diagnostic definition that writes the units attribute. Change only the soil_moisture metadata from kg kg-1 to kg m-2 and verify that generated LFRic output reports the corrected units without changing stored values.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- fortran
- Domain
- data
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 74/100