= The PDAF3 Interface  =


[[PageOutline(2-3,Contents of this page)]]

== 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 [[BR]]for all filters =|| [wiki: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 [[BR]]for flexible parallel[[BR]](backward compatibility) =|| [wiki: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 &[[BR]]flexible parallel** =||= **flexible parallel[[BR]](backward-compatibility)** =||
||= global filters[[BR]]LEnKF =|| [wiki:PDAF3_assimilate_global] || [wiki: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[[BR]](backward compatibility) =|| [wiki:PDAF3_assimilate_lenkf] ||
There is analogously the routine [wiki:PDAF3_put_state_lenkf]. However, using the new routine [wiki: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 [wiki:ExternalModelLoop instructions for implementing the flexible parallelization variant] for the updated instructions.
 * One can let PDAF select which of the routines to call. The function [wiki: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 [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:
||= **filter** =||= **fully parallel &[[BR]]flexible parallel** =||= **flexible parallel[[BR]](backward-compatibility)** =||
||= LESTKF[[BR]]LETKF[[BR]] LSEIK[[BR]] =|| [wiki:PDAF3_assimilate_local_nondiagR] ||[wiki:PDAF3_put_state_local_nondiagR] ||
||= LNETF =|| [wiki:PDAF3_assimilate_lnetf_nondiagR] || [wiki:PDAF3_put_state_lnetf_nondiagR] ||
||= LKNETF =|| [wiki:PDAF3_assimilate_lknetf_nondiagR] || [wiki:PDAF3_assimilate_lnetf_nondiagR] ||
||= ESTKF[[BR]]ETKF[[BR]] SEIK[[BR]] =|| [wiki:PDAF3_assimilate_global_nondiagR] ||[wiki:PDAF3_put_state_global_nondiagR] ||
||= NETF[[BR]]PF[[BR]] =|| [wiki:PDAF3_assimilate_nonlin_nondiagR] || [wiki:PDAF3_put_state_nonlin_nondiagR] ||
||= EnKF[[BR]]LEnKF =|| [wiki:PDAF3_assimilate_enkf_nondiagR] || [wiki: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 &[[BR]]flexible parallel** =||= **flexible parallel[[BR]](backward-compatibility)** =||
||= 3DVar =|| [wiki:PDAF3_assimilate_3dvar] || [wiki:PDAF3_put_state_3dvar] || 
||= En3DVar with ESTKF=|| [wiki:PDAF3_assimilate_en3dvar_estkf] || [wiki:PDAF3_put_state_en3dvar_estkf] || 
||= Hyb3DVar with ESTKF =|| [wiki:PDAF3_assimilate_hyb3dvar_estkf] || [wiki:PDAF3_put_state_hyb3dvar_estkf] || 
||= En3DVar with LESTKF=|| [wiki:PDAF3_assimilate_en3dvar_lestkf] || [wiki:PDAF3_put_state_en3dvar_lestkf] || 
||= Hyb3DVar with ESTKF =|| [wiki:PDAF3_assimilate_hyb3dvar_lestkf] || [wiki:PDAF3_put_state_hyb3dvar_lestkf] || 


**for non-diagonal R matrix**

See [wiki:OMI_nondiagonal_observation_error_covariance_matrices] for information on using non-diagonal **R**-matrices with OMI.

||= **Method** =||= **fully parallel &[[BR]]flexible parallel** =||= **flexible parallel[[BR]](backward-compatibility)** =||
||= 3DVar =|| [wiki:PDAF3_assimilate_3dvar_nondiagR] || [wiki:PDAF3_put_state_3dvar_nondiagR] || 
||= En3DVar with LESKTF=|| [wiki:PDAF3_assimilate_en3dvar_lestkf_nondiagR] || [wiki:PDAF3_put_state_en3dvar_lestkf_nondiagR] || 
||= En3DVar with ESTKF =|| [wiki:PDAF3_assimilate_en3dvar_estkf_nondiagR] || [wiki:PDAF3_put_state_en3dvar_estkf_nondiagR] || 
||= Hyb3DVar with LESTKF=|| [wiki:PDAF3_assimilate_hyb3dvar_lestkf_nondiagR] || [wiki:PDAF3_put_state_hyb3dvar_lestkf_nondiagR] || 
||= Hyb3DVar with ESTKF=|| [wiki:PDAF3_assimilate_hyb3dvar_estkf_nondiagR] || [wiki: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_`.
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 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.
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` (or `PDAF3_assimilate_global` which makes implementing the additional routine `localize_covar_pdafomi` obsolete)
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].
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.