The PDAF3 Interface

Overview

The PDAF3 interface was introduced with PDAF V3.0 to provide a consistent interface for all DA methods. The PDAF3 interfaces utilizes the functionality of PDAF-OMI (Obervation Module Interface) and PDAFlocal for easy state vector localization.

Routines to perform the analysis step

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.

Here we provide an overview of the routine names and the links to the interface descriptions.

Ensemble filters

For diagonal R matrix

For the more typical assuming that the observation error covariance matrix R is diagonal there are only two routines.

Depending on the fully parallel are flexible implementation choose the routine

Filter	fully parallel & flexible parallel	flexible parallel (backward-compatibility)
domain local filters ENSRF/EAKF	PDAF3_assimilate_local	PDAF3_put_state_local
global filters LEnKF	PDAF3_assimilate_global	PDAF3_put_state_global

Notes:

• The routines PDAF3_put_state_local and PDAF3_put_state_global exist for backward-compatibility of the flexible parallelization variant. Starting with PDAF V3.0, we recommend to use PDAF3_assimilate_local and PDAF3_assimilate_global. See the instructions for implementing the flexible parallelization variant for the updated instructions.
• One can let PDAF select which of the routines to call. The function PDAF_localfilter allows to switch between the routines as is shown in the tutorial implementations and templates.

For non-diagonal R matrix

If 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.

See the 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:

filter	fully parallel & flexible parallel	flexible parallel (backward-compatibility)
LESTKF LETKF LSEIK	PDAF3_assimilate_local_nondiagR	PDAF3_put_state_local_nondiagR
LNETF	PDAF3_assimilate_lnetf_nondiagR	PDAF3_put_state_lnetf_nondiagR
LKNETF	PDAF3_assimilate_lknetf_nondiagR	PDAF3_assimilate_lnetf_nondiagR
ESTKF ETKF SEIK	PDAF3_assimilate_global_nondiagR	PDAF3_put_state_global_nondiagR
NETF PF	PDAF3_assimilate_nonlin_nondiagR	PDAF3_put_state_nonlin_nondiagR
EnKF LEnKF	PDAF3_assimilate_enkf_nondiagR	PDAF3_put_state_enkf_nondiagR

Note:

• There is no routine for the ENSRF/EAKF for nondiagonal R, because these filters assume that a diagonal R matrix exists.

3D-Var

Only En3DVar and hybrid 3D-Var use a local filter. The routines are the following.

for diagonal R matrix

Method	fully parallel & flexible parallel	flexible parallel (backward-compatibility)
3DVar	PDAF3_assimilate_3dvar	PDAF3_put_state_3dvar
En3DVar with ESTKF	PDAF3_assimilate_en3dvar_estkf	PDAF3_put_state_en3dvar_estkf
Hyb3DVar with ESTKF	PDAF3_assimilate_hyb3dvar_estkf	PDAF3_put_state_hyb3dvar_estkf
En3DVar with LESTKF	PDAF3_assimilate_en3dvar_lestkf	PDAF3_put_state_en3dvar_lestkf
Hyb3DVar with ESTKF	PDAF3_assimilate_hyb3dvar_estkf	PDAF3_put_state_hyb3dvar_estkf

for non-diagonal R matrix

See OMI_nondiagonal_observation_error_covariance_matrices for information on using non-diagonal R-matrices with OMI.

Method	fully parallel & flexible parallel	flexible parallel (backward-compatibility)
3DVar	PDAF3_assimilate_3dvar_nondiagR	PDAF3_put_state_3dvar_nondiagR
En3DVar with LESKTF	PDAF3_assimilate_en3dvar_lestkf_nondiagR	PDAF3_put_state_en3dvar_lestkf_nondiagR
En3DVar with ESTKF	PDAF3_assimilate_en3dvar_estkf_nondiagR	PDAF3_put_state_en3dvar_estkf_nondiagR
Hyb3DVar with LESTKF	PDAF3_assimilate_hyb3dvar_lestkf_nondiagR	PDAF3_put_state_hyb3dvar_lestkf_nondiagR
Hyb3DVar with ESTKF	PDAF3_assimilate_hyb3dvar_estkf_nondiagR	PDAF3_put_state_hyb3dvar_estkf_nondiagR

Porting to PDAF3

If you like to port your existing code to using PDAF3, the required changes depend on which interface calls you used bfore:

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_.
2. 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
3. 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)
4. 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 implementation instructions to for implementing the state location with PDAFlocal.
5. 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.