Changes between Version 3 and Version 4 of AddFilterAlgorithm_PDAF3

Timestamp:

Jun 5, 2025, 9:54:11 AM (6 weeks ago)

Author:

lnerger

Comment:

--

AddFilterAlgorithm_PDAF3

@@ -3 +3 @@
 [[PageOutline(2-3,Contents of this page)]]
 
-|| This page describes the implementation for PDAF2. It will be updated for PDAF3. ||
+|| This page describes the implementation for PDAF3. The previous implementation for PDAF2 is described on the [wiki:AddFilterAlgorithm_PDAF231 Page on adding a DA Method to PDAF 2] ||
 
 PDAF provides an internal interface to add a data assimilation (DA) method to PDAF. Here we describe the implementation strategy and internal structure of PDAF valid for version 3.0 and later. In this text, we assume that the reader is already familiar with PDAF to the extend that it is known how PDAF is connected to a model as is described in the [ImplementationGuide Implementation Guide].
@@ -11 +11 @@
 In PDAF, each DA algorithm consists of 5 Fortran modules including different subroutines for configuring the DA method, for the handling of the ensemble forecasts, and for the analysis step. The modules and routines are described below. 
 
+We provide templates for the implementation of global and local ensemble filter in the sub-directores of `templates/analysis_step/`.
+
 == PDAF's Internal Interface ==
 
-Before explaining the method-specific routines, we provide an overview of the internal interface routines of PDAF. The structure of the internal interface of PDAF is depicted in Figure 1 (For the method-specific routines, 'X' is the name of the DA method). 
+Here, we first provide an overview of the internal interface routines of PDAF. The structure of the internal interface of PDAF is depicted in Figure 1 (For the method-specific routines, 'X' is the name of the DA method). 
 
 The left column in Fig. 1 shows the generic PDAF routines, which are called from the user code. Here, `PDAF_init` calls 5 interface routines to perform the specific initialization of the DA method. The other generic routines are more focused and call only one interface routine each.
 
-The internal interface routines are depicted in the middle column of Fig. 1. All these routines are collected in the module `PDAF_utils_filters` in the file `PDAF_utils_filters.F90`. For each of the interface routines there is a specific routine of the DA method. These specific routines are collected in the module `PDAF_X` in the file `PDAF_X.F90`. The interface routines perform the initialization of a DA method, setting parameters or printing information about the configuration or the available options.
-
-The assimilation routines, here the universal routines `PDAF3_assim_offline` and `PDAF3_assimilate` directly call the specific assimilation routine of the DA method. These are stored the module in `PDAF_assimilate_X.F90.
-
-[[Image(//pics/internal_interface_PDAF3.png)]]
+The internal interface routines allowthe user to call the generic routines, which are then mapped to a specific routine of the DA method. The internal interface routines are depicted in the middle column of Fig. 1. All these routines are collected in the module `PDAF_utils_filters` in the file `PDAF_utils_filters.F90`. For each interface routine there is a specific routine of the DA method shown in the right-most column. These specific routines are collected in the module `PDAF_X` in the file `PDAF_X.F90`. The interface routines perform the initialization of a DA method, setting parameters or printing information about the configuration or the available options. 
+
+The assimilation routines, here the universal routines `PDAF3_assim_offline` and `PDAF3_assimilate`, directly call the specific assimilation routine of the DA method. These are stored the module in `PDAF_assimilate_X.F90.
+
+[[Image(//pics/internal_interface_PDAF3_.png)]]
 [[BR]]'''Figure 1:''' Structure of the internal interface of PDAF. There are 7 internal interface routines (middle column) that connect the generic part with filter-specific routines. All these interface routines are collected in the module PDAF_utils filters. Each of the internal interface routines call one routine that is specific to the DA method. These routines are collected in the module PDAF_X, where 'X' would be the name of the DA method. The assimilation routines for the online and offline coupled modes are collected in the module PDAF_assimilate_X.
 
@@ -29 +31 @@
 
 The purpose of the internal interface routines is as follows
-||= Interface routine =||= called specific routine =||= Description =||
+||= Interface routine [[BR]]in `PDAF_utils_filters` =||= called specific routine [[BR]]in `PDAF_X` =||= Description =||
 || `PDAF_init_filters` ||  `PDAF_X_init` || Perform the filter-specific initialization of parameters and calls the user-supplied routine that initializes the initial ensemble of model states. ||
 || `PDAF_alloc_filters` || `PDAF_X_alloc` || Allocate the filter-specific arrays. ||
 || `PDAF_options_filters` || `PDAF_X_options` || Display an overview of available options for the filter algorithm. ||
-|| `PDAF_set_iparam_filters` || `PDAF_X_set_iparam` || Set integer parameter ||
-|| `PDAF_set_rparam_filters` || `PDAF_X_set_rparam` || Set real (floating point) parameter ||
+|| `PDAF_set_iparam_filters` || `PDAF_X_set_iparam` || Set integer parameter for the DA method ||
+|| `PDAF_set_rparam_filters` || `PDAF_X_set_rparam` || Set real (floating point) parameter for the DA method ||
 || `PDAF_print_info_filters` || `PDAF_x_memtime` || Display information on the run time of the different parts of the DA method as well as information on the amount of allocated memory.  ||
 || `PDAF_configinfo_filters` || `PDAF_x_config` || Display the current configuration of the DA method ||
@@ -40 +42 @@
 When `PDAF_init` is called, the DA method is chosen by its ID number or its name parameter (see [wiki:AvailableOptionsforInitPDAF page on specific options of DA method]). Internally to PDAF, each DA method is identified by a string that is defined in the module `PDAF_DA` in `PDAF_da.F90`. The interface routines have a very simple structure. In general, they select the method-specific routine based on the string identifying the filters. 
 
+Collecting all interface routines in the file `PDAF_utils_filters.F90` yields a single place in which additions for the configuration functionality for a new DA method need to be done.
+
 || When adding a DA method, a line for the corresponding method-specific routine has to be inserted to each of the interface routines in `PDAF_utils_filters.F90`. Further, one has to add to `PDAF_da.F90` a line for the DA method declaring its name in the form `PDAF_DA_X` and a correspondig index. ||
 
@@ -48 +52 @@
 Each DA method in PDAF consist of 5 standard modules. These are
 
-
+|| `PDAF_X` || This module declares variables specific to the DA method, e.g. the variable for the ensemble inflation. Further, it contains the different subroutines called by the routines in `PDAF_utils_filters` for the configuration of the DA method. ||
+|| `PDAFassimilate_X` || This module contains the assimilation interface routines. Usually these are `PDAF_assimilate_X` and `PDAF_assim_offline_X`. ||
+|| `PDAFput_state_X` || This module contains the routine `PDAF_put_state_X`. This routine controls the ensmeble integrations for the `flexible` parallelization variant. It exists as a spearate routine for backward-compatibility with PDAF2. 
+|| `PDAF_X_update` || This module contains the main routine `PDAFX_update` for the analysis update. This controls the actual update, e.g. by performing a local analysis loop for domain-localized filter methods. ||
+|| `PDAF_X_analysis` || This module contains the routine that computes and applies the actual ensemble analysis increment. ||
+
+Note on naming modules and subroutines: Fortran does not allow that the name of a module is idential to the name of a subroutine contained in the module. We we handle this issue with using or omitting understores, e.g. the module `PDAFassimilate_X` contains the subroutine `PDAF_assimilate_X`.