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. Using the PDAF3 interface is recommended for new implementations.

For 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 Porting to the PDAF3 interface.

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.

The different parts of this page are

• Analysis step with diagonal R matrix
• Analysis step with non-diagonal R matrix
• Porting to the PDAF3 interface

Analysis step with diagonal R matrix

Assuming that the observation error covariance matrix R is diagonal is the more common case. The assumption is that observation errors are uncorrelated. In this case, only the observation error variances need to be considered.

Ensemble filters and smoothers

For the more typical assuming that the observation error covariance matrix R is diagonal there is one universal routine for online-coupled programs and one for offline-coupled (file-based) programs:

	online coupled	offline coupled
Universal Routine for all filters	PDAF3_assimilate	PDAF3_put_state

For the online-coupled case, PDAF3_assimilate can be used for both the fully parallel and flexible parallization variants.

Routines for particular cases

To enable an easier transition for existing PDAF2 implementations of the flexible parallelization mode to the PDAF3interface, one can use the routine

Universal Routine for flexible parallel (backward compatibility)	PDAF3_put_state

The 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

	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

	fully parallel & flexible parallel	flexible parallel (backward-compatibility)
Specific LEnKF routine (backward compatibility)	PDAF3_assimilate_lenkf	PDAF3_put_state_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 'put_state' routines exist for backward-compatibility of the flexible parallelization variant. Starting with PDAF V3.0, we recommend to use PDAF3_assimilate also for the flexible parallelization variant. 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).

3D-Var

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

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

Method	online coupled	offline coupled
3D-Var (parameterized)	PDAF3_assimilate_3dvar	PDAF3_put_state_3dvar
En3D-Var with ESTKF or LESTKF	PDAF3_assimilate_en3dvar	PDAF3_put_state_en3dvar
hyb3D-Var with ESTKF or LESTKF	PDAF3_assimilate_3dvar_all	PDAF3_put_state_3dvar_all
Universal Routine (all 3D-Var methods)	PDAF3_assimilate_3dvar_all	PDAF3_put_state_3dvar_all

Note:

• For the online-coupled case, the PDAF3_assimilate_* routines can be used for both the fully parallel and flexible parallization variants.
• 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.
• 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.
• 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.
• 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.

Routines for particular cases

The 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

Method	online coupled	offline coupled
En3DVar with ESTKF	PDAF3_assimilate_en3dvar_estkf	PDAF3_put_state_en3dvar_estkf
Hyb3DVar with ESTKF	PDAF3_assimilate_hyb3dvar_estkf	PDAF3_put_state_hyb3dvar_estkf

Analysis step with non-diagonal R matrix

Ensemble filters

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

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 the PDAF3 interface

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

For ensemble filters:

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

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

For 3D-Vars:

1. 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'/
2. 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_.
3. 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_.
4. 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_.
5. If you used the hybrid 3D-Var or ensemble 3D-Var with PDAFomi_* routines: Follow the implementation instructions to for implementing the state localization with PDAFlocal. Afterwards change the the PDAFomi_* call to the PDAF3_* interface.
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 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.