Changes between Version 7 and Version 8 of PDAF3_interface


Ignore:
Timestamp:
Mar 30, 2025, 11:25:05 AM (3 days ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • PDAF3_interface

    v7 v8  
    1111For existing implementations from PDAF V2.x, there are cases where the PDAF3 interface can be used without much changes. Generally the routines to be called for the analysis step are analogous to those present in PDAF2.3. Here PDAFomi_* routines used the functionality of PDAFomi and PDAFlocalomi_* routines used PDAF-OMI and PDAFlocal for local filter methods. We describe the necessary porting steps in the section on [wiki:PDAF3_interface?PortingtoPDAF3 Porting to the PDAF3 interface].
    1212
    13 Here we provide an overview of the routine names and the links to the interface descriptions. We distinguish the cases that the observation error covariance matrix **R** is diagonal from those that **R** is non-diagonal, i.e. the case of correlated observation errors.
     13Here we provide an overview of the routine names and the links to the interface descriptions. We distinguish the cases that the observation error covariance matrix **R** is diagonal from those that **R** is non-diagonal, i.e. the case of correlated observation errors.
     14
     15The different parts of this page are
     16* [wiki:PDAF3_interface?AnalysisstepwithdiagonalRmatrix Analysis step with diagonal R matrix]
     17* [wiki:PDAF3_interface?Analysisstepwithnon-diagonalRmatrix  Analysis step with non-diagonal R matrix]
     18* [wiki:PDAF3_interface?PortingtothePDAF3interface Porting to the PDAF3 interface]
    1419
    1520== Analysis step with diagonal R matrix ==
    … …  
    3338The universal routines include in their interface three routines related to localization. These are only executed for local filters. For the particualr case, that one only uses global filters or the LEnKF one can use one of the routines
    3439||= **Filter** =||= **fully parallel &[[BR]]flexible parallel** =||= **flexible parallel[[BR]](backward-compatibility)** =||
    35 ||= global filters[[BR]]LEnKF =|| [wiki:PDAF3_assimilate_global] || [wiki:PDAF3_put_state_global] ||
     40||= global filters[[BR]]& LEnKF =|| [wiki:PDAF3_assimilate_global] || [wiki:PDAF3_put_state_global] ||
    3641
    3742To enable an easier transition for existing PDAF2 implementations using the LEnKF to PDAF3, there is also the corresponding routine
    … …  
    4651=== 3D-Var ===
    4752
    48 Only En3DVar and hybrid 3D-Var use a local filter. The routines are the following.
     53For 3D-Var we distinguish routines for parameterized 3D-Var, ensemble 3D-Var (En3D-Var) and hybrid 3D-Var. The ensemble 3D-Var and hybrid 3D-Var use an the ESTKF or LESTKF to update the ensemble perturbations.
    4954
    50 For 3D-Var we distinguish routines for parameterized 3D-Var, ensemble 3D-Var and hybrid 3D-Var.
     55There is also the universal routine that can be used to run any of the 3D-Var methods. This can be useful if one has implemented, for example, the parameterized 3D-Var and then wants to add the ensemble 3D-Var. In this case one can right away use the univeral routine and does not need to implement the particular routine for ensemble 3D-Var.
    5156
    5257||= **Method** =||= online coupled =||= offline coupled =||
    53 ||= 3DVar =|| [wiki:PDAF3_assimilate_3dvar] || [wiki:PDAF3_put_state_3dvar] ||
    54 ||= En3DVar with ESTKF or LESTKF=|| [wiki:PDAF3_assimilate_en3dvar] || [wiki:PDAF3_put_state_en3dvar] ||
    55 ||= hyb3DVar with ESTKF or LESTKF =|| [wiki:PDAF3_assimilate_hyb3dvar] || [wiki:PDAF3_put_state_hyb3dvar] ||
     58||= 3D-Var (parameterized) =|| [wiki:PDAF3_assimilate_3dvar] || [wiki:PDAF3_put_state_3dvar] ||
     59||= En3D-Var with ESTKF or LESTKF=|| [wiki:PDAF3_assimilate_en3dvar] || [wiki:PDAF3_put_state_en3dvar] ||
     60||= hyb3D-Var with ESTKF or LESTKF =|| [wiki:PDAF3_assimilate_3dvar_all] || [wiki:PDAF3_put_state_3dvar_all] ||
     61||= Universal Routine [[BR]](all 3D-Var methods) =|| [wiki:PDAF3_assimilate_3dvar_all] || [wiki:PDAF3_put_state_3dvar_all] ||
    5662
    57 The routines for En3D-Var and hybrid 3D-Var are universal an can be used to with either the LESTKF or the global ESTKF depending on the chosen subtype.
     63**Note:**
     64* For the online-coupled case, the `PDAF3_assimilate_*` routines can be used for both the fully parallel and flexible parallization variants.
     65* The 'put_state' routines can also be used in the flexible parallelization mode. This is particularly relevant for an easier transition for existing PDAF2 implementations to the PDAF3 interface. For new implementations we recommend to the use `PDAF3_assimilate_*` routines.
     66* The particular routines for the parameterized 3D-Var have less arguments, because there is no ensemble filter involved. These routines are recommended if only the parameterized 3D-Var is implemented.
     67* Hybrid 3D-Var is called through the univeral routine, because the arguments would be the same for a routine that only executed the hybrid 3D-var schemes.
     68* There is a separate routine for the ensemble 3D-Var schemes, because they only involve covariance operations for the ensemble covariance and not the parameterized covariance. As such these routines need less arguments. However, if plans to implement both the parameterized 3D-Var and the ensemble 3D-Var one can right away use the universal routine.
    5869
    59 ||= En3DVar with LESTKF=|| [wiki:PDAF3_assimilate_en3dvar_lestkf] || [wiki:PDAF3_put_state_en3dvar_lestkf] ||
    60 ||= Hyb3DVar with ESTKF =|| [wiki:PDAF3_assimilate_hyb3dvar_lestkf] || [wiki:PDAF3_put_state_hyb3dvar_lestkf] ||
     70**Routines for particular cases**
     71
     72The generic routines for En3D-Var and hybrid 3D-Var listed in the table above can be used to with either the LESTKF or the global ESTKF depending on the chosen subtype. If one exclusively uses the global ESTKF to update the ensemble perturbations, one can use the following routines. These do not include the arguments specifying the subroutines for localization and are hence shorter
     73
     74||= **Method** =||= online coupled =||= offline coupled =||
     75||= En3DVar with ESTKF=|| [wiki:PDAF3_assimilate_en3dvar_estkf] || [wiki:PDAF3_put_state_en3dvar_estkf] ||
     76||= Hyb3DVar with ESTKF =|| [wiki:PDAF3_assimilate_hyb3dvar_estkf] || [wiki:PDAF3_put_state_hyb3dvar_estkf] ||
    6177
    6278
    … …  
    6581
    6682=== Ensemble filters ===
    67 
    68 **For non-diagonal R matrix**
    6983
    7084If the observation error covariance matrix **R** is non-diagonal, one needs to use different interface routines. These provide direct access to the routines that involve operations with the matrix **R** so that the user can implement these as efficiently as possible given the particular characteristics of **R** in they particular application.
    … …  
    87101=== 3D-Var ===
    88102
    89 
    90 **for non-diagonal R matrix**
    91 
    92103See [wiki:OMI_nondiagonal_observation_error_covariance_matrices] for information on using non-diagonal **R**-matrices with OMI.
    93104
    … …  
    100111
    101112
    102 == Porting to PDAF3 ==
     113== Porting to the PDAF3 interface ==
    103114
    104115If you like to port your existing code to using PDAF3, the required changes depend on which interface calls you used bfore:
    105 1. If you only used global filters with `PDAFomi_assimilate_global` or `PDAFomi_put_state_global`: Just change the call of the analysis routine from `PDAFomi_` to `PDAF3_`.
    106 1. If you used local filters with `PDAFlocalomi_assimilate` or `PDAFlocalomi_put_state`: Change the call of the analysis routine to `PDAF3_assimilate`. In addition move the argument `prepoststep_pdaf` to the correct position.
     116
     117**For ensemble filters:**
     1181. If you used local filters with `PDAFlocalomi_assimilate` or `PDAFlocalomi_put_state`: Change the call of the analysis routine to `PDAF3_assimilate`. In addition move the argument `prepoststep_pdaf` to the correct position.1.
     119If you only used global filters with `PDAFomi_assimilate_global` or `PDAFomi_put_state_global`: Just change the call of the analysis routine from `PDAFomi_` to `PDAF3_`.
    1071201. If you used both `PDAFomi_assimilate_global` and `PDAFlocalomi_assimilate` you can merge the calls to using only `PDAF3_assimilate` by adapting the call to `PDAFlocalomi_assimilate` as described above and then calling this routine for all filters.
    1081211. If you used the LEnKF with `PDAFomi_assimilate_lenkf` or `PDAFomi_put_state_lenkf`: Change the call of the analysis routine for `PDAFlocalomi_` to `PDAF3_`. In addition move the argument `prepoststep_pdaf` to the correct position. (There is also the new routine `PDAF_set_localize_covar` which allows user to use `PDAF3_assimilate` (or `PDAF3_assimilate_global` which makes implementing the additional routine `localize_covar_pdafomi` obsolete)
    109 1. If you used local filter with `PDAFomi_assimilate_local` or `PDAFomi_put_state_local`: Change the call of the analysis routine from `PDAFomi_` to `PDAF3_` and follow the [wiki:PDAFlocal_overview implementation instructions to for implementing the state location with PDAFlocal].
    110 1. If you used the `PDAF_assimilate_*` or `PDAF_put_state_*` routines of PDAF-1, thus the routines with the full interface you need to follow the genral implementation instructions for PDAF3. The changes will be to use the functionality of PDAF-OMI and, for local filter, of PDAFlocal.
     1221. If you used local filters with `PDAFomi_assimilate_local` or `PDAFomi_put_state_local`: Change the call of the analysis routine from `PDAFomi_` to `PDAF3_` and follow the [wiki:PDAFlocal_overview implementation instructions to for implementing the state localization with PDAFlocal].
     1231. If you used the `PDAF_assimilate_*` or `PDAF_put_state_*` routines of PDAF-1, thus the routines with the full interface, you need to follow the general implementation instructions for PDAF3. The changes will be to use the functionality of PDAF-OMI and, for local filter, of PDAFlocal. However, in PDAF3, the full PDAF-1 interface routines are still present. One just needs to include them with `USE PDAF`.
     124
     125**For 3D-Vars:**
     1261. If you used the parameterized 3D-Var and also either or both of the ensemble 3D-Var and hybrid 3D-Var with PDAFlocalomi routines: Change the call `PDAFlocalomi_assimilate_hy3dvar_lestkf` to `PDAF3_assimilate_3dvar_all` and call this routine for all 3D-Var methods. This is analogous for 'put_state'/
     1271. If you used only the parameterized 3D-Var using `PDAFomi_assimilate_3dvar` or `PDAFomi_put_state_3dvar`: Just change the call of the analysis routine from `PDAFomi_` to `PDAF3_`.
     1281. If you used the hybrid 3D-Var with `PDAFlocalomi_assimilate_hyb3dvar_lestkf` or `PDAFlocalomi_put_state_hyb3dvar_lestkf`: Just change the call of the analysis routine from `PDAFlocalomi_` to `PDAF3_`.
     1291. If you used the ensemble 3D-Var with `PDAFlocalomi_assimilate_en3dvar_lestkf` or `PDAFlocalomi_put_state_en3dvar_lestkf`: Just change the call of the analysis routine from `PDAFlocalomi_` to `PDAF3_`.
     1301. If you used the hybrid 3D-Var or ensemble 3D-Var with `PDAFomi_*` routines: Follow the [wiki:PDAFlocal_overview implementation instructions to for implementing the state localization with PDAFlocal]. Afterwards change the the PDAFomi_* call to the PDAF3_* interface.
     1311. If you used the `PDAF_assimilate_*` or `PDAF_put_state_*` routines of PDAF-1, thus the routines with the full interface, you need to follow the general implementation instructions for PDAF3. The changes will be to use the functionality of PDAF-OMI and, for local filter, of PDAFlocal. However, in PDAF3, the full PDAF-1 interface routines are still present. One just needs to include them with `USE PDAF`.