= Auxiliary Routines = [[PageOutline(2-3,Contents of this page)]] PDAF provide a number of auxiliary routines. They serve to access PDAF-internal data, which is not available through the regular interface of PDAF. == PDAF_interfaces_module.F90 == This file contains the module `PDAF_interfaces_module`. It provides interface definitions for the routines of PDAF. If you like to use explicit Fortran interfaces, or if you have to use then in case of the smoother, you have to include the following line in the header you the calling routine: {{{ use PDAF_interfaces_module }}} == PDAF-D_get_smootherens.F90 == A smoother is available for several filters (ESTKF/LESTKF/ETKF/LETKF/EnKF). This routine is called to set a Fortran pointer to the array in PDAF that stores the ensembles for smoothing. Also, the routine sets the available lag of the smoothing. {{{ CALL PDAF_get_smootherens(sens_pointer, maxlag, status) }}} The variables in the interface are the following: * `sens_pointer`: The pointer to the smoother ensemble. The dimension is `sens_pointer(:,:,:)`. Thus in the program calling `PDAF_get_smmotherens` one has to declare `REAL, POINTER :: sens_pointer(:,:,:)`. On output it points to the smoother ensemble. * `maxlag`: Number of lags stored in the smoother ensemble. While in the call to `PDAF_init` the maximum lag for the smoother is set, not all possible lags are using at the beginning of the assimilations. `maxlag` shows how many times were already smoothed. * `status`: Status flag. 0 for successful exit. '''Important:''' * Because `sens_pointer` is a pointer, the call to `PDAF_get_smootherens` needs an ''explicit'' Fortran interface. This is provided by the Fortran module `PDAF_interfaces_module`. In the header part of the routine that calls `PDAF_get_smootherens` one has to include `use PDAF_interfaces_module`! Notes: * `PDAF_get_smootherens` is typically called in the prepoststep routine after the analysis step. At this time not only the filtered analysis step can be analized, but also all smoothed ensembles. * The first two indices of `sens_pointer` are identical to those in the ensemble array `ens_p`. Thus, the array contains state vectors in its columns. The second index is the ensemble index. The third index is the lag. Thus, if the value of the third index is fixed one can use the array `sens_pointer` analogous to the ensemble array `ens_p`. * For an example using `PDAF_get_smootherens` see the example implementation `testsuite/src/dummymodel_1D/`. The routine is called in `compute_rms_smoother.F90`. == PDAF-D_set_smootherens.F90 == A smoother is available for several filters (ESTKF/LESTKF/ETKF/LETKF/EnKF). This routine is called to set a Fortran pointer to the array in PDAF that stores the ensembles for smoothing. In addition, it sets the available lag of the smoothing. This routine is called in the offline mode of PDAF. While in the online mode, the smoother ensemble array is filled automatically by PDAF, one has to fill it manually in the offline mode. `PDAF_set_smootherens` gives access to the smoother array to fill it. {{{ CALL PDAF_set_smootherens(sens_pointer, maxlag, status) }}} The arguments are: * `sens_pointer`: The pointer to the smoother ensemble. The dimension is `sens_pointer(:,:,:)`. Thus in the program calling `PDAF_get_smmotherens` one has to declare `REAL, POINTER :: sens_pointer(:,:,:)`. On output it points to the smoother ensemble. * `maxlag`: Set the number of lags stored in the smoother ensemble. While in the call to `PDAF_init` the maximum lag for the smoother is set, not all possible lags are using at the beginning of the assimilations. `maxlag` says how many times were already smoothed. Both values are usually identical for the offline mode. * `status`: Status flag. 0 for successful exit. '''Important:''' * Because `sens_pointer` is a pointer, the call to `PDAF_set_smootherens` needs an ''explicit'' Fortran interface. This is provided by the Fortran module `PDAF_interfaces_module`. In the header part of the routine that calls `PDAF_set_smootherens` one has to include `use PDAF_interfaces_module`! Notes: * `PDAF_set_smootherens` is typically called in the initialization phase of PDAF. It was to be called after the basic initialization of PDAF in `PDAF_init`. A possible location is to call `PDAF_set_smootherens` is the ensemble initialization routine `U_init_ens`. * The first two indices of `sens_pointer` are identical to those in the ensemble array `ens_p`. Thus, the array contains state vectors in its columns. The second index is the ensemble index. The third index is the lag. Thus, if the value of the third index is fixed one can use the array `sens_pointer` analogous to the ensemble array `ens_p`. == PDAF-D_get_memberid.F90 == This routine can be called from the model during an ensemble integration. It provides access to the number (id) of the ensemble member that is currently integrated. {{{ CALL PDAF_get_memberid(memberid) }}} The only argument is: * `memberid`: In integer providing on output the id the ensemble member Note: * Using `PDAF_get_memberid` is obviously only useful if more than one ensemble member is integrated by a model task. If there are as many model tasks as ensemble members, `memberid` is always 1. In this case one can use `task_id` from the module `mod_parallel` to distinguish the ensemble members. == PDAF-D_get_obsmemberid.F90 == This routine can be called from the model during the analysis step. It provides access to the number (id) of the ensemble member for which the user-routine for the observation operator is called. {{{ CALL PDAF_get_obsmemberid(memberid) }}} The only argument is: * `memberid`: In integer providing on output the id the ensemble member Note: * The routine an be useful if the observation operator does not actually operate on the state vector that is provided when [wiki:obs_obs_pdaf] is called. Their might be cases in which one likes to read model state information from a file (e.g. if the observation operator performs an averaging over time, while the state vector for the analysis step only contains a single time instance). == PDAF-D_incremental.F90 == When incremental updating is used, this routine is called during the forecast phase to add a fraction of the analysis increment to an ensemble member. {{{ CALL PDAF_incremental(steps, U_dist_stateinc) }}} The arguments are: * `steps`: The number of time steps over which the increment should be distributed * `U_dist_stateinc`: The name of the user supplied call-back function that performs the actual addition of the state vector increment to the individual model fields. == PDAF-D_add_increment.F90 == When incremental updating is used, the state increment of the analysis step is not directly added to the forecast state. To add the increment to some state vector `PDAF_add_increment` is called: {{{ CALL PDAF_add_increment(dim_p, state_p) }}} The arguments are * `dim_p`: An integer giving the state dimension of `state_p` * `state_p`: A real array of size `dim_p` holding the on input the state vector and on output the state vector plus increment. Note: * the routine can be used in the prepoststep routine when the analysis state should be analized.