From 3ea97e8e30187928a383bd329420276ee2d1c0bb Mon Sep 17 00:00:00 2001 From: Matthew Griffith <93525584+mjg41@users.noreply.github.com> Date: Thu, 19 Mar 2026 16:32:36 +0000 Subject: [PATCH 1/4] Initial commit detailing ADR and outcome of meeting today. Images included in new images folder. --- ADR/ADR-007-Land-Surface-Tile-Data.md | 302 +++++++++++++++++++++++++ ADR/images/tile_scheme_details_1.png | Bin 0 -> 13 bytes ADR/images/tile_scheme_details_2.png | Bin 0 -> 13 bytes ADR/images/tile_schemes_comparison.png | Bin 0 -> 13 bytes 4 files changed, 302 insertions(+) create mode 100644 ADR/ADR-007-Land-Surface-Tile-Data.md create mode 100644 ADR/images/tile_scheme_details_1.png create mode 100644 ADR/images/tile_scheme_details_2.png create mode 100644 ADR/images/tile_schemes_comparison.png diff --git a/ADR/ADR-007-Land-Surface-Tile-Data.md b/ADR/ADR-007-Land-Surface-Tile-Data.md new file mode 100644 index 0000000..5d1fe17 --- /dev/null +++ b/ADR/ADR-007-Land-Surface-Tile-Data.md @@ -0,0 +1,302 @@ +# ADR-00X: Land surface tile data + +# Status + +Proposed + +# Last Updated + +19.03.2026 + +# Context + +### Background + +Land surface tiling is a technique used in numerical weather prediction models to represent sub-grid scale heterogeneity of surface characteristics within a single grid box. Instead of representing each grid box with a single uniform surface type, tiling schemes divide the grid box into multiple surface types (tiles), each with its own fraction of coverage and potentially different attributes. This allows models to better capture the diversity of land surfaces and their distinct meteorological responses. + +For example, a single grid box might contain ocean, urban areas, and forest, each occupying different fractions of the grid box area. Parameters such as 2-meter temperature (2t) can vary significantly across these different surface types and encoding them separately provides more detailed and accurate information than a single grid box average. + +We introduced new product definition templates (4.113, 4.114, 4.115, and 4.116) to support generalised tile encoding. These templates include several key metadata elements: + +- **Tile Classification** (Code Table 4.242): Specifies the land cover survey used (e.g., ECOCLIMAP-SG, GLCC v2.0 BATS) +- **Type of Tile** (Code Table 4.252): The specific tile type within the survey (e.g., 1001 for Sea and Oceans, 1502 for Non-forest grouping) +- **Attribute of Tile** (Code Table 4.241): Additional attributes that modify the tile state (e.g., UNMOD (Unmodified), ICE, SNOW, AGG (Aggregated), ITCW (With intercepted water)) +- **Number of Used Spatial Tiles**: Total number of different tile types in the configuration +- **Number of Used Tile Attribute Combinations**: How many tile + attribute combinations exist for the specific tile type +- **UUID of Data Group**: Unique identifier linking related tile messages together + +See the full specification at: + +In the context of Destination Earth on-demand-extremes-dt, part of the output portfolio is to provide data on tiles. Here, two different tile schemes are run simultaneously to capture both a simple tile configuration, as well as one which is more granular and captures more details. + +In the context of CARRA2 project, extensive regional reanalyses dataset is ready to be archived in the production. As a part of that dataset, there are parameters produced on tiles which would be archived using a single, set tile scheme. + +In the context of IFS, there is interest in producing tile output in GRIB2 for future cycles (e.g. cy51r1). As a part of that dataset, there would be parameters produced on tiles which would be archived using a single, set tile scheme (whilst rd expvers would be used for experimentation). + +### MARS archiving approach + +For archiving tile data in MARS, we have an existing mapping of the GRIB2 tile keys to MARS indexing keys as follows: + +- **`tile`**: Maps to "Type of Tile" from Code Table 4.252\ + Examples: + - `SEAO` (Sea and oceans) + - `GNATU` (Nature grouping) + - `GLCZU` (Urban grouping) + - `GIWAT` (Inland water grouping) +- **`tileattribute`**: Maps to "Attribute of Tile" from Code Table 4.241\ + Examples: + - `UNMOD` (Unmodified) + - `ICE` (Ice-covered) + - `ICE_SNOW` (Ice-covered + snow-covered) (concatenated attributes) + +We propose an additional indexing key as follows: + +- **`tilescheme`**: A new key to distinguish between different tile scheme configurations\ + Examples (more details below): + - `simple` (Simple grouping scheme used) + - `granular` (More detailed, granular grouping scheme used) + +The `tile` and `tileattribute` keys are the minimum required to uniquely identify which surface type and state a parameter value represents. + +### Tile scheme examples + +Different model configurations may use different levels of granularity in their tiling schemes. We illustrate two common approaches. + +Both schemes use the same ocean, urban and inland water representation but differ in how they handle natural vegetation. The simple scheme aggregates all nature into one tile (1501), while the granular scheme separates it into forest (1503) and non-forest (1502) components. + +#### Simple Tile Scheme + +A simple configuration groups vegetation types into a single broad nature category: + +| **Type Code** | **Description** | **Attribute** | **Description** | **Example Parameter** | +|---------------|-------------------|---------------|----------------------------------------------|-----------------------| +| SEAO; 1001 | Sea and oceans | UNMOD | Plain / unmodified | 2t | +| SEAO; 1001 | Sea and oceans | ICE | Ice-covered | 2t | +| SEAO; 1001 | Sea and oceans | ICE_SNOW | Ice-covered + snow-covered | 2t | +| GNATU; 1501 | Nature grouping | AGG | Tile attributes aggregated across group | 2t | +| GLCZU; 1523 | Urban grouping | AGG | Tile attributes aggregated across group | 2t | +| GIWAT; 1524 | Inland water grouping | AGG | Tile attributes aggregated across group | 2t | + +#### Granular Tile Scheme + +A more detailed configuration separates natural vegetation into forest and non-forest components: + +| **Type Code** | **Description** | **Attribute** | **Description** | **Example Parameter** | +|---------------|----------------------|---------------|----------------------------------------------|-----------------------| +| SEAO; 1001 | Sea and oceans | UNMOD | Plain / unmodified | 2t | +| SEAO; 1001 | Sea and oceans | ICE | Ice-covered | 2t | +| SEAO; 1001 | Sea and oceans | ICE_SNOW | Ice-covered + snow-covered | 2t | +| GFORE; 1502 | Forest grouping | AGG | Tile attributes aggregated across group | 2t | +| GNOFO; 1503 | Non-forest grouping | AGG | Tile attributes aggregated across group | 2t | +| GLCZU; 1523 | Urban grouping | AGG | Tile attributes aggregated across group | 2t | +| GIWAT; 1524 | Inland water grouping | AGG | Tile attributes aggregated across group | 2t | + +#### Tile Distribution example: + +![Comparison of land surface tile schemes](./images/tile_schemes_comparison.png) + +#### Possible tile schemes: + +The full options of different schemes are below — each column in the second diagram represents a possible tile scheme becoming more granular from right to left: + +![A black and white chart with red text](./images/tile_scheme_details_1.png) + +![A colorful grid with numbers](./images/tile_scheme_details_2.png) + +#### CARRA2: + +In the frame of CARRA2 project, extensive regional reanalyses dataset is ready to be archived in the production. As a part of that dataset, there are eleven parameters produced on tiles: + +- 167 - 2 metre temperature +- 174096 - 2 metre specific humidity +- 207 - 10 metre wind speed +- 228032 - Snow albedo +- 228141 - Snow depth water equivalent +- 260038 - Snow cover +- 260199 - Volumetric soil moisture +- 260242 - 2 metre relative humidity +- 260360 - Soil temperature +- 260644 - Volumetric soil ice +- 3066 - Snow depth + +Regarding the tile scheme, only a single tile scheme is used, thus no need for `tilescheme` key. + +Comparing to DestinE tile scheme, CARRA2 includes two "patches" (vegetation split in two) instead of DestinE's three ones. + +# Options Considered + +### 1. Always include `tilescheme` key + +Archive all tile data with an explicit `tilescheme` key, even when only one scheme exists in a dataset. + +#### Advantages: + +- Provides future-proofing if additional schemes are added later +- Makes the data structure uniform across all tile datasets +- Explicit metadata about configuration is always available + +#### Disadvantages: + +- Adds an unnecessary indexing dimension when only one scheme is present +- Increases MARS catalogue size with redundant entries +- May confuse users with an extra key that only ever has one value in certain contexts + +### 2. Include `tilescheme` only when multiple schemes exist + +Add the `tilescheme` key only for datasets where multiple tile configurations need to coexist (e.g., datasets which output both simple & granular schemes). + +#### Advantages: + +- Keeps MARS structure as simple as possible +- Only introduces complexity where it's genuinely needed +- Avoids adding unnecessary entries in the MARS index + +#### Disadvantages: + +- Data structure becomes inconsistent between datasets +- Adding a second scheme later requires data restructuring +- Users must know whether `tilescheme` exists before querying + +### 3. Alternative Key Names + +Regardless of when the key is included, several naming options could be considered: + +- `tilescheme`: Short and descriptive (proposed) +- `tileconfig(uration)`: More explicit but longer +- `tilesetup`: Alternative descriptive name + +# Analysis + +The `tile` and `tileattribute` keys are fundamental and must always be present to properly identify the tile type and corresponding attribute. The question is whether an additional `tilescheme` dimension is always necessary. + +### Examining typical use cases: + +- **On-Demand Extremes DT**: Will run with two different tile schemes simultaneously with the same output portfolio. Adding `tilescheme` will allow simultaneous archiving of both sets of data to serve both use cases. +- **CARRA2**: Will run with a single, set tile scheme with a single output portfolio. Adding `tilescheme` would create an extra index dimension with only one value (e.g., `tilescheme=simple` for all data). +- **ECMWF operational forecasting**: Would run with a single, set tile scheme with a single output portfolio. Adding `tilescheme` would create an extra index dimension with only one value (e.g., `tilescheme=simple` for all data). +- **Research and development**: May compare multiple tile schemes side-by-side. In this case the typical experimental workflow can be used running different experiment (`expver`) for different tile schemes. + +### Recommendation: Option 2 (Conditional Inclusion) + +We recommend including the `tilescheme` key only for datasets where multiple tile configurations genuinely need to be distinguished. This approach: + +- Only necessary for on-demand-extremes. IFS & CARRA2 do not need this. +- Keeps operational archives clean and simple +- Avoids unnecessary indexing dimension +- Provides the flexibility to add scheme when projects or datasets require it +- Follows the principle of minimal necessary metadata +- In research/development, different experiments (expvers) can be run to achieve testing different tile schemes. + +### Proposed Key Name: `tilescheme` + +Among the naming options, `tilescheme` is: + +- Concise and clear +- Consistent with existing tile-related key names (`tile`, `tileattribute`) +- Self-documenting (users understand it refers to the tile scheme) +- Shorter than `tileconfiguration` while avoiding ambiguity + +The key `tileconfig` also has these properties and so could also be considered. + +### Proposed Local Code Table Values: + +When `tilescheme` is needed, values: + +- **1 (simple)**: Simple tile scheme configuration with most-grouped tiles +- **2 (granular)**: Granular tile scheme configuration with separated tile types +- Additional values reserved for future tile schemes + +### Encoding example + +An encoding example for 2-metre temperature on the forest grouping tile with aggregated attribute: + +``` +8-9 productDefinitionTemplateNumber = 113 [Generalised tiles at a horizontal level...] +10 parameterCategory = 0 [Temperature] +11 parameterNumber = 0 [Temperature (K)] +12 tileClassification = 4 [ECOCLIMAP-SG] +13-14 typeOfTile = 1503 [Forest grouping] +15 numberOfUsedSpatialTiles = 7 +16 numberOfUsedTileAttributeCombinations = 1 +17 numberOfUsedTileAttributes = 1 +18 attributeOfTile = 7 [Aggregated] +19 totalNumberOfTileAttributeCombinations = 7 +20 tileIndex = 5 +21-36 uuidOfDataGroup = [16-byte UUID] +... +``` + +MARS namespace: + +
{
+  "messages": [
+    {
+      "domain": "g",
+      "date": 20260211,
+      "time": 1200,
+      "expver": "0001",
+      "class": "od",
+      "type": "fc",
+      "stream": "oper",
+      "step": 6,
+      "levtype": "sfc",
+      "tile": "gfor",
+      "tileattribute": "agg",
+      "tilescheme": "granular", # On-demand extremes-dt only
+      "param": 167
+    }
+  ]
+}
+
+ +Note: In this example, `tilescheme=granular` is used because the dataset contains both simple and granular schemes, as will be used in e.g. DestinE on-demand-extremes-dt. + +Within the context of the MARS catalogue, the presence of the keywords `tile` and `tileattribute` will be used to create a corresponding `paramtype=tile` entry in the catalogue. + +# Decision + +Meeting was held on 19/03/2026 to discuss the proposal with: + +- Simon Smart +- Emanuele Danovaro +- Manuel Fuentes +- Robert Osinski +- Richard Mladek +- Paul Dando +- Gabriele Arduini + +Everyone was happy with the proposal and the recommendations as above, in particular: + +- Underscore is acceptable as joining character for attributes. +- Consensus on `tilescheme` as additional key only in DestinE context. +- Happy with construction of tile and tileattribute keys. + +We will proceed with the implementation, which will include a modification: + +- Lower case for grouping names and attributes. + +# Consequences + +- Lower case for grouping names and attributes – change in ecCodes +- Changes to metkit language file, enumeration of possible values. +- Changes to metkit axes (no massaging rules whilst traversing axis). +- Changes to FDB schema(s) and build rules. +- C client comparison list of keywords. +- Evaluate need for additional C classes on mars-server side (not expected). + + + +# References + +- WMO GRIB2 Issue #191: New section 4 templates for advanced surface tiling +- GRIB2 Code Table 4.252: Type of Tile +- GRIB2 Code Table 4.241: Attribute of Tile +- GRIB2 Code Table 4.242: Tile Classification +- GRIB2 Templates 4.113, 4.114, 4.115, 4.116 + +# Authors + +- Sebastien Villaume +- Matthew Griffith +- Richard Mladek +- Robert Osinski \ No newline at end of file diff --git a/ADR/images/tile_scheme_details_1.png b/ADR/images/tile_scheme_details_1.png new file mode 100644 index 0000000000000000000000000000000000000000..ba5213fb23dc34699739844ece8c4e1d3730a40f GIT binary patch literal 13 UcmaFAe{X=FJC_s}0|NsW048?>i2wiq literal 0 HcmV?d00001 diff --git a/ADR/images/tile_scheme_details_2.png b/ADR/images/tile_scheme_details_2.png new file mode 100644 index 0000000000000000000000000000000000000000..ba5213fb23dc34699739844ece8c4e1d3730a40f GIT binary patch literal 13 UcmaFAe{X=FJC_s}0|NsW048?>i2wiq literal 0 HcmV?d00001 diff --git a/ADR/images/tile_schemes_comparison.png b/ADR/images/tile_schemes_comparison.png new file mode 100644 index 0000000000000000000000000000000000000000..ba5213fb23dc34699739844ece8c4e1d3730a40f GIT binary patch literal 13 UcmaFAe{X=FJC_s}0|NsW048?>i2wiq literal 0 HcmV?d00001 From b501368206be986ebf88b2a48e075efa20f0c347 Mon Sep 17 00:00:00 2001 From: Matthew Griffith <93525584+mjg41@users.noreply.github.com> Date: Thu, 19 Mar 2026 17:09:09 +0000 Subject: [PATCH 2/4] Fix issue with image display, hopefully! --- ADR/ADR-007-Land-Surface-Tile-Data.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ADR/ADR-007-Land-Surface-Tile-Data.md b/ADR/ADR-007-Land-Surface-Tile-Data.md index 5d1fe17..aede227 100644 --- a/ADR/ADR-007-Land-Surface-Tile-Data.md +++ b/ADR/ADR-007-Land-Surface-Tile-Data.md @@ -93,15 +93,15 @@ A more detailed configuration separates natural vegetation into forest and non-f #### Tile Distribution example: -![Comparison of land surface tile schemes](./images/tile_schemes_comparison.png) +![Comparison of land surface tile schemes](images/tile_schemes_comparison.png) #### Possible tile schemes: The full options of different schemes are below — each column in the second diagram represents a possible tile scheme becoming more granular from right to left: -![A black and white chart with red text](./images/tile_scheme_details_1.png) +![Tile scheme possible vegetation types](images/tile_scheme_details_1.png) -![A colorful grid with numbers](./images/tile_scheme_details_2.png) +![Tile scheme possible combinations to form groups](images/tile_scheme_details_2.png) #### CARRA2: From 75262f42e46682efb526f08a13fde03e0d88c5a1 Mon Sep 17 00:00:00 2001 From: Matthew Griffith <93525584+mjg41@users.noreply.github.com> Date: Thu, 19 Mar 2026 17:13:26 +0000 Subject: [PATCH 3/4] Moved to ADR-008 --- ...d-Surface-Tile-Data.md => ADR-008-Land-Surface-Tile-Data.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename ADR/{ADR-007-Land-Surface-Tile-Data.md => ADR-008-Land-Surface-Tile-Data.md} (99%) diff --git a/ADR/ADR-007-Land-Surface-Tile-Data.md b/ADR/ADR-008-Land-Surface-Tile-Data.md similarity index 99% rename from ADR/ADR-007-Land-Surface-Tile-Data.md rename to ADR/ADR-008-Land-Surface-Tile-Data.md index aede227..2d13d66 100644 --- a/ADR/ADR-007-Land-Surface-Tile-Data.md +++ b/ADR/ADR-008-Land-Surface-Tile-Data.md @@ -1,4 +1,4 @@ -# ADR-00X: Land surface tile data +# ADR-008: Land surface tile data # Status From 02ae887177b24aa6674089f5abd9ac2060c8ba37 Mon Sep 17 00:00:00 2001 From: Matthew Griffith Date: Fri, 20 Mar 2026 14:09:11 +0000 Subject: [PATCH 4/4] Renaming and moving ADR to MARS language directory. --- .../MARS-006-Land-Surface-Tile-Data.md | 4 ++-- .../images/tile_scheme_details_1.png | Bin .../images/tile_scheme_details_2.png | Bin .../images/tile_schemes_comparison.png | Bin 4 files changed, 2 insertions(+), 2 deletions(-) rename ADR/ADR-008-Land-Surface-Tile-Data.md => MARS language/MARS-006-Land-Surface-Tile-Data.md (99%) rename {ADR => MARS language}/images/tile_scheme_details_1.png (100%) rename {ADR => MARS language}/images/tile_scheme_details_2.png (100%) rename {ADR => MARS language}/images/tile_schemes_comparison.png (100%) diff --git a/ADR/ADR-008-Land-Surface-Tile-Data.md b/MARS language/MARS-006-Land-Surface-Tile-Data.md similarity index 99% rename from ADR/ADR-008-Land-Surface-Tile-Data.md rename to MARS language/MARS-006-Land-Surface-Tile-Data.md index 2d13d66..ac70bdc 100644 --- a/ADR/ADR-008-Land-Surface-Tile-Data.md +++ b/MARS language/MARS-006-Land-Surface-Tile-Data.md @@ -1,4 +1,4 @@ -# ADR-008: Land surface tile data +# MARS-006: Land surface tile data # Status @@ -299,4 +299,4 @@ We will proceed with the implementation, which will include a modification: - Sebastien Villaume - Matthew Griffith - Richard Mladek -- Robert Osinski \ No newline at end of file +- Robert Osinski diff --git a/ADR/images/tile_scheme_details_1.png b/MARS language/images/tile_scheme_details_1.png similarity index 100% rename from ADR/images/tile_scheme_details_1.png rename to MARS language/images/tile_scheme_details_1.png diff --git a/ADR/images/tile_scheme_details_2.png b/MARS language/images/tile_scheme_details_2.png similarity index 100% rename from ADR/images/tile_scheme_details_2.png rename to MARS language/images/tile_scheme_details_2.png diff --git a/ADR/images/tile_schemes_comparison.png b/MARS language/images/tile_schemes_comparison.png similarity index 100% rename from ADR/images/tile_schemes_comparison.png rename to MARS language/images/tile_schemes_comparison.png