Changes between Version 50 and Version 51 of AddFilterAlgorithm


Ignore:
Timestamp:
Nov 10, 2024, 6:28:37 PM (13 days ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • AddFilterAlgorithm

    v50 v51  
    1616[[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).
    1717
    18 The separate routines are the following: The routine `PDAF_init` calls
     18The separate routines are the following:
     19
     20=== Calls by `PDAF_init` ===
     21
     22The routine `PDAF_init` calls
    1923|| `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. ||
    2024|| `PDAF_alloc_filters` || Interface routine to `PDAF_X_alloc`.[[BR]] `PDAF_X_alloc` allocates the filter-specific arrays. ||
    … …  
    2327When `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.
    2428
     29See the [https://pdaf.awi.de/trac/wiki/AddFilterAlgorithm#Filter-specificroutines section on filter-specific routines] for a detailed description.
     30
     31=== Calls by `PDAF_print_info` ===
     32
    2533The routine `PDAF_print_info` only includes the interface to `PDAF_X_memtime`
    26  * `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.
     34 * `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.
     35
     36
     37=== Calls by `PDAFomi_assimilate_local` or `PDAFomi_assimilate_global` ===
    2738
    2839The routine `PDAFomi_assimilate_local`, for local ensemble filters and smoothers, or analogously the other available `PDAF_omi_assimilate` routines, like for global ensemble filters and smoothers (`PDAFomi_assimilate_global`) or the different variants of 3D-Var (`PDAFomi_assimilate_*3dvar*`) are called directly from the model code. These are used for the fully-parallel implementation variant. For the flexible-parallelization variant the analogous routines `PDAFomi_put_state_*` are provided. These are generic routines which internally call the method-specific routine (PDAF_assimilate_X or PDAF_put_state_X) according to the chosen filter which then calls the actual update routine (PDAF_X_update). This call structure is explained in Figure 2.
    … …  
    3041[[Image(//pics/analysis_call_structure.png)]]
    3142[[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.
     43
     44See the [https://pdaf.awi.de/trac/wiki/AddFilterAlgorithm#Filter-specificroutines section on filter-specific routines] for a detailed description for `PDAF_assimilate_X` and `PDAF_put_state_X`.
     45
    3246
    3347== Internal dimensions ==
    … …  
    167181
    168182
    169 
    170183=== `PDAF_assimilate_X` / `PDAF_put_state_X` ===
    171184
    172 These routines are called by `PDAFomi_assimilate_*` or `PDAFomi_put_state_*`. They are directly inserted into the model code, if the online mode of PDAF is used. The text on the [ImplementationofAnalysisStep implementation of the analysis step] in the Implementation Guide explains the interface for the algorithms that are included in the PDAF package. As described before `PDAF_assimilate_X` called `PDAF_put_state_X` which then calls the actual DA method. Here `PDAF_assimilate_X` mainly passes its arguments over to `PDAF_put_state_X`.
     185These routines are called by `PDAFomi_assimilate_*` or `PDAFomi_put_state_*`, which are directly inserted into the model code, if the online mode of PDAF is used. The text on the [ImplementationofAnalysisStep implementation of the analysis step] in the Implementation Guide explains the interface for the algorithms that are included in the PDAF package. `PDAFomi_assimilate_*` are interface routines for PDAF-OMI and call either `PDAF_assimilate_X`. (Likewise routines `PDAFomi_put_state_*` call `PDAF_put_state_X`.
     186As described before `PDAF_assimilate_X` calls `PDAF_put_state_X` which then calls the actual update routine of the DA method. Here `PDAF_assimilate_X` mainly passes its arguments over to `PDAF_put_state_X`, but it also controls the ensemble run.
    173187
    174188Apart from the usual integer status flag, the interface of the routines contains the names of the user-supplied routines that are required for the analysis step. Usually, the minimum set of routines are:
    … …  
    182196 * `U_next_observation`: The routine that specified the number of time steps until the next DA analysis update.
    183197
    184 Further routines can be added and depend on the requirements of the filter algorithm. For example the (L)ETKF and (L)ESTKF uses a routine `U_prodRinvA` which has to multiply some temporary matrix of the filter method with the inverse observation error covariance matrix.
     198Further routines can be added and depend on the requirements of the filter algorithm. For example, the (L)ETKF and (L)ESTKF uses a routine `U_prodRinvA` which has to multiply some temporary matrix of the filter method with the inverse observation error covariance matrix.
    185199
    186200When one plans to implement a new filter we recommend to check whether the filter is compatible with the existing local or global filters, i.e. using the same call-back routines. In this case, support for the new filter can be added into one of the existing routines (PDAFomi_assimilate_global/PDAFomi_assimilate_local or likewise PDAFomi_put_state_global/PDAFomi_put_state_local).