Changes between Version 54 and Version 55 of AddFilterAlgorithm


Ignore:
Timestamp:
Dec 12, 2024, 3:34:00 AM (10 days ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • AddFilterAlgorithm

    v54 v55  
    5050|| `dim_p` || The size of the state vector (with parallelization the size of the local state vector for the current process) ||
    5151|| `dim_ens` || The overall size of the ensemble ||
    52 || `dim_ens_l` || If the ensemble integration is distributed over several ensemble tasks, this variable stores the size of the sub-ensemble handled by the current process. (`dim_ens_l` equals `dim_ens` if no parallelization or if only a single model task is used.) This variable is only used in the ensemble handling of PDAF, but not in the DA update. ||
    53 || `rank` || The maximum rank of the ensemble covariance matrix. In almost all cases, it is `dim_ens-1`. Used in error-subspace filters, (L)ESTKF and (L)SEIK||
     52|| `dim_ens_l` || If the ensemble integration is distributed over several ensemble tasks, this variable stores the size of the sub-ensemble handled by the current process. (`dim_ens_l` equals `dim_ens` if no parallelization or if only a single model task is used.) For the fully parallel implementation it is din_ens_l=1. Note that this variable is only used in the ensemble handling of PDAF, but not in the DA update. ||
     53|| `rank` ||The maximum rank of the ensemble covariance matrix. In almost all cases, it is `dim_ens-1`. Used in error-subspace filters, (L)ESTKF and (L)SEIK ||
    5454
    5555== Internal arrays ==
    … …  
    5858For the processes that computes the analysis (those with `filterpe=.true.`) the following arrays are defined:
    5959|| Array || Dimension || Comment ||
    60 ||`state`|| `dim_p`   || State vector. Used in all filters. ||
     60||`state`|| `dim_p`   || State vector. Used in all filters. Inside the filter code, it's usually called `state_p` ||
    6161||`eofV` || `dim_p` x `dim_ens` || Ensemble array. Used in all filters. Inside some filters the name is `ens_p` ||
    6262||`eofU` || `dim_ens-1` x `dim_ens-1` (SEEK, SEIK, ESTKF)[[BR]] `dim_ens` x `dim_ens` (ETKF) ||Eigenvalue matrix '''U''' from '''P'''='''VUV'''^T^ (SEEK, SEIK) or transform matrix '''A''' (ETKF, ESTKF). Not used in EnKF. In some routines the matrix is called `Uinv` to indicate the inverse ||
    … …  
    107107The routine has to perform the following operations:
    108108 * initialize the PDAF-internal parameter variables specific for the DA method from the provided values of `subtype`, `param_int`, and `param_real`.
    109  * set the logical flags `ensemblefilter` and `fixedbasis` have to be set.
     109 * set the logical flags `ensemblefilter` and `fixedbasis`.
    110110The existing implementations also include some screen output about the configuration.
    111111
    112112Please note:
    113113 * The routine should check, whether the provided value of `subtype` is a valid choice. If this is not the case, the error flag should be set to 2.
    114  * Only parameters from `param_int` and `param_real` up to the value `dim_pint` and `dim_preal` should be considered in the initialization. The array may be bigger, but the user defines which parameters are to be used be setting the values of `dim_pint` and `dim_preal`.
     114 * Only parameters from `param_int` and `param_real` up to the value `dim_pint` and `dim_preal`, respectively, should be considered in the initialization. The arrays may be bigger, but the user defines which parameters are to be used be setting the values of `dim_pint` and `dim_preal`.
    115115 * The error flag `outflag` is initially set to 0.
    116116 * The internal parameters are declared in the Fortran module `PDAF_mod_filter`. If a new filter algorithm requires additional parameters, their declaration should be added to the module. Alternatively, one can introduce a new module the holds the parameters specific to the new DA method.
    … …  
    119119=== `PDAF_X_alloc` ===
    120120
    121 The routine `PDAF_X_alloc` allocates arrays for the data assimilation, like the ensemble array and a state vector. The success of the allocation is checked.
     121The routine `PDAF_X_alloc` allocates arrays for the data assimilation. These are the arrays that are used in the forecasting and hence need to be persistently allocated, like the ensemble array and a state vector. The success of the allocation is checked.
    122122
    123123The interface is as follows:
    … …  
    148148The optional routine `PDAF_X_options` displays information on the available options for the filter algorithm.
    149149
    150 The rotine has no arguments. Thus the interface is as follows:
     150The routine has no arguments. Thus the interface is as follows:
    151151{{{
    152152  SUBROUTINE PDAF_X_options()
    … …  
    178178}}}
    179179
    180 The timing operation are implemented using the module `PDAF_timer`, which provides the function `PDAF_timeit`. Memory allocation is computed using `PDAF_memcount`, which is provided by the module `PDAF_memcounting`.
     180The timing operations are implemented using the module `PDAF_timer`, which provides the function `PDAF_timeit`. Memory allocation is computed using `PDAF_memcount`, which is provided by the module `PDAF_memcounting`.
    181181
    182182
    183183=== `PDAF_assimilate_X` / `PDAF_put_state_X` ===
    184184
    185 These 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`.
    186 As 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.
    187 
    188 Apart 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:
     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 together with PDAF-OMI. The description of 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 the `PDAF_assimilate_X` routines as described above. (Likewise the routines `PDAFomi_put_state_*` call `PDAF_put_state_X`.)
     186
     187As 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 by counting the number of time steps.
     188
     189Apart from the usual integer status flag, the interface of the routines contains the names of the user-supplied call-back 2routines that are required for the analysis step. Usually, the minimum set of routines are:
    189190 * `U_collect_state`: The routine that writes model fields into the state vector, i.e. a single column of the ensemble state array
    190191 * `U_init_dim_obs`: The routine that determines the size of the observation vector
    … …  
    196197 * `U_next_observation`: The routine that specified the number of time steps until the next DA analysis update.
    197198
    198 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.
    199 
    200 When 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).
    201 
    202 With regard to the operations, the routines `PDAF_put_state_X` prepare for the actual analysis step, that is called inside these routines as a separate routine `PDAF_X_update`. The operations implemented in `PDAF_put_state_X` are:
     199Further routines can be added and depend on the requirements of the filter algorithm. Common is a routine that involves the observation error covariance matrix. For example, the (L)ETKF and (L)ESTKF methods use the routine
     200 * `U_prodRinvA` which has to multiply some temporary matrix of the filter method with the inverse observation error covariance matrix.
     201
     202When one plans to implement a new filter, we recommend to check whether the filter is compatible with the existing local or global filters, in particular whether it uses the same call-back routines. In this case, the new filter can be added into the existing routines (either PDAFomi_assimilate_global/PDAFomi_put_state_global for a global DA method or likewise PDAFomi_assimilate_local/PDAFomi_put_state_local for a DA method using domain localization).
     203
     204The routine `PDAF_assimilate_X` and `PDAF_put_state_X` provide the actual infrastructure to manage the ensemble forecasting. Here `PDAF_assimilate_X` is used for the fully parallel setup and counts the time steps and finally calls `PDAF_put_state_X`.
     205
     206The routines `PDAF_put_state_X` prepare for the actual analysis step, that is called inside these routines as a separate routine `PDAF_X_update`. `PDAF_put_state_X` also performs the ensemble management for the flexible parallelization variant in which more than one ensemble state can be integrated by a model task.
     207The operations implemented in `PDAF_put_state_X` are:
    203208 * Write model fields back into the ensemble array (by calling `U_collect_state`)
    204209 * Increment the counter for the integrated ensemble members (named `counter` and provided by the module `PDAF_mod_filter`.
    205  * Check, if the ensemble integration is completed (in that case, it is `member = local_dim_ens + 1`). If not, exit the `PDAF_put_state_X`.
    206  * If the ensemble integration is completed, the following operations are required:
     210 * Check, if the ensemble integration is completed (in that case, it is `member = local_dim_ens + 1`). If not, exit `PDAF_put_state_X`.
     211 * When the ensemble integration is completed, the following operations are required:
    207212  * If more than one model task is used: Collect the sub-ensembles from all model tasks onto the processes that perform the analysis step. This operation is done by the subroutine `PDAF_gather_ens`.
    208213  * Call the routine that computes the analysis step for the chosen filter algorithm (typically named `PDAF_X_update`).
    209214  * Reset the control variables for the ensemble forecast (`initevol=1`, `member=1`, `step=step_obs+1`).
    210215
    211 In general, the PDAF_put_state routines of all ensemble-based filters have the same structure. For the implementation of a new filter we recommend to base on an existing routine, e.g. that of for the ETKF. Thus, one copies the routine to a new name. Then, one adapts the interface for the required user-supplied routines of the new DA method. In addition, the call of the routine `PDAF_X_update` holding the DA analysis update step has to be revised (name of the routine, required user-supplied routines).
    212 
    213 The routine `PDAF_assimilate_X` is mainy an interface routine to `PDAF_put_state_X`. It counts the time steps and calls `PDAF_put_state_X` when the forecast phase is complete. Thus, apart form adapting the name (`X`) and the interface specifying the call-back routines, there should be no need for changes.
     216In general, the `PDAF_put_state` routines of all ensemble-based filters have the same structure. For the implementation of a new filter we recommend to base on an existing routine, e.g. that of for the ETKF. Thus, one copies the routine to a new name. Then, one adapts the interface for the required user-supplied routines of the new DA method. In addition, the call of the routine `PDAF_X_update` holding the DA analysis update step has to be revised (name of the routine, required user-supplied routines).
     217
     218The routine `PDAF_assimilate_X` is mainy an interface routine to `PDAF_put_state_X`. It counts the time steps and calls `PDAF_put_state_X` when the forecast phase is complete. Thus, to implement a new filter, one can copy a routine and apart form adapting the name (`X`) and the interface specifying the call-back routines, there should be no need for changes.
    214219
    215220== Analysis update step `PDAF_X_update` ==
    … …  
    217222The actual DA analysis update is computed in the routine `PDAF_X_update`. The routine is provided with the names of the call-back routines, the arrays as well of the relevant dimensions as describe above.
    218223
    219 The structure of the operations in `PDAF_X_update` can be designed freely when implementing a new DA method. The existing methods follow the recommended structure in which `PDAF_x_update` only performes preparations for the actual analysis update and then calls `PDAF_X_analysis` for the computation of the actual update. Here, the operations are different for global and local methods.
     224The structure of the operations in `PDAF_X_update` can be designed freely when implementing a new DA method. The existing methods follow the recommended structure in which `PDAF_X_update` only performes preparations for the actual analysis update and then calls `PDAF_X_analysis` for the computation of the actual update. Here, the operations are different for global and local methods.
    220225
    221226=== Global Methods ===
    222227
    223 For localized Methods, e.g. ESTKF, ETKF or NETF, the general structure of `PDAF_X_update` is:
     228For global methods, e.g. ESTKF, ETKF, EnKF, NETF, the general structure of `PDAF_X_update` is:
    224229
    225230{{{
    226231   IF (fixed ensemble, i.e. subtype==2 or subtype==3) THEN
    227       Add central state for ensemble perturbations
     232      Add central state and ensemble perturbations
    228233   ENDIF
    229234
    … …  
    232237   CALL PDAF_X_analysis  # Compute global analysis update of ensemble
    233238
    234    CALL PDAF_smoother   # Only for filters for which a smoother is implemented
     239   CALL PDAF_smoother    # Compute smoother update (Only for filters for which a smoother is implemented)
    235240 
    236241   CALL U_prepoststep    # Perform pre/poststep after analysis update
    237242}}}   
    238 You will find this structure e.g. in `PDAF_ESTKF_update.F90`. This structure is also valid for the LEnKF. The actual implementation, e.g. in `PDAF_ESTKF_update.F90` contains additional functionality e.g. calls for timers and normal screen output or debug outputs. Also there can be different calls `PDAF_X_analysis` depending on the subtype of a filter.
     243You will find this structure e.g. in `PDAF_ESTKF_update.F90`. This structure is also valid for the LEnKF. The actual implementation, e.g. in `PDAF_ESTKF_update.F90` contains additional functionality e.g. calls for timers and normal screen output or debug outputs. Also there can be several different calls `PDAF_X_analysis` depending on the subtype of a filter.
    239244
    240245This general structure should be widely usable. Thus, when implementing a new global ensemble method one could copy an existing file and adapt it for the new method. The main functionality of the new DA method would then be implemented in `PDAF_X_analysis`.
    … …  
    247252{{{
    248253   IF (fixed ensemble, i.e. subtype==2 or subtype==3) THEN
    249       Add central state for ensemble perturbations
     254      Add central state and ensemble perturbations
    250255   ENDIF
    251256