MetOffice / MetOffice/ANTS

Improve documentation of vertical interpolation

Open
#75 0 comments 0 reactions 0 assignees View on GitHub
📚 documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.