= Implementing the analysis step =

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


{{{
#!html
<div class="wiki-toc">
<h4>Implementation Guide - Analysis Step</h4>
<ol><li>Main page: Implementing the analysis step</li>
<ol>
<li><b>Ensemble filters</b></li>
<ol>
<li> <a href="ImplementFilterAnalysisOverviewPDAF3"> General overview for ensemble filters</a></li>
<li><a href="ImplementAnalysisPDAF3Universal">Universal interface </a></li>
<li><a href="ImplementAnalysisPDAF3UniversalLocal">Universal interface using g2l/l2g_state</a></li>
<li><a href="ImplementanalysisPDAF3Gloval">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>
</ol>
</div>
}}}


{{{
#!html
<div class="wiki-toc">
<b> This page can be reached from different<br>parts of the documentation:</b>
<p>Back to <b><a href="OfflineImplementationGuide">Offline Mode: Implementation Guide</a></b></p>
<p>Back to <b><a href="OnlineImplementationGuide_PDAF3">Online Mode: Implementation Guide</a></b></p>
<p>Back to <b><a href="PDAF_OMI_Overview_PDAF3">PDAF-OMI Guide</a></b></p>
</div>
}}}

The implementation of the analysis step requires that the user-supplied routines that are arguments in the call to the routine for the analysis step are implemented with full functionality. 

While different routines are used for the online and offline modes of PDAF, the implementation of the analysis is generally generic. As such we combine this here for both the online and offline modes.


== Ensemble filter methods ==

To get an overview of the required routines for the analysis step see:
 * [Implement3DVarAnalysisOverviewPDAF3 General overview of routines required to implement the analysis step for ensemble filters].


There are universal routines that call the filter analysis step for all ensemble filter methods.
 * [wiki:ImplementAnalysisPDAF3Universal Implementation of the analysis using the universal routines.]

For more specific cases, there are further routines
 * [wiki:ImplementAnalysisPDAF3UniversalLocal Implementation with user-provided routines for transfer between global and local state vectors (g2l_state_pdaf/l2g_state_pdaf) in local filters]
 * [wiki:ImplementanalysisPDAF3Global Implementation specific for global filters and LEnKF] 


== 3D-Var methods ==

To get an overview of the required routines for the analysis step of 3D-Var methods see:
 * [wiki:Implement3DVarAnalysisOverviewPDAF3 General overview of routines required to implement the analysis step for 3D-Var].

For the application of the 3D-Var methods there are universal routines for all methods:
 * [wiki:Implement3DVarAnalysisPDAF3Universal Implementation of the analysis using the universal routines.]

For more specific cases, there are further routines

 1. [wiki:Implement3DVarAnalysisPDAF3_3DVar Implementation of the analysis for 3D-Var with parameterized background covariance matrix]
 1. [wiki:Implement3DVarAnalysisPDAF3_3DEnVar Implementation of the analysis for 3D Ensemble Var ]
 1. [wiki:Implement3DVarAnalysisPDAF3_Hyb3DVar Implementation of the analysis for hybrid 3D-Var]


== Implementation variants before PDAF3 ==

=== Analysis step using PDAF-OMI without PDAFlocal ===

This variant refers to the `PDAFomi_` routines to call the analysis step.

Before releasing PDAF V3.0 with its now PDAF3-interface routines for the analysis step, using the PDAF Observation Module Interface (PDAF-OMI) was recommended. PDAFlocal was introduced with PDAF V2.3 in September 2024 as an add-on to PDAF-OMI for local filters. With PDAFlocal we simplified the localization of the state vector. Implementations done before the release of PDAF V2.3 likely use PDAF-OMI without PDAFlocal. This mean they call user-provided routines `g2l_state_pdaf` and `l2g_state_pdaf`.

|| For reference we provide the documentation on the  **[wiki:ImplementAnalysisLocal_untilPDAF221 implementation of the analysis step with PDAF-OMI not using PDAFlocal].** ||

=== Analysis step using PDAF-OMI and PDAFlocal ===

This variant refers to the `PDAFlocalomi_` routines to call the analysis step.

PDAFlocal was introduced with PDAF V2.3 in September 2024 as an add-on to PDAF-OMI for local filters. With PDAFlocal we simplified the implementation of localization of the state vector. 
without PDAFlocal. This mean they call user-procided routines `g2l_state_pdaf` and `l2g_state_pdaf`. Even so, the period between the introduction of PDAFlocal and the PDAF3 interface was short, there are possible implementations using PDAFlocal. The PDAF3 interface bases on both PDAF-OMI and PDAFlocal, so that it should be very easy to port a code to using the universal PDAF3 interface described above. See the [wiki:PortingToPDAF3 explanation for porting von PDAF2 to PDAF3].

|| For reference we provide the documentation on the  **[wiki:ImplementAnalysisLocal implementation of the analysis step with PDAF-OMI and PDAFlocal].** ||


=== Analysis step using PDAF's full interface ===

This variant refers to the `PDAF_` routines to call the analysis step.

The full interface omits the use of PDAF-OMI for the observation handling, and PDAFlocal for the simplified handling of localization. Using the full interface is an 'expert mode' because it requires to implement a larger number of call-back routines. Nonetheless, assimilation systems implemented before the introduction of PDAF-OMI with Version 1.16 in November 2020 might still use this approach.

|| For reference we provide the documentation on the  **[wiki:ImplementationofAnalysisStep_noOMI implementation of the analysis step without PDAF-OMI]**, which is still possible. ||


== Testing the full implementation ==

After the implementation of the user-supplied routines for the analysis step, the data assimilation system is fully implemented. Thus, one an now test its full functionality including the analysis step.