| 227 | | 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 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`.) |
| 228 | | |
| 229 | | 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 by counting the number of time steps. |
| 230 | | |
| 231 | | Apart 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: |
| 232 | | * `U_collect_state`: The routine that writes model fields into the state vector, i.e. a single column of the ensemble state array |
| 233 | | * `U_init_dim_obs`: The routine that determines the size of the observation vector |
| 234 | | * `U_obs_op`: The routine that contains the implementation of the observation operator |
| 235 | | * `U_init_obs`: The routine that provdes the vector of observations |
| 236 | | * `U_prepoststep`: The pre- and post-step routine in which the forecast and analysis ensembles can be analyzed or modified. |
| 237 | | `PDAF_assimilate_X` uses in addition |
| 238 | | * `U_distribute_state`: The routine that fills the field arrays of a model from the state vector, i.e. a single column of the ensemble state array |
| 239 | | * `U_next_observation`: The routine that specified the number of time steps until the next DA analysis update. |
| 240 | | |
| 241 | | Further 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 |
| 242 | | * `U_prodRinvA` which has to multiply some temporary matrix of the filter method with the inverse observation error covariance matrix. |
| 243 | | |
| 244 | | When 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). |
| 245 | | |
| 246 | | The 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`. |
| 247 | | |
| 248 | | 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`. `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. |
| 249 | | The operations implemented in `PDAF_put_state_X` are: |
| 250 | | * Write model fields back into the ensemble array (by calling `U_collect_state`) |
| 251 | | * Increment the counter for the integrated ensemble members (named `counter` and provided by the module `PDAF_mod_filter`. |
| 252 | | * Check, if the ensemble integration is completed (in that case, it is `member = local_dim_ens + 1`). If not, exit `PDAF_put_state_X`. |
| 253 | | * When the ensemble integration is completed, the following operations are required: |
| 254 | | * 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`. |
| 255 | | * Call the routine that computes the analysis step for the chosen filter algorithm (typically named `PDAF_X_update`). |
| 256 | | * Reset the control variables for the ensemble forecast (`initevol=1`, `member=1`, `step=step_obs+1`). |
| 257 | | |
| 258 | | 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). |
| 259 | | |
| 260 | | 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, 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. |
| 261 | | |
| 262 | | == Analysis update step `PDAF_X_update` == |
| | 227 | This routine is called by `PDAF3_assimilate` and other of the advanced 'assimilate'-routines (See further below for information o how to integrate a new DA method into the advanced interface routines). It provides the full interface in which all user-supplied routines are specified as arguments. For detailed information on using the routines with he full interface, please see the [wiki:ImplementationofAnalysisStep_noOMI Page on Implementing the Analysis Step using PDAF's full interface]. |
| | 228 | |
| | 229 | Except for the status flag `outflag`, all arguments of `PDAF_assimilate_X` are the names of user-provided call-back routines. |
| | 230 | |
| | 231 | The routine is an infrastructure routine which is nearly identical for all DA methods. The template marks the lines which are generic and those which are specific to a DA method. Specific is the call to `PDAF_put_state_X`, both with regard to its name and to its arguments. Thus, when implementing a new DA method one has to adapt the argument list to those call-back routines that are used by the DA method. |
| | 232 | |
| | 233 | Most of the specified call-back routines are used for all DA method. For example, the interface in the template for the global ensemble filter (`template/analysis_step/global/PDAF_assimilate_GLOBALTEMPLATE.F90`) is: |
| | 234 | {{{ |
| | 235 | SUBROUTINE PDAF_assimilate_GLOBALTEMPLATE(U_collect_state, U_distribute_state, & |
| | 236 | U_init_dim_obs, U_obs_op, U_init_obs, U_prodRinvA, & |
| | 237 | U_init_obsvar, U_next_observation, U_prepoststep, outflag) |
| | 238 | }}} |
| | 239 | Here, `U_` marks the user-provided call-back routines. This interface is identical to that in `PDAF_assimilate_etkf.F90`, `PDAF_assimilate_estkf.F90` and `PDAF_assimilate_seik.F90`. The only routines that are specific to the DA method are `U_prodRinvA` and `U_init_obsvar. Thus, only these should be changed (e.g. some DA method do not used the product of **R**^-1^ with some matrix which is provided by `U_prodRinvA`, but compute an observation likelihood. Then one would rather use `U_likelihood`.) |
| | 240 | |
| | 241 | The generic routines, which are always needed are: |
| | 242 | || |
| | 243 | |
| | 244 | The domain-local filters (`template/analysis_step/global/PDAF_assimilate_LOCALTEMPLATE.F90`) have additional arguments to handle the localization of the state vectors and the localization of obsevations. However, they use the same generic routines |
| | 245 | |
| | 246 | |
| | 247 | === `PDAF_assim_offline_X` === |
| | 248 | |
| | 249 | === `PDAF_put_state_X` === |
| | 250 | |
| | 251 | === `PDAFX_update` === |
