From f6dc26aa04e905db44629d270c52f0a6e6df955a Mon Sep 17 00:00:00 2001 From: Robert Osinski Date: Fri, 6 Feb 2026 15:54:33 +0000 Subject: [PATCH 1/4] ADR for model error fourier coefficients --- MARS language/ADR-003-model-errors.md | 85 +++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 MARS language/ADR-003-model-errors.md diff --git a/MARS language/ADR-003-model-errors.md b/MARS language/ADR-003-model-errors.md new file mode 100644 index 0000000..cf96464 --- /dev/null +++ b/MARS language/ADR-003-model-errors.md @@ -0,0 +1,85 @@ +# Architectural Decision Record 003: Model Error Coefficients Index + +## Status +[**Proposed** | Accepted | Deprecated | Superseded by [ADR-XXX]] + +## Last Updated +2026-01-09 + +## Context + +Initial request from RD: +As we are developing weak-constraint 4D-Var further, I would like to update the way we define and archive the model error fields. +At the moment, type=me is available for class LWDA and type=eme is available for class ELDA. They are used to archive 3D-fields for a deterministic or an ensemble of weak-constraint 4D-Var. +We are developing a new formulation where we would need to archive a set of 3D-fields, instead of a single 3D-fields per physical variable. I think the best way to implement this would be to have a new GRIB variable in the template (i.e. a metadata that contains an integer). This should be then linked to a new MARS key, similar to what is done with the "member" key. +Let me know what you think, happy to discuss this further and give more details/motivations if needed. + +Assessment by Data Governance +Essentially, instead of having a single value for a model error (of temperature for instance, but it could be any other parameter), the model error is now a series E1*sin(...) + E2*cos(...) + E3*sin(...) + E4*cos(...) + ..... instead of being a single value E. +We need to store the coefficients E1, E2, E3, E4, etc. For now the truncation is at E3 but it could be anything. We can't use MARS number to index these coefficients because number is rightfully used for ensemble number with type=eme. +This development is needed for 50r1. + +### Options Considered + +Option 1 +We propose a new MARS keyword, called coefficient or coeffIndex to keep it generic so that it could be used in other context than to capture the n-th model error coefficient. +An immediate implementation is available by extending the currently used "model error" local section 39 (and 25 for non deterministic). + +```bash +# Local definition 39: 4DVar model errors for long window 4Dvar system (inspired by local def 25) + +unsigned[1] componentIndex : dump; +alias mars.number=componentIndex; +unsigned[1] numberOfComponents : dump; +alias totalNumber=numberOfComponents; +unsigned[1] modelErrorType : dump; + +alias local.componentIndex=componentIndex; +alias local.numberOfComponents=numberOfComponents; +alias local.modelErrorType=modelErrorType; + +# Hours +unsigned[2] offsetToEndOf4DvarWindow : dump; +unsigned[2] lengthOf4DvarWindow : dump; +alias anoffset=offsetToEndOf4DvarWindow; +``` + +We could create a new local section from 39 by adding 2 new keys and alias it to a mars keyword: + +```bash +unsigned[1] fourierCoefficientIndex : dump; +unsigned[1] numberOfFourierCoefficients : dump; +alias mars.coeffindex=fourierCoefficientIndex; +``` + +For now, this new keyword will be solely used in the context of model errors (type=me and type=eme). Those are expert fields needed for restarting model runs but are of little use for the vast majority of people. +This needs to be implemented in metkit as well and a new layout axis needs to be implemented in the MARS server. +These coefficients are not planned to be disseminated or made available to external users. They will likely be plotted and consumed by evaluation tools. + +### Analysis +In terms of the information stored in the GRIBs, we did not consider options outside of option 1. +We had a wide ranging discussion about the options of coefficient , coeffindex , component , componentindex and other options. This settled on coeffindex fundamentally because: +* The value is not a coefficient. +* Component is already used in a related context + +## Decision +* implement a new MARS keyword coeffindex in ecCodes, metkit and mars server. +* implement in FDB schema and MARS buildRules +* review MARS client rules + metkit language rules (remove from inherited requests) + + +### Related Decisions + +## Consequences + + +## References + +## Authors +- Manuel Fuentes +- Sebastien Villaume +- Robert Osinski +- Mohamed Azhar +- Simon Smart +- Emanuele Danovaro +- Paul Dando From ba931b2be88f8a5a5b7ea2c5a62970f0486fc696 Mon Sep 17 00:00:00 2001 From: Robert Osinski Date: Tue, 19 May 2026 13:49:34 +0000 Subject: [PATCH 2/4] rename ADR MARS model errors with coefficients document --- ...R-003-model-errors.md => MARS-003-model-errors-with-coeffs.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename MARS language/{ADR-003-model-errors.md => MARS-003-model-errors-with-coeffs.md} (100%) diff --git a/MARS language/ADR-003-model-errors.md b/MARS language/MARS-003-model-errors-with-coeffs.md similarity index 100% rename from MARS language/ADR-003-model-errors.md rename to MARS language/MARS-003-model-errors-with-coeffs.md From b94a8ea0cc464a9f47fb32321ef620a343cb7795 Mon Sep 17 00:00:00 2001 From: Robert Osinski Date: Tue, 19 May 2026 13:52:53 +0000 Subject: [PATCH 3/4] adapt title --- MARS language/MARS-003-model-errors-with-coeffs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MARS language/MARS-003-model-errors-with-coeffs.md b/MARS language/MARS-003-model-errors-with-coeffs.md index cf96464..781ea12 100644 --- a/MARS language/MARS-003-model-errors-with-coeffs.md +++ b/MARS language/MARS-003-model-errors-with-coeffs.md @@ -1,4 +1,4 @@ -# Architectural Decision Record 003: Model Error Coefficients Index +# MARS Language Decision Record 003: Model Error Coefficients Index ## Status [**Proposed** | Accepted | Deprecated | Superseded by [ADR-XXX]] From 617ef9dd56a03c7f9f17adb5f24beec62eeb573d Mon Sep 17 00:00:00 2001 From: Simon Smart Date: Wed, 20 May 2026 13:17:06 +0100 Subject: [PATCH 4/4] Update formatting, etc, in MARS-003 --- .../MARS-003-model-errors-with-coeffs.md | 50 +++++++++++++------ 1 file changed, 35 insertions(+), 15 deletions(-) diff --git a/MARS language/MARS-003-model-errors-with-coeffs.md b/MARS language/MARS-003-model-errors-with-coeffs.md index 781ea12..77c5c9b 100644 --- a/MARS language/MARS-003-model-errors-with-coeffs.md +++ b/MARS language/MARS-003-model-errors-with-coeffs.md @@ -1,28 +1,35 @@ # MARS Language Decision Record 003: Model Error Coefficients Index ## Status -[**Proposed** | Accepted | Deprecated | Superseded by [ADR-XXX]] +[Proposed | **Accepted** | Deprecated | Superseded by [ADR-XXX]] ## Last Updated 2026-01-09 ## Context -Initial request from RD: -As we are developing weak-constraint 4D-Var further, I would like to update the way we define and archive the model error fields. -At the moment, type=me is available for class LWDA and type=eme is available for class ELDA. They are used to archive 3D-fields for a deterministic or an ensemble of weak-constraint 4D-Var. -We are developing a new formulation where we would need to archive a set of 3D-fields, instead of a single 3D-fields per physical variable. I think the best way to implement this would be to have a new GRIB variable in the template (i.e. a metadata that contains an integer). This should be then linked to a new MARS key, similar to what is done with the "member" key. -Let me know what you think, happy to discuss this further and give more details/motivations if needed. +Initial request from RD + +> As we are developing weak-constraint 4D-Var further, I would like to update the way we define and archive the model error fields. +> At the moment, `type=me` is available for class LWDA and `type=eme` is available for class ELDA. They are used to archive 3D-fields for a deterministic or an ensemble of weak-constraint 4D-Var. +> +> We are developing a new formulation where we would need to archive a set of 3D-fields, instead of a single 3D-fields per physical variable. I think the best way to implement this would be to have a new GRIB variable in the template (i.e. a metadata that contains an integer). This should be then linked to a new MARS key, similar to what is done with the "member" key. +> Let me know what you think, happy to discuss this further and give more details/motivations if needed. Assessment by Data Governance -Essentially, instead of having a single value for a model error (of temperature for instance, but it could be any other parameter), the model error is now a series E1*sin(...) + E2*cos(...) + E3*sin(...) + E4*cos(...) + ..... instead of being a single value E. -We need to store the coefficients E1, E2, E3, E4, etc. For now the truncation is at E3 but it could be anything. We can't use MARS number to index these coefficients because number is rightfully used for ensemble number with type=eme. + +Essentially, instead of having a single value for a model error (of temperature for instance, but it could be any other parameter), +the model error is now a series E1*sin(...) + E2*cos(...) + E3*sin(...) + E4*cos(...) + ..... instead of being a single value E. +We need to store the coefficients E1, E2, E3, E4, etc. For now the truncation is at E3 but it could be anything. +We can't use MARS number to index these coefficients because number is rightfully used for ensemble number with type=eme. + This development is needed for 50r1. ### Options Considered Option 1 -We propose a new MARS keyword, called coefficient or coeffIndex to keep it generic so that it could be used in other context than to capture the n-th model error coefficient. + +We propose a new MARS keyword, called `coefficient` or `coeffIndex` to keep it generic so that it could be used in other context than to capture the n-th model error coefficient. An immediate implementation is available by extending the currently used "model error" local section 39 (and 25 for non deterministic). ```bash @@ -52,26 +59,39 @@ unsigned[1] numberOfFourierCoefficients : dump; alias mars.coeffindex=fourierCoefficientIndex; ``` -For now, this new keyword will be solely used in the context of model errors (type=me and type=eme). Those are expert fields needed for restarting model runs but are of little use for the vast majority of people. +For now, this new keyword will be solely used in the context of model errors (type=me and type=eme). +Those are expert fields needed for restarting model runs but are of little use for the vast majority of people. + This needs to be implemented in metkit as well and a new layout axis needs to be implemented in the MARS server. These coefficients are not planned to be disseminated or made available to external users. They will likely be plotted and consumed by evaluation tools. ### Analysis + In terms of the information stored in the GRIBs, we did not consider options outside of option 1. -We had a wide ranging discussion about the options of coefficient , coeffindex , component , componentindex and other options. This settled on coeffindex fundamentally because: + +We had a wide ranging discussion about the options of `coefficient`, `coeffindex`, `component`, `componentindex` and other options. This settled on `coeffindex` fundamentally because: + * The value is not a coefficient. -* Component is already used in a related context +* `component` is already used in a related context ## Decision -* implement a new MARS keyword coeffindex in ecCodes, metkit and mars server. -* implement in FDB schema and MARS buildRules -* review MARS client rules + metkit language rules (remove from inherited requests) +Introduce a new MARS keyword, `coeffindex`, to identify which coefficient is being +stored as part of a series. + +Actions required + + * Implement encoding in eccodes + * New MARS keyword support in metkit + * New layout axis, and updated buildRules in MARS server + * Updated schema required for output into FDB + * review MARS client rules + metkit language rules (remove from inherited requests) ### Related Decisions ## Consequences +No wider consequences expected. ## References