| 7 | | PDAF provides an internal interface that makes it easy to add another assimilation method. Here we describe the implementation strategy and internal structure of PDAF valid for version 2.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]. |
| 8 | | |
| 9 | | The internal structure of PDAF is organized into a generic part providing the infrastructure to perform ensemble forecasts and filter analysis steps. This generic part is independent of the particular filter algorithm and only distinguishes between ensemble based filters (all filters except SEEK) and mode based filters (currently only SEEK, which integrates r modes plus one central model state). The specific routines for a DA method are called through an internal interface. |
| 10 | | |
| 11 | | In PDAF, each DA algorithm consists of 3 mandatory routines plus 2 optional routines. All routines are described below. They are called through the internal interface of PDAF, except for the "PDAF_assimilate" or "PDAF_put_state" routine ('PDAF_assimilate_X' or `PDAF_put_state_X` where X is the name of the selected DA method), which is directly called in the model code. |
| | 7 | 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]. |
| | 8 | |
| | 9 | The internal structure of PDAF is organized into a generic part providing the infrastructure to perform ensemble forecasts and the actual analysis step of the DA method. This generic part is independent of the particular filter algorithm. The specific routines for a DA method are called through the internal interface. |
| | 10 | |
| | 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. |
| 15 | | Before explaining the method-specific routines and the calling interface of each routine, 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). Shown are only the routines that are relevant for the implementation of a new filter method grouped by type. To add a filter algorithm, new method-specific routines (right column of Fig. 1) need to be implemented. These routines are registered in PDAF by modifying the internal interface routines in the middle column of Fig. 1. |
| 16 | | |
| 17 | | [[Image(//pics/internal_interface_omi.png)]] |
| 18 | | [[BR]]'''Figure 1:''' Structure of the internal interface of PDAF. There are 6 interface routines (middle column) that connect the generic part with filter-specific routines. For each filter there are 5 filter-specific routines (right column). The three routines marked in blue are called inside the model code, while the routines marked in yellow are internal routines of PDAF. For PDAF-OMI there are seprate routines for local filters (PDAFomi_assimilate_local) and global filters (PDAFomi_assimilate_global). |
| | 15 | 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). |
| | 16 | |
| | 17 | 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. |
| | 18 | |
| | 19 | 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. |
| | 20 | |
| | 21 | 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. |
| | 22 | |
| | 23 | [[Image(//pics/internal_interface_PDAF3.png)]] |
| | 24 | [[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. |
| 22 | | === Calls by `PDAF_init` === |
| 23 | | |
| 24 | | The routine `PDAF_init` calls |
| 25 | | || `PDAF_init_filters` || Interface routine to `PDAF_X_init`.[[BR]] `PDAF_X_init` performs the filter-specific initialization of parameters and calls the user-supplied routine that initializes the initial ensemble of model states. || |
| 26 | | || `PDAF_alloc_filters` || Interface routine to `PDAF_X_alloc`.[[BR]] `PDAF_X_alloc` allocates the filter-specific arrays. || |
| 27 | | || `PDAF_options_filters` || interface routine to `PDAF_X_options`.[[BR]] `PDAF_X_options` is an optional routine. Its purpose is to display an overview of available options for the filter algorithm. || |
| 28 | | |
| 29 | | When `PDAF_init` is called, the DA method is chosen by its ID number. Internally to PDAF, each DA method is identified by a string that is defined in `PDAF_init_filters`. The interface routines have a very simple structure. In general, they select the method-specific routine based on the string identifying the filters. When a DA method is added, a line for the corresponding method-specific routine has to be inserted to each of the interface routines. One can also remove a DA method from PDAF by deleting the corresponding lines form the internal interface routines. |
| 30 | | |
| 31 | | See the [https://pdaf.awi.de/trac/wiki/AddFilterAlgorithm#Filter-specificroutines section on filter-specific routines] for a detailed description. |
| 32 | | |
| 33 | | === Calls by `PDAF_print_info` === |
| 34 | | |
| 35 | | The routine `PDAF_print_info` only includes the interface to `PDAF_X_memtime` |
| 36 | | * `PDAF_X_memtime` displays information on the run time of the different parts of the assimilation process as well as information on the amount of allocated memory. This functionality is optional. See the [https://pdaf.awi.de/trac/wiki/AddFilterAlgorithm#Filter-specificroutines section on filter-specific routines] for a detailed description. |
| | 28 | === Internal interface routines === |
| | 29 | |
| | 30 | The purpose of the internal interface routines is as follows |
| | 31 | ||= Interface routine =||= called specific routine =||= Description =|| |
| | 32 | || `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. || |
| | 33 | || `PDAF_alloc_filters` || `PDAF_X_alloc` || Allocate the filter-specific arrays. || |
| | 34 | || `PDAF_options_filters` || `PDAF_X_options` || Display an overview of available options for the filter algorithm. || |
| | 35 | || `PDAF_set_iparam_filters` || `PDAF_X_set_iparam` || Set integer parameter || |
| | 36 | || `PDAF_set_rparam_filters` || `PDAF_X_set_rparam` || Set real (floating point) parameter || |
| | 37 | || `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. || |
| | 38 | || `PDAF_configinfo_filters` || `PDAF_x_config` || Display the current configuration of the DA method || |
| | 39 | |
| | 40 | 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. |
| | 41 | |
| | 42 | || When a DA method is added, a line for the corresponding method-specific routine has to be inserted to each of the interface routines. One can also remove a DA method from PDAF by deleting the corresponding lines form the internal interface routines. || |
| | 43 | |
| | 44 | == Modules of a DA method == |
| | 45 | |
| 43 | | [[Image(//pics/analysis_call_structure.png)]] |
| 44 | | [[BR]]'''Figure 2:''' Internal call structure for the analysis step. The generic routine (here `PDAFomi_assimilate_local` as example) calls the method-specific routine. Here `PDAF_assimilate_X` is the routine that controls the ensemble run in case of the fully-parallel implementation. The routine `PDAF_put_state_X` is used for both the fully-parallel and flexible parallelization variants. For the flexible parallelization one uses `PDAFomi_put_state_local` which directly calls `PDAF_put_state_X`, while for the fully parallel variant this routine is called by `PDAF_assimilate_X`. `PDAF_put_state_X` controls the ensemble for the case that multiple ensmeble states are propagated by a single model task and collects the ensemble from the ensemble tasks before the assimilate update and distributes the ensemble to the model tasks afterwards. The actual main routine for the DA method is `PDAF_X_update` which is called by `PDAF_put_state_X`. The routines on the right without 'omi' in their name are those with the full interface so that they are usable without OMI. |
| | 52 | [[Image(//pics/analysis_call_structure_PDAF3.png)]] |
| | 53 | [[BR]]'''Figure 2:''' Internal call structure for the analysis step. The universal interface routines `PDAF3_assimilate` and `PDAF3_Assim_offline` call a corresponding specific routine of the DA method. These specific routines are `PDAF_assimilate_X` and `PDAF_assim_offline_X` which are members of the module `PDAFassimilate_X`. `PDAF_assimilate_X` calls `PDAF_put_state_X`. These two routines together control the online coupled mode, while `PDAF_assim_offline_X` controls the offline coupled mode. The actual analysis update is performed by the routines, `PDAFX_update` and `PDAFX_analysis`, each in their own module. |
| | 54 | |
| | 55 | The universal routine `PDAF3_assimilatel` as example) calls the method-specific routine. Here `PDAF_assimilate_X` is the routine that controls the ensemble run in case of the fully-parallel implementation. The routine `PDAF_put_state_X` is used for both the fully-parallel and flexible parallelization variants. For the flexible parallelization one uses `PDAFomi_put_state_local` which directly calls `PDAF_put_state_X`, while for the fully parallel variant this routine is called by `PDAF_assimilate_X`. `PDAF_put_state_X` controls the ensemble for the case that multiple ensmeble states are propagated by a single model task and collects the ensemble from the ensemble tasks before the assimilate update and distributes the ensemble to the model tasks afterwards. The actual main routine for the DA method is `PDAF_X_update` which is called by `PDAF_put_state_X`. The routines on the right without 'omi' in their name are those with the full interface so that they are usable without OMI. |
