= The simplified interface of PDAF = {{{ #!html

Implementation Guide

  1. Main page
  2. Adaptation of the parallelization
  3. Initialization of PDAF
  4. Modifications for ensemble integration
  5. Implementation of the analysis step
  6. Memory and timing information
  7. PDAF's simplified interface
}}} [[PageOutline(2-3,Contents of this page)]] == Overview == With version 1.7 of PDAF as simplified (or shortened) interface has been introduced. It can be used as an alternative to the full interface, which remains to exist. In the full interface, the names of all required user-supplied subroutines (e.g. the implementation of the observation operator) need to be specified. This scheme allows the user to choose the names of these routines. In contrast, the simplified interface uses pre-defined routine names and does not require to define the name in the call to PDAF. Thus, the interfaces are shorted. On the other hand, the simplified interface restricts the names of the user-supplied to the pre-defined ones. We leave it to the user to decide, which variant he or she prefers. The implementation of PDAF with the simplified interface is analogous to the case when the full interface is used. Below, we described the differences in the interfaces. For the general implementation guide, please see the pages describing the implementation with the full interface. (The subroutine names listed there are the pre-defined names required when the simplified interface is used) Overview of predefined names: || predefined name || Name in documentation || called by || || `init_ens_pdaf` || `U_init_ens` || `PDAF_init[_si]` || || `next_observation_pdaf` || `U_next_observation` || `PDAF_get_state[_si]`, `PDAF_assimilate_state_X[_si]` || || `distribute_state_pdaf` || `U_distribute_state` || `PDAF_get_state[_si]`, `PDAF_assimilate_state_X[_si]` || || `prepoststep_pdaf` || `U_prepoststep` || `PDAF_get_state[_si]`, `PDAF_put_state_X[_si]`, `PDAF_assimilate_state_X[_si]` || || `collect_state_pdaf` || `U_collect_state` || `PDAF_put_state_X[_si]`, `PDAF_assimilate_state_X[_si]` || In addition, there are filter-specific routines whose names are given on the page for each filter in the documentation on the [ImplementationofAnalysisStep implementation of the analysis step]. == Required arguments for `PDAF_init_si` == The call to `PDAF_init_si` has the following structure: {{{ CALL PDAF_init_si(filtertype, subtype, step_null, & filter_param_i, length_filter_param_i, & filter_param_r, length_filter_param_r, & COMM_model, COMM_filter, COMM_couple, & task_id, n_modeltasks, filterpe, & screen, status_pdaf) }}} The required variables are the following: * `filtertype`: An integer defining the type of filter algorithm. Available are * 0: SEEK * 1: SEIK * 2: EnKF * 3: LSEIK * 4: ETKF * 5: LETKF * `subtype`: An integer defining the sub-type of the filter algorithm (see the example code in `testsuite/src/dummymodel_1D` for choices) * `step_null`: An integer defining the initial time step. For some cases it can use useful to set `step_null` larger to 0. * `filter_param_i`: Integer array collecting several variables for PDAF. The first two variables are mandatory and equal for all filters. Further variables are optional (see example code). The mandatory variables are in the following order: * The size of the local state vector for the current process. * The ensemble size for all ensemble-based filters (or the rank of the state covariance matrix for mode-based filters like SEEK) * `length_filter_param_i`: An Integer defining the length of the array `filter_param_i`. The entries in the array are parsed up to this index. * `filter_param_r`: Array of reals collecting floating point variables for PDAF. The first variable is mandatory and equal for all filters. Further variables are optional (see example code in `testsuite/src/dummymodel_1D`). The mandatory variable is: * The value of the forgetting factor (required to be larger than zero) * `length_filter_param_r`: An Integer defining the length of the array `filter_param_r`. The entries in the array are parsed up to this index. * `COMM_model`: The communicator variable `COMM_model` as initialized by `init_parallel_pdaf`. If the model-communicator is named differently in the actual program, the name has to be adapted * `COMM_filter`: The communicator variable `COMM_filter` as initialized by `init_parallel_pdaf`. * `COMM_couple`: The communicator variable `COMM_couple` as initialized by `init_parallel_pdaf`. * `task_id`: The index of the model tasks as initialized by `init_parallel_pdaf`. * `n_modeltasks`: The number of model tasks as defined before the call to `init_parallel_pdaf`. * `filterpe`: The flag showing if a process belongs to `COMM_filter` as initialized by `init_parallel_pdaf`. * `screen`: An integer defining whether information output is written to the screen (i.e. standard output). The following choices are available: * 0: quite mode - no information is displayed. * 1: Display standard information (recommended) * 2: as 1 plus display of timing information during the assimilation process * 3: Display detailed information for debugging * `status_pdaf`: An integer used as status flag of PDAF. If `status_pdaf` is zero upon exit from `PDAF_init` the initialization was successful. An error occurred for non-zero values. (The error codes are documented in the routine PDAF_init.) It is recommended that the value of `status_pdaf` is checked in the program after PDAF_init is executed. Only if its value is 0 the initialization was successful. The routine `PDAF_init` calls the user-supplied routine `init_ens_pdaf`. The interface of `init_ens_pdaf` is described on the [InitPdaf#User-suppliedroutineU_init_ensinit_ens_pdaf.F90 page on PDAF_init with full interface]. == `PDAF_get_state_si` == The routine `PDAF_get_state_si` has the purpose to initialize the information, whether further model integrations have to be computed and how many time steps have to be performed. In addition, the model fields to be propagated are initialized from the array holding the ensemble states. The interface of `PDAF_get_state_si` is the following: {{{ SUBROUTINE PDAF_get_state_si(nsteps, timenow, doexit, status) }}} with the following arguments: * `nsteps`: An integer specifying upon exit the number of time steps to be performed * `timenow`: A real specifying upon exit the current model time. * `doexit`: An integer variable defining whether the assimilation process is completed and the program should exit the while loop. For compatibility 1 should be used for exit, 0 for continuing in the loop. * `status`: The integer status flag. It is zero, if `PDAF_get_state` is exited without errors. The routine `PDAF_get_state_si` calls three user-supplied routines with the pre-defined names: * `next_observation_pdaf` * `distribute_state_pdaf` * `prepoststep_pdaf` The interfaces of these routines are described on the [ModifyModelforEnsembleIntegration#U_next_observationnext_observation_pdaf.F90 page on the implementation with the full interface]. == `PDAF_put_state_X_si` == There is a separate routine `PDAF_put_state_X_si` for each of the filter algorithms. The name of the routine includes the name of the filter (instead of `X`). The purpose of the `PDAF_put_state_X_si` routines is to write back the forecast model fields into the array holding the ensemble of model state vectors. In addition, the routine checks if the current forecast phase is completed. If not, the routine is exited and the next cycle of the ensemble loop is performed. If the current forecast phase is completed, the routine executes the analysis step of the chosen filter algorithm. Each filter algorithm has its own put-state routine, because the distinct names of several user-supplied routines. The different names do not appear in the simplified interrfaces but are defined internally to PDAF. At the stage of implementing the ensemble integration only the first and last arguments of the routines are relevant. The interface for all filters is the following: {{{ SUBROUTINE PDAF_put_state_X_si(status) }}} and has only a single argument: * `status`: The integer status flag. It is zero, if PDAF_get_state is exited without errors. At the stage of [ModifyModelforEnsembleIntegration implementing the ensemble integration], one user-supplied routine is relevant: * `collect_state_pdaf` The interface of this routine is described on the page on [ModifyModelforEnsembleIntegration#U_collect_statecollect_state.F90 implementing the ensemble integration with the full interface]. The other arguments are names of user-supplied subroutines that are only executed if the analysis step is executed (See the section [ModifyModelforEnsembleIntegration#Compilationandtesting 'Compilation and testing'] for how to provide these routines for compilation at this stage). These routines are explained in the section of the implementation guide on ([ImplementationofAnalysisStep Implementation of the Analysis step]) separately for each available filter algorithm. == `PDAF_assimilate_X_si` == There is a separate routine `PDAF_assimilate_X_si` for each of the filter algorithms. The name of the routine includes the name of the filter (instead of `X`). The purpose of the `PDAF_assimilate_X_si` routines is to write back the forecast model fields into the array holding the ensemble of model state vectors and to compute the analysis step of the chosen filter algorithm. Each filter algorithm has its own 'assimilate' routine, because the distinct names of several user-supplied routines. The different names do not appear in the simplified interfaces but are defined internally to PDAF. The interface for all filters is the following: {{{ SUBROUTINE PDAF_assimilate_X_si(status) }}} and has only a single argument: * `status`: The integer status flag. It is zero, if PDAF_get_state is exited without errors. At the stage of [ModifyModelforEnsembleIntegration implementing the ensemble integration], only three user-supplied routine are relevant: * `collect_state_pdaf` * `distribute_state_pdaf` * `next_observation_pdaf` The interface of these routines is described on the page on [ModifyModelforEnsembleIntegration#U_collect_statecollect_state.F90 implementing the ensemble integration with the full interface]. The other arguments are names of user-supplied subroutines that are only executed if the analysis step is executed (See the section [ModifyModelforEnsembleIntegration#Compilationandtesting 'Compilation and testing'] for how to provide these routines for compilation at this stage). These routines are explained in the section of the implementation guide on ([ImplementationofAnalysisStep Implementation of the Analysis step]) separately for each available filter algorithm.