| | 1 | = The PDAF3 Interface = |
| | 2 | |
| | 3 | |
| | 4 | [[PageOutline(2-3,Contents of this page)]] |
| | 5 | |
| | 6 | == Overview == |
| | 7 | |
| | 8 | The PDAF3 interface was introduced with PDAF V3.0 to provide a consistent interface for all DA methods. |
| | 9 | The PDAF3 interfaces utilizes the functionality of PDAF-OMI (Obervation Module Interface) and PDAFlocal for easy state vector localization. |
| | 10 | |
| | 11 | == Routines to perform the analysis step == |
| | 12 | |
| | 13 | 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. If one used such routines one an easilty port to the PDAF3 interface. For new implemenetation we recommend to use the PDAF3 interfaces right away. |
| | 14 | |
| | 15 | Here we provide an overview of the routine names and the links to the interface descriptions. |
| | 16 | |
| | 17 | === Ensemble filters === |
| | 18 | |
| | 19 | **For diagonal R matrix** |
| | 20 | |
| | 21 | For the more typical assuming that the observation error covariance matrix **R** is diagonal there are only two routines. |
| | 22 | |
| | 23 | Depending on the fully parallel are flexible implementation choose the routine |
| | 24 | ||= **Filter** =||= **fully parallel** =||= **flexible parallelization** =|| |
| | 25 | ||= domain local filters[[BR]]ENSRF/EAKF =|| [wiki:PDAF3_assimilate_local] || [wiki:PDAF3_assimilate_local][[BR]]([wiki:PDAF3_put_state_local]) || |
| | 26 | ||= global filters[[BR]]LEnKF =|| [wiki:PDAF3_assimilate_global] || [wiki:PDAF3_assimilate_global][[BR]]([wiki:PDAF3_put_state_global]) || |
| | 27 | |
| | 28 | **Notes:** |
| | 29 | * The routines [wiki:PDAF3_put_state_local] and [wiki:PDAF3_put_state_global] exist for backward-compatibility. Starting with PDAF V3.0, we recommend to use [wiki:PDAF3_assimilate_local] and [wiki:PDAF3_assimilate_global] |
| | 30 | * One can let PDAF select which of the routines to call. The function [wiki:PDAF_localfilter] allows to switch between the routines as is shown in the tutorial implementations and templates. |
| | 31 | |
| | 32 | **For non-diagonal R matrix** |
| | 33 | |
| | 34 | I the observation error covariance matrix **R** is non-diagonal, one needs to sue different interface routines. These provide direct access to the routines that involved 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. |
| | 35 | |
| | 36 | See the [wiki:OMI_nondiagonal_observation_error_covariance_matrices] for information on using non-diagonal **R**-matrices with OMI. The routines are only partly generic depending on the needed observation-specific routine: |
| | 37 | ||= **filter** =||= **fully parallel** =||= **flexible** =|| |
| | 38 | ||= LESTKF[[BR]]LETKF[[BR]] LSEIK[[BR]] =|| [wiki:PDAF3_assimilate_local_nondiagR] ||[wiki:PDAF3_assimilate_local_nondiagR][[BR]]([wiki:PDAF3_put_state_local_nondiagR]) || |
| | 39 | ||= LNETF =|| [wiki:PDAF3_assimilate_lnetf_nondiagR] || [wiki:PDAF3_assimilate_lnetf_nondiagR][[BR]]([wiki:PDAF3_put_state_lnetf_nondiagR]) || |
| | 40 | ||= LKNETF =|| [wiki:PDAF3_assimilate_lknetf_nondiagR] ||[wiki:PDAF3_put_state_lknetf_nondiagR][[BR]]([wiki:PDAF3_assimilate_lnetf_nondiagR]) || |
| | 41 | ||= ESTKF[[BR]]ETKF[[BR]] SEIK[[BR]] =|| [wiki:PDAF3_assimilate_global_nondiagR] ||[wiki:PDAF3_assimilate_global_nondiagR][[BR]]([wiki:PDAF3_put_state_global_nondiagR]) || |
| | 42 | ||= NETF[[BR]]PF[[BR]] =|| [wiki:PDAF3_assimilate_nonlin_nondiagR] ||[wiki:PDAF3_assimilate_nonlin_nondiagR][[BR]]([wiki:PDAF3_put_state_nonlin_nondiagR]) || |
| | 43 | ||= EnKF[[BR]]LEnKF =|| [wiki:PDAF3_assimilate_enkf_nondiagR] ||[wiki:PDAF3_assimilate_enkf_nondiagR][[BR]]([wiki:PDAF3_put_state_enkf_nondiagR]) || |
| | 44 | |
| | 45 | **Note:** |
| | 46 | * There is no routine for the ENSRF/EAKF for nondiagonal **R**, because these filters assume that a riagonal **R** matrix exists. |
| | 47 | |
| | 48 | === 3D-Var === |
| | 49 | |
| | 50 | Only En3DVar and hybrid 3D-Var use a local filter. The routines are the following. |
| | 51 | |
| | 52 | **for diagonal R matrix** |
| | 53 | |
| | 54 | ||= **Method** =||= **fully parallel** =||= **flexible** =|| |
| | 55 | ||= 3DVar =|| [wiki:PDAF3_assimilate_3dvar] || [wiki:PDAF3_put_state_3dvar] || |
| | 56 | ||= En3DVar with ESTKF=|| [wiki:PDAF3_assimilate_en3dvar_estkf] || [wiki:PDAF3_put_state_en3dvar_estkf] || |
| | 57 | ||= Hyb3DVar with ESTKF =|| [wiki:PDAF3_assimilate_hyb3dvar_estkf] || [wiki:PDAF3_put_state_hyb3dvar_estkf] || |
| | 58 | ||= En3DVar with LESTKF=|| [wiki:PDAF3_assimilate_en3dvar_lestkf] || [wiki:PDAF3_put_state_en3dvar_lestkf] || |
| | 59 | ||= Hyb3DVar with ESTKF =|| [wiki:PDAF3_assimilate_hyb3dvar_estkf] || [wiki:PDAF3_put_state_hyb3dvar_estkf] || |
| | 60 | |
| | 61 | |
| | 62 | **for non-diagonal R matrix** |
| | 63 | |
| | 64 | See [wiki:OMI_nondiagonal_observation_error_covariance_matrices] for information on using non-diagonal **R**-matrices with OMI. |
| | 65 | |
| | 66 | ||= **Method** =||= **fully parallel** =||= **flexible** =|| |
| | 67 | ||= 3DVar =|| [wiki:PDAF3_assimilate_3dvar_nondiagR] || [wiki:PDAF3_put_state_3dvar_nondiagR] || |
| | 68 | ||= En3DVar with LESKTF=|| [wiki:PDAF3_assimilate_en3dvar_lestkf_nondiagR] || [wiki:PDAF3_put_state_en3dvar_lestkf_nondiagR] || |
| | 69 | ||= En3DVar with ESTKF =|| [wiki:PDAF3_assimilate_en3dvar_estkf_nondiagR] || [wiki:PDAF3_put_state_en3dvar_estkf_nondiagR] || |
| | 70 | ||= Hyb3DVar with LESTKF=|| [wiki:PDAF3_assimilate_hyb3dvar_lestkf_nondiagR] || [wiki:PDAF3_put_state_hyb3dvar_lestkf_nondiagR] || |
| | 71 | ||= Hyb3DVar with ESTKF=|| [wiki:PDAF3_assimilate_hyb3dvar_estkf_nondiagR] || [wiki:PDAF3_put_state_hyb3dvar_estkf_nondiagR] || |
| | 72 | |
| | 73 | |
| | 74 | == Porting to PDAF3 == |
| | 75 | |
| | 76 | If you like to port your existing code to using PDAF3, the required changes depend on which interface calls you used bfore: |
| | 77 | 1. If you used global filters with `PDAFomi_assimilate_global` or `PDAFomi_put_state_global`: Just change the call of the analysis routine from `PDAFomi_` to `PDAF3_`. |
| | 78 | 1. If you used local filters with `PDAFlocalomi_assimilate` or `PDAFlocalomi_put_state`: Change the call of the analysis routine for `PDAFlocalomi_` to `PDAF3_`. In addition move the argument `prepoststep_pdaf` to the correct position |
| | 79 | 1. 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_global` which makes implementing the additional routine `localize_covar_pdafomi` obsolete) |
| | 80 | 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:https://pdaf.awi.de/trac/wiki/PDAFlocal_overview implementation instructions to for implementing the state location with PDAFlocal]. |
| | 81 | 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. |
