MetOffice / MetOffice/lfric_apps

soil_moisture diagnostic mislabelled units kg kg-1 (should be kg m-2 / SMCL)

Open Beginner friendly
#647 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.