= Overview of the Analysis Step of Ensemble Filters =

{{{
#!html
<div class="wiki-toc">
<h4>Implementation Guide - Analysis Step</h4>
<ol><li><a href="ImplementationofAnalysisStep_PDAF3">Main page: Implementing the analysis step<a></li>
<ol>
<li><b>Ensemble filters</b></li>
<ol>
<li>General overview for ensemble filter</li>
<li><a href="ImplementAnalysisPDAF3Universal">Universal interface </a></li>
<li><a href="ImplementAnalysisPDAF3UniversalLocal">Universal interface using g2l/l2g_state</a></li>
<li><a href="ImplementanalysisPDAF3Global">Interface specific for global filters</a></li>
</ol>
<li><b>3D-Var methods</b></li>
<ol>
<li> <a href="Implement3DVarAnalysisOverviewPDAF3"> General overview for 3D-Var methods</a></li>
<li><a href="Implement3DVarAnalysisPDAF3Universal">Universal interface for 3D-Var</a></li>
<li><a href="Implement3DVarAnalysisPDAF3_3DVar">Implementation for parameterized 3D-Var</a></li>
<li><a href="Implement3DVarAnalysisPDAF3_3DEnVar">Implementation for 3D Ensemble Var</a></li>
<li><a href="Implement3DVarAnalysisPDAF3_Hyb3DVar">Implementation for Hybrid 3D-Var</a></li>
</ol>
<li><a href="nondiagonal_observation_error_covariance_matrices_PDAF3">Using nondiagonal R-matrices</a></li>
<li><a href="PDAF_OMI_Overview_PDAF3">PDAF-OMI Overview</a></li>
</ol>
</div>
}}}

For the analysis step of ensemble filters several routines need to be implemented. We provide a conceptional overview here. The detailed interfaces are then described on the pages for the difference interfaces.

Figure 1 gives an overview of the different routines one needs to provide to the analysis step of an ensemble filter. The actual routines depend on the chosen filter method. The routines are organized in three groups:

[[Image(//pics/Analysis_EnFs_web_PDAF3.png)]]
[[BR]]'''Figure 1:''' Required routines for the analysis step of ensemble filters. There are three groups of routines: The interface to the model (blue), the observation module (red), and state localization in case of domain-localized filters like LETKF/LESTKF/LNETF (purple). Without [wiki:PDAFlocal_overview PDAFlocal] there are two additional routines in the localization module.



== Model Interface ==

The model Interface consists of the routines `collect_state_pdaf` and `distribute_state_pdaf`. These routine perform the conversion between model fields and state vector. The routines have been discussed in the context of the [ModifyModelforEnsembleIntegration modification of the model for the ensemble integration]. These routines are only used in the online assimilation mode.

== OMI Observation Modules ==

The observation modules perform all observation-related operations. There is one observation module per observation type. The call-back routines are collected in the file `callback_obs_pdafomi.F90`. Each of these routines then calls a subroutine in the observation model specific to the observation type. 

In `callback_obs_pdafomi.F90` there are the routines:
  * `init_dim_obs_pdafomi`:[[BR]] For each observation type that is assimilated, this routine calls a routine form the observation modules that reads the observations and initializes observation values, coordinates, and errors. In addition, indices are specified that link the state vector to the observations. These are used in the observation operator.
  * `obs_op_pdafomi`:[[BR]] For each observation type, there is one routine providing the observation operator. For this, PDAF-OMI provides different observation operators as subroutines.
  * `init_dim_obs_l_pdafomi`:[[BR]] This is only used for the domain-localized filters. It calls the observation modules to initialize the local observations of each observation type. With PDAF-OMI this is mainly a single subroutine call, while PDAF-OMI does the actual initialization.

== Localization module ==

These routines are only required for the domain-localized ensemble filters. They handle the initialization of the state vector for a local analysis. These routines are
  * `init_n_domain`: This routine sets the number of local analysis domains
  * `init_dim_l`: This routine determines the state vector size for the local analysis domain and initializes the index information to fill a local state vector

In the special case, that the implementation does not use the recommend functionality of `PDAF3_assimilate` but `PDAF3_assimilate_local` instead, there are two additional routines:
 * `g2l_state_pdaf`: This routine initializes a local state vector from the global state vector
 * `l2g_state_pdaf`: This routine initializes elements of the global analysis state vector from a local state vector.
See the page on [wiki:ImplementAnalysisPDAF3UniversalLocal Implementation of the analysis using the universal interface without PDAFlocal] for more information.

For the covariance localization in the LEnKF and EnsRF/EAKF filters, there is the routine [wiki:PDAFomi_set_localize_covar], which is called in the observation-specific `init_dim_obs` routine of each observation module.

== Code examples in tutorial ==

The implementation of the ensemble filters is demonstrated in the tutorial codes in the PDAF package in the sub-directories of
{{{
   tutorial/
}}}
The implementations are described in detail in the [PdafTutorial PDAF tutorial slide sets].

The template files in 
{{{
  templates/
}}}
provide the requires files without functionality. They contain instructions on what needs to be implemented and can help in the implementation steps.


== Documention of the required implementations ==

There are three different routines that call the filter analysis step:
 * [wiki:ImplementAnalysisPDAF3Universal Implementation of the analysis using the universal interface]
 * [wiki:ImplementAnalysisPDAF3UniversalLocal Implementation of the analysis using the universal interface without PDAFlocal]
 * [wiki:ImplementanalysisPDAF3Global Implementation for the analysis specific for global filters]