From b1024dc1717eb6ef3df74d4a6a3adbd045f9c07c Mon Sep 17 00:00:00 2001 From: Robert Osinski Date: Thu, 5 Feb 2026 14:51:45 +0000 Subject: [PATCH 1/8] ADR-001 for CEMS / C3S hydrology --- MARS language/ADR-001-CEMS-C3S-Hydrology.md | 50 ++++++++++++++++++ MARS language/ADR-Template.md | 58 +++++++++++++++++++++ 2 files changed, 108 insertions(+) create mode 100644 MARS language/ADR-001-CEMS-C3S-Hydrology.md create mode 100644 MARS language/ADR-Template.md diff --git a/MARS language/ADR-001-CEMS-C3S-Hydrology.md b/MARS language/ADR-001-CEMS-C3S-Hydrology.md new file mode 100644 index 0000000..38a2560 --- /dev/null +++ b/MARS language/ADR-001-CEMS-C3S-Hydrology.md @@ -0,0 +1,50 @@ +# Architectural Decision Record XXX: Title of the Decision + +## Status +[**Proposed** | Accepted | Deprecated | Superseded by [ADR-XXX]] + +## Last Updated +2025-15-16 + +## Context + +For CEMS and C3S, hydrological data are produced with different hydrological models which are driven by different atmospheric model and observational data. +The layout of the current way hydrological data is archived will change. In CEMS, the different hydrological versions for the European and the global domain go into different streams under class ce. The new layout has four distinct classes for the European CEMS / C3S and the global counterparts. +The hydrological model in the current layout is stored in the ‘model’ keyword. This proposed layout will also use the model keyword for the hydrological model. One problem with the existing layout is that different model configurations used for producing the climatologies were referenced through the keyword date, which caused overwriting issues with the reforecast data. Therefore, the proposal includes introducing a new MARS keyword, configuration, which specifies not only the model version but also additional information about the setup. +Examples of different configurations used in CEMS and C3S are: +* v1, v4 +* v1-c3s-e_catchment +* v1-c3s-e_grid +* v1-c3s-ww + +The forcing is in the old layout specified by the origin mars keyword, e.g., origin=ecmf/edwz/cosmo. +As for ECMWF forcings will include IFS as well as AIFS. origin=ecmf is no longer sufficient to distinguish between the two models. With the specific post-processing templates, we are using in GRIB2 to encode the data, it is possible to distinguish the data and a string can be created for ecmf_ifs and ecmf_aifs, In general, this follows the format "centre_model", which provides more information than the current origin key. +For this reason, we propose introducing a new MARS keyword called ‘forcing’, which would more accurately represent the model used to produce the data. + + +### Options Considered + +We propose two new mars keywords. The configuration keyword keeps the information about the model version and the setup running. +The 2nd proposed key is the forcing keyword which contains the centre identifier together with the modelName. This is needed to distinguish AIFS and IFS for ECMWF, but also Cosmo and ICON. + + +### Analysis + +We did not consider other options than option 1. + +## Decision + + + +### Related Decisions + +## Consequences + + +## References + +## Authors +- Sebastien Villaume +- Robert Osinski +- Mohamed Azhar + diff --git a/MARS language/ADR-Template.md b/MARS language/ADR-Template.md new file mode 100644 index 0000000..9a77c77 --- /dev/null +++ b/MARS language/ADR-Template.md @@ -0,0 +1,58 @@ +# Architectural Decision Record XXX: Title of the Decision + +## Status +[**Proposed** | Accepted | Deprecated | Superseded by [ADR-XXX]] + +## Last Updated +YYYY-MM-DD + +## Context + +[ ] Explained the business or technical problem being solved +[ ] Described relevant constraints (time, budget, technology, regulatory) +[ ] Provided sufficient background for someone unfamiliar with the project +[ ] Included relevant ECMWF-specific considerations (operational requirements, data volumes, performance needs, etc) + +### Options Considered + +[ ] Listed all seriously considered alternatives +[ ] Provided brief descriptions of each option +[ ] Included pros and cons for each alternative + +### Analysis + +[ ] Compared options against relevant criteria (cost, performance, maintainability, risk, etc) +[ ] Explained trade-offs and their implications +[ ] Referenced any prototypes, benchmarks, or research conducted (if applicable) +[ ] Considered both immediate and long-term impacts + +## Decision + +[ ] Stated the chosen option (clearly and unambiguously) +[ ] Avoided implementation details (unless crucial to understanding the decision) +[ ] Included any conditions or limitations on the decision + +### Related Decisions + +[ ] Referenced other ADRs that influenced or are influenced by this decision +[ ] Noted any decisions this ADR modifies or supersedes +[ ] Considered impacts on existing architectural patterns +[ ] Referenced ECMWF previous decisions that may be relevant but not documented as ADRs + +## Consequences + +[ ] Listed both positive and negative expected outcomes (if applicable) +[ ] Included impacts on performance, maintainability, team productivity, operations, etc +[ ] Noted any new risks introduced or mitigated +[ ] Considered implications for future decisions + +## References + +[ ] Linked to any relevant documents, discussions, or resources that informed the decision +[ ] Included links to related ADRs, design documents, or external references + +## Authors + +- Author 1 +- Author 2 +- Author 3 \ No newline at end of file From 335fe75557fb39897810b3e3abe68b594256496f Mon Sep 17 00:00:00 2001 From: Robert Osinski Date: Thu, 5 Feb 2026 14:55:58 +0000 Subject: [PATCH 2/8] add missing title --- MARS language/ADR-001-CEMS-C3S-Hydrology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MARS language/ADR-001-CEMS-C3S-Hydrology.md b/MARS language/ADR-001-CEMS-C3S-Hydrology.md index 38a2560..2a05301 100644 --- a/MARS language/ADR-001-CEMS-C3S-Hydrology.md +++ b/MARS language/ADR-001-CEMS-C3S-Hydrology.md @@ -1,4 +1,4 @@ -# Architectural Decision Record XXX: Title of the Decision +# Architectural Decision Record 001: CEMS and C3S hydrology data in MARS ## Status [**Proposed** | Accepted | Deprecated | Superseded by [ADR-XXX]] From dc0fe6e5d85385891efbb659b63748c50c200711 Mon Sep 17 00:00:00 2001 From: Robert Osinski Date: Tue, 19 May 2026 13:47:59 +0000 Subject: [PATCH 3/8] rename ADR MARS hydrology document --- MARS language/ADR-Template.md | 58 ------------------- ...logy.md => MARS-005-CEMS-C3S-Hydrology.md} | 0 2 files changed, 58 deletions(-) delete mode 100644 MARS language/ADR-Template.md rename MARS language/{ADR-001-CEMS-C3S-Hydrology.md => MARS-005-CEMS-C3S-Hydrology.md} (100%) diff --git a/MARS language/ADR-Template.md b/MARS language/ADR-Template.md deleted file mode 100644 index 9a77c77..0000000 --- a/MARS language/ADR-Template.md +++ /dev/null @@ -1,58 +0,0 @@ -# Architectural Decision Record XXX: Title of the Decision - -## Status -[**Proposed** | Accepted | Deprecated | Superseded by [ADR-XXX]] - -## Last Updated -YYYY-MM-DD - -## Context - -[ ] Explained the business or technical problem being solved -[ ] Described relevant constraints (time, budget, technology, regulatory) -[ ] Provided sufficient background for someone unfamiliar with the project -[ ] Included relevant ECMWF-specific considerations (operational requirements, data volumes, performance needs, etc) - -### Options Considered - -[ ] Listed all seriously considered alternatives -[ ] Provided brief descriptions of each option -[ ] Included pros and cons for each alternative - -### Analysis - -[ ] Compared options against relevant criteria (cost, performance, maintainability, risk, etc) -[ ] Explained trade-offs and their implications -[ ] Referenced any prototypes, benchmarks, or research conducted (if applicable) -[ ] Considered both immediate and long-term impacts - -## Decision - -[ ] Stated the chosen option (clearly and unambiguously) -[ ] Avoided implementation details (unless crucial to understanding the decision) -[ ] Included any conditions or limitations on the decision - -### Related Decisions - -[ ] Referenced other ADRs that influenced or are influenced by this decision -[ ] Noted any decisions this ADR modifies or supersedes -[ ] Considered impacts on existing architectural patterns -[ ] Referenced ECMWF previous decisions that may be relevant but not documented as ADRs - -## Consequences - -[ ] Listed both positive and negative expected outcomes (if applicable) -[ ] Included impacts on performance, maintainability, team productivity, operations, etc -[ ] Noted any new risks introduced or mitigated -[ ] Considered implications for future decisions - -## References - -[ ] Linked to any relevant documents, discussions, or resources that informed the decision -[ ] Included links to related ADRs, design documents, or external references - -## Authors - -- Author 1 -- Author 2 -- Author 3 \ No newline at end of file diff --git a/MARS language/ADR-001-CEMS-C3S-Hydrology.md b/MARS language/MARS-005-CEMS-C3S-Hydrology.md similarity index 100% rename from MARS language/ADR-001-CEMS-C3S-Hydrology.md rename to MARS language/MARS-005-CEMS-C3S-Hydrology.md From 5ffdd34d11aa41480911591b1d3336a8b9cbf889 Mon Sep 17 00:00:00 2001 From: Robert Osinski Date: Tue, 19 May 2026 13:54:01 +0000 Subject: [PATCH 4/8] adapt title --- MARS language/MARS-005-CEMS-C3S-Hydrology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MARS language/MARS-005-CEMS-C3S-Hydrology.md b/MARS language/MARS-005-CEMS-C3S-Hydrology.md index 2a05301..d0867d2 100644 --- a/MARS language/MARS-005-CEMS-C3S-Hydrology.md +++ b/MARS language/MARS-005-CEMS-C3S-Hydrology.md @@ -1,4 +1,4 @@ -# Architectural Decision Record 001: CEMS and C3S hydrology data in MARS +# MARS Language Decision Record 005: CEMS and C3S hydrology data in MARS ## Status [**Proposed** | Accepted | Deprecated | Superseded by [ADR-XXX]] From 58b99b4e7065ffbeb4b20a4fb1cec9dd40cbb920 Mon Sep 17 00:00:00 2001 From: Robert Osinski Date: Tue, 19 May 2026 15:00:11 +0000 Subject: [PATCH 5/8] decision part --- MARS language/MARS-005-CEMS-C3S-Hydrology.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/MARS language/MARS-005-CEMS-C3S-Hydrology.md b/MARS language/MARS-005-CEMS-C3S-Hydrology.md index d0867d2..98781c8 100644 --- a/MARS language/MARS-005-CEMS-C3S-Hydrology.md +++ b/MARS language/MARS-005-CEMS-C3S-Hydrology.md @@ -1,10 +1,10 @@ # MARS Language Decision Record 005: CEMS and C3S hydrology data in MARS ## Status -[**Proposed** | Accepted | Deprecated | Superseded by [ADR-XXX]] +[~~Proposed~~ | **Accepted** | ~~Deprecated~~ | ~~Superseded by [ADR-XXX]~~] ## Last Updated -2025-15-16 +2025-05-19 ## Context @@ -33,7 +33,12 @@ The 2nd proposed key is the forcing keyword which contains the centre identifier We did not consider other options than option 1. ## Decision - +| mars_abbreviation | long_name | +|:-----------------:|:---------------------------------------| +| ef | EFAS (European flood awareness system) | +| gf | GLOFAS (Global flood awareness system) | +| eh | C3S European hydrology | +| gh | C3S Global hydrology | ### Related Decisions From 1976aa4f55f66201c0d167b3db0b5d5040641b40 Mon Sep 17 00:00:00 2001 From: Robert Osinski Date: Tue, 19 May 2026 15:10:44 +0000 Subject: [PATCH 6/8] finaling MARS ADR for hydrology --- MARS language/MARS-005-CEMS-C3S-Hydrology.md | 27 +++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/MARS language/MARS-005-CEMS-C3S-Hydrology.md b/MARS language/MARS-005-CEMS-C3S-Hydrology.md index 98781c8..b89b4bb 100644 --- a/MARS language/MARS-005-CEMS-C3S-Hydrology.md +++ b/MARS language/MARS-005-CEMS-C3S-Hydrology.md @@ -33,13 +33,38 @@ The 2nd proposed key is the forcing keyword which contains the centre identifier We did not consider other options than option 1. ## Decision -| mars_abbreviation | long_name | +The hydrology data will be archived under the following MARS classes: + +| MARS class | Name | |:-----------------:|:---------------------------------------| | ef | EFAS (European flood awareness system) | | gf | GLOFAS (Global flood awareness system) | | eh | C3S European hydrology | | gh | C3S Global hydrology | +A MARS key forcing will be introduced which will get values like +* ecmf-ifs +* ecmf-aifs +* ecmf-era5 +* ecmf-seas +* edzw-icon +* cosmo-cosmo +* cmcc-sps +* obs + +This is the centre abbreviation dash the modelName. A configuration key will be introduced as well but only used in stream rfsd. It will contain the following values: +* v1.0 +* v1.0-catchment +* v1.0-grid +* v1.0-c3s +* v2.0 +* v2.1 +* v3.0 +* v3.1 +* v3.5 +* v4.0 +* v5.0 + ### Related Decisions From 6129b619d184bc1ec9f75689af5e84a382ac0b98 Mon Sep 17 00:00:00 2001 From: Robert Osinski Date: Wed, 27 May 2026 13:09:53 +0000 Subject: [PATCH 7/8] some changes on the ADR hydrology text --- MARS language/MARS-005-CEMS-C3S-Hydrology.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/MARS language/MARS-005-CEMS-C3S-Hydrology.md b/MARS language/MARS-005-CEMS-C3S-Hydrology.md index b89b4bb..4b86ce5 100644 --- a/MARS language/MARS-005-CEMS-C3S-Hydrology.md +++ b/MARS language/MARS-005-CEMS-C3S-Hydrology.md @@ -8,24 +8,23 @@ ## Context -For CEMS and C3S, hydrological data are produced with different hydrological models which are driven by different atmospheric model and observational data. +CEMS and C3S hydrological data are produced with different hydrological models which are driven by different atmospheric model and observational data. The layout of the current way hydrological data is archived will change. In CEMS, the different hydrological versions for the European and the global domain go into different streams under class ce. The new layout has four distinct classes for the European CEMS / C3S and the global counterparts. -The hydrological model in the current layout is stored in the ‘model’ keyword. This proposed layout will also use the model keyword for the hydrological model. One problem with the existing layout is that different model configurations used for producing the climatologies were referenced through the keyword date, which caused overwriting issues with the reforecast data. Therefore, the proposal includes introducing a new MARS keyword, configuration, which specifies not only the model version but also additional information about the setup. +The hydrological model in the current layout is indexed using the ‘model’ keyword. This new proposed layout will also use the model keyword for indexing the hydrological model. One problem with the existing layout is that different model configurations used for producing the climatologies were referenced through the keyword date, which caused overwriting issues with the reforecast data. Therefore, the proposal includes introducing a new MARS keyword, configuration, which specifies not only the model version but also additional information about the setup. This configuration keyword is intended to be used only for the hindcasts as for all other data, there is no overlapping of different configurations at the same point in time. Examples of different configurations used in CEMS and C3S are: * v1, v4 * v1-c3s-e_catchment * v1-c3s-e_grid * v1-c3s-ww -The forcing is in the old layout specified by the origin mars keyword, e.g., origin=ecmf/edwz/cosmo. -As for ECMWF forcings will include IFS as well as AIFS. origin=ecmf is no longer sufficient to distinguish between the two models. With the specific post-processing templates, we are using in GRIB2 to encode the data, it is possible to distinguish the data and a string can be created for ecmf_ifs and ecmf_aifs, In general, this follows the format "centre_model", which provides more information than the current origin key. +The hydrological data are driven by different atmospheric data. In the old layout this was specified by the origin mars keyword, e.g., origin=ecmf/edwz/cosmo. As for ECMWF forcings will include IFS as well as AIFS, origin=ecmf is no longer sufficient to distinguish between the two models. With the specific post-processing templates, we are using in GRIB2 to encode the data, it is possible to distinguish the data and a string can be created like for example ecmf_ifs or ecmf_aifs. In general, this follows the format "centre_model", which provides more information than the current origin key. For this reason, we propose introducing a new MARS keyword called ‘forcing’, which would more accurately represent the model used to produce the data. ### Options Considered -We propose two new mars keywords. The configuration keyword keeps the information about the model version and the setup running. -The 2nd proposed key is the forcing keyword which contains the centre identifier together with the modelName. This is needed to distinguish AIFS and IFS for ECMWF, but also Cosmo and ICON. +We propose to introduce two new MARS keywords. +The configuration keyword stores information about the model version and the current running setup in a single key. The 2nd proposed key is the forcing keyword which contains the centre identifier together with the modelName to describe the data used to drive the hydrological model. This is needed to distinguish AIFS and IFS for ECMWF, but also the DWD Cosmo and ICON models which is not doable with the existing origin keyword. ### Analysis @@ -69,7 +68,8 @@ This is the centre abbreviation dash the modelName. A configuration key will be ### Related Decisions ## Consequences - +The data will be stored in newly created MARS classes, ensuring that existing datasets remain unaffected, except for the hydrology data, which will be rearchived within the new layout. +The forcing and configuration MARS keywords are also applicable in other contexts. For example, the fire datasets are based on ERA5 and IFS medium-range forecasts. The configuration keyword can likewise be applied to the land data assimilation system, which operates with different model versions running in parallel to support multiple target forecasting systems that rely on this data as input. ## References From 139043a1b641bdeb5acff660fe37a8c83d80dfc4 Mon Sep 17 00:00:00 2001 From: Robert Osinski Date: Wed, 27 May 2026 13:14:35 +0000 Subject: [PATCH 8/8] text changes --- MARS language/MARS-005-CEMS-C3S-Hydrology.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/MARS language/MARS-005-CEMS-C3S-Hydrology.md b/MARS language/MARS-005-CEMS-C3S-Hydrology.md index 4b86ce5..4c87941 100644 --- a/MARS language/MARS-005-CEMS-C3S-Hydrology.md +++ b/MARS language/MARS-005-CEMS-C3S-Hydrology.md @@ -23,8 +23,9 @@ For this reason, we propose introducing a new MARS keyword called ‘forcing’, ### Options Considered -We propose to introduce two new MARS keywords. -The configuration keyword stores information about the model version and the current running setup in a single key. The 2nd proposed key is the forcing keyword which contains the centre identifier together with the modelName to describe the data used to drive the hydrological model. This is needed to distinguish AIFS and IFS for ECMWF, but also the DWD Cosmo and ICON models which is not doable with the existing origin keyword. +We propose introducing two new MARS keywords. +The configuration keyword stores information about the model version and the current runtime setup within a single key. The second proposed keyword, forcing, combines the centre identifier with the modelName to describe the data used to drive the hydrological model. +This distinction is required to differentiate between AIFS and IFS at ECMWF, as well as between the COSMO and ICON models at DWD, which is not possible using the existing origin keyword alone. ### Analysis