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.

Generally there is only one routine that can execute all filter method:

Universal Routine for all filters	PDAF3_assimilate

This routine can be used for both the fully parallel and flexible parallization variants.

To enable an easier transition for existing PDAF2 implementations of the flexible parallelization mode to PDAF3, there is also the corresponding routine

Universal Routine for flexible parallel (backward compatibility)	PDAF3_put_state

The universal routines include in their interface 3 routines that are only used for local filters. For the particualr case, that one only uses global filters or the LEnKF one can use oe of the routines

Filter	fully parallel & flexible parallel	flexible parallel (backward-compatibility)
global filters LEnKF	PDAF3_assimilate_global	PDAF3_put_state_global

To enable an easier transition for existing PDAF2 implementations using the LEnKF to PDAF3, there is also the corresponding routine

Specific LEnKF routine (backward compatibility)	PDAF3_assimilate_lenkf

There is analogously the routine PDAF3_put_state_lenkf. However, using the new routine PDAFomi_set_localize_covar in init_dim_obs_pdafomi in each observation module one can switch to using the new universal routine.

Notes:

• The routines PDAF3_put_state 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. 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 select PDAF3_assimilate_global for global filters (PDAF_localfilter()=0).

For non-diagonal R matrix

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

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_lestkf	PDAF3_put_state_hyb3dvar_lestkf

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 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_.
2. 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.
3. 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.
4. 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)
5. 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.
6. 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.