Improve documentation of vertical interpolation
- Dominant language
- Python
- Stars
- 7
- Forks
- 10
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 5
Description
# 📚 Documentation Request
## Addition
Add more detail on vertical interpolation, to be clear about supported cases and in particular the relationship between the F03 specification and CF conventions (which iris follows).
For now, our output is always for the target UM `hybrid_height` coordinate. For UKCA NetCDF this means including `altitude` and `surface_altitude` (and model level number, level height, sigma, if they were on the target). For a UM F03 ancillary field it means setting up `blev` and friends (iris does this for us based on the cube)
If the source is altitude and means it, great.
If the source is height and means it, we generate a source altitude using the target orography
If the source is 'altitude', but really means height, it's up to the end user to correct their coordinate name.
In addition, we only support a 3D target altitude coordinate (as this is the UM hybrid height coordinate), and either a 1D or 3D source altitude/height coordinate.
Finally, the source is required to have a time - i.e. it's required to be 4D (time, altitude/height, lat, lon)
## Vertical coordinates
F03 body/PP files | F03 Appendix A | Iris/CF conventions
-- | -- | --
brsvd1 | Zsea of upper layer boundary | atmosphere_hybrid_height[^1]/level_height upper bound
blev | Zsea of level | atmosphere_hybrid_height[^1]/level_height point
brlev | Zsea of lower layer boundary | atmosphere_hybrid_height[^1]/level_height lower bound
brsvd2 | C of upper layer boundary | sigma upper bound
bhlev | C of level | sigma point
bhrlev | C of lower layer boundary | sigma lower bound
lblev | N/A[^2] | model_level_number
The names `bulev` and `bhulev` are not used by mule, in favour of `brsvd1` and `brsvd2`.
[^1]: Iris renames the `level_height` to `atmosphere_hybrid_height` on load if there is an orography (and enough other coordinates to trigger
generation of an altitude hybrid height factory).
[^2]: `model_level_number` inferred from index of other coordinates for F03 appendix A, but it's explicit in netCDF files.
Contributor guide
Research direction
Start by locating the documentation for vertical interpolation and compare the F03 body/PP and Appendix A coordinate names with the Iris/CF conventions described here. Document the supported target and source dimensions, time requirement, altitude-versus-height behavior, and the expected UM or UKCA NetCDF coordinates; done means these cases and limitations are clear to users.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100