| | 20 | == Set or reset PDAF parameters == |
| | 21 | |
| | 22 | === PDAF_set_iparam === |
| | 23 | |
| | 24 | This routine is used to set integer parameters for PDAF. It was introduced with PDAF V3.0. |
| | 25 | |
| | 26 | The integer parameters specific to a DA method can be set in the array `filter_param_i` that is an argument of `PDAF_init` (see the [wiki:InitPdaf page on initializing PDAF]). `PDAF_set_iparam` provides an alternative way. Instead of providing all parameters in the call to `PDAF_init`, one can provide only the required minimum for this call. Afterwards, one can then call `PDAF_set_iparam` for each integer parameter that one intends to specify differently from the default value. An advantage of using `PDAF_set_iparam` is that one only needs to call it for parameters that one intends to change, while in the call to `PDAF_init` all parameters up to the index one intends to change have to be specified, even if one does not want to change a parameter value. The tutorials and templates show the use of `PDAF_set_iparam`. |
| | 27 | |
| | 28 | Full documentation: [wiki:PDAF_set_iparam] |
| | 29 | |
| | 30 | === PDAF_set_rparam === |
| | 31 | |
| | 32 | This routine is used to set real-valued (floating-point) parameters for PDAF. It was introduced with PDAF V3.0. |
| | 33 | |
| | 34 | The real-value parameters specific to a DA method can be set in the array `filter_param_r` that is an argument of `PDAF_init` (see the [wiki:InitPdaf page on initializing PDAF]). `PDAF_set_rparam` provides an alternative way. Instead of providing all parameters in the call to `PDAF_init`, one can provide only the required minimum for this call. Afterwards, one can then call `PDAF_set_rparam` for each integer parameter that one intends to specify differently from the default value. An advantage of using `PDAF_set_rparam` is that one only needs to call it for parameters that one intends to change, while in the call to `PDAF_init`, all parameters up to the index one intends to change have to be specified, even if one does not want to change a parameter value. The tutorials and templates show the use of `PDAF_set_rparam`. |
| | 35 | |
| | 36 | Full documentation: [wiki:PDAF_set_rparam] |
| | 37 | |
| | 38 | == Get information for forecast phase == |
| | 39 | |
| | 40 | === PDAF_get_fcst_info === |
| | 41 | |
| | 42 | This routine was introduced with PDAF V3.0. |
| | 43 | |
| | 44 | This routine returns the number of time steps to be computed int he current forecast phase. It also returns an exit flag to control the termination of ensemble forecasting and a value of the model time at the beginning of the forecast. |
| | 45 | |
| | 46 | This routine is required in the setup of the [wiki:OnlineFlexible_PDAF3 flexible parallelization variant] in the form introduced with PDAF V3.0. However it can balso be useful for the fully parallel case. |
| | 47 | |
| | 48 | Full documentation: [wiki:PDAF_get_fcst_info] |
| | 49 | |
| | 50 | |
| | 51 | |
| 24 | | 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. |
| 25 | | |
| 26 | | {{{ |
| 27 | | CALL PDAF_get_smootherens(sens_pointer, maxlag, status) |
| 28 | | }}} |
| 29 | | |
| 30 | | The variables in the interface are the following: |
| 31 | | |
| 32 | | * `sens_pointer`: The pointer to the smoother ensemble. The dimension is `sens_pointer(:,:,:)`. Thus in the program calling `PDAF_get_smootherens` one has to declare `REAL, POINTER :: sens_pointer(:,:,:)`. On output it points to the smoother ensemble. |
| 33 | | * `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. |
| 34 | | * `status`: Status flag. 0 for successful exit. |
| 35 | | |
| 36 | | '''Important:''' |
| 37 | | |
| 38 | | * 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`! |
| 39 | | * Using a pointer combined with an intent, i.e. using a pointer as argument, is a feature of Fortran 2003. Thus, if a too old compiler is used, it will provide an error when the routine is compiled. |
| 40 | | |
| 41 | | Notes: |
| 42 | | |
| 43 | | * `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. |
| 44 | | * 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`. |
| 45 | | * For an example using `PDAF_get_smootherens` see the implementation for the Lorenz96 model in `models/lorenz96/`. The routine is called in `compute_rms_smoother.F90`. |
| | 56 | A smoother is available for several filters (ESTKF/LESTKF/ETKF/LETKF/EnKF/NETF/LNETF). |
| | 57 | |
| | 58 | This routine is called to set a Fortran pointer to the array in PDAF that stores the ensembles for smoothing. In addition, the routine returns the available lag of the smoothing. Using this routine is required to aassess the smoother array, e.g. to write the smoother ensemble or its mean into a file. |
| | 59 | |
| | 60 | Full documentation: [wiki:PDAF_get_smootherens] |
| 51 | | A smoother is available for several filters (ESTKF/LESTKF/ETKF/LETKF/EnKF/NETF/LNETF). 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. |
| 52 | | |
| 53 | | {{{ |
| 54 | | CALL PDAF_set_smootherens(sens_pointer, maxlag, status) |
| 55 | | }}} |
| 56 | | |
| 57 | | The arguments are: |
| 58 | | |
| 59 | | * `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. |
| 60 | | * `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. |
| 61 | | * `status`: Status flag. 0 for successful exit. |
| 62 | | |
| 63 | | |
| 64 | | '''Important:''' |
| 65 | | |
| 66 | | * 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`! |
| 67 | | * Using a pointer combined with an intent, i.e. using a pointer as argument, is a feature of Fortran 2003. Thus, if a too old compiler is used, it will provide an error when the routine is compiled. |
| 68 | | |
| 69 | | |
| 70 | | Notes: |
| 71 | | |
| 72 | | * `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`. |
| 73 | | * 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`. |
| | 65 | A smoother is available for several filters (ESTKF/LESTKF/ETKF/LETKF/EnKF/NETF/LNETF). |
| | 66 | |
| | 67 | 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. |
| | 68 | |
| | 69 | Full documentation: [wiki:PDAF_set_smootherens] |
| 78 | | This routine allows a program to get a Fortran pointer to the internal ensemble array of PDAF. |
| 79 | | |
| 80 | | {{{ |
| 81 | | CALL PDAF_set_ens_pointer(ens_pointer, status) |
| 82 | | }}} |
| 83 | | |
| 84 | | The arguments are: |
| 85 | | |
| 86 | | * `ens_pointer`: The pointer to the smoother ensemble. The dimension is `ens_pointer(:,:)`. Thus in the program calling `PDAF_set_ens_pointer` one has to declare `REAL, POINTER :: sens_pointer(:,:)`. On output it points to the ensemble array. |
| 87 | | * `status`: Status flag. 0 for successful exit. |
| 88 | | |
| 89 | | |
| 90 | | '''Important:''' |
| 91 | | |
| 92 | | * Because `ens_pointer` is a pointer, the call to `PDAF_set_ens_pointer` 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_ens_pointer` one has to include `use PDAF_interfaces_module`! |
| 93 | | * Using a pointer combined with an intent, i.e. using a pointer as argument, is a feature of Fortran 2003. Thus, if a too old compiler is used, it will provide an error when the routine is compiled. |
| 94 | | |
| 95 | | |
| 96 | | Notes: |
| 97 | | |
| 98 | | * `PDAF_set_ens_pointer` is a special routine that is never needed when the standard online or offline modes of the implementation are used. However, the routine allows to build a model that uses each column of the ensemble array to store the model fields. Thus, one can avoid allocating additional memory for the model fields. |
| 99 | | |
| | 74 | This routine allows a program to get a Fortran pointer to the internal ensemble array of PDAF. This provides direct access to the ensemble array. |
| | 75 | |
| | 76 | `PDAF_set_ens_pointer` is a special routine that is never needed when the standard online or offline modes of the implementation are used. However, the routine allows to build a code that uses each column of the ensemble array to store the model fields. Thus, one can avoid allocating additional memory for the model fields. |
| | 77 | |
| | 78 | Full documentation: [wiki:PDAF_set_ens_pointer] |
| 105 | | 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. |
| 106 | | |
| 107 | | {{{ |
| 108 | | CALL PDAF_get_memberid(memberid) |
| 109 | | }}} |
| 110 | | |
| 111 | | The only argument is: |
| 112 | | * `memberid`: In integer providing on output the id the ensemble member |
| 113 | | |
| 114 | | Note: |
| 115 | | * 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. |
| | 84 | The routine returns the value of the ensemble member ID. It can be called during the ensemble integration, if a program needs this information, e.g. if ensemble-specific forcing is applied. Also it can be used in the routines `collect_state_pdaf` and `distribute_state_pdaf`. |
| | 85 | |
| | 86 | Full documentation: [wiki:PDAF_get_memberid] |
| 120 | | 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. |
| 121 | | |
| 122 | | {{{ |
| 123 | | CALL PDAF_get_obsmemberid(memberid) |
| 124 | | }}} |
| 125 | | |
| 126 | | The only argument is: |
| 127 | | * `memberid`: In integer providing on output the id the ensemble member |
| 128 | | |
| 129 | | Note: |
| 130 | | * The routine an be useful if the observation operator does not actually operate on the state vector that is provided when [wiki:obs_op_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). |
| | 91 | The routine returns the value of the ensemble member ID for the application of the observation operator. The routine can be called in the observation-operator routine `obs_op_OBSTYPE` in an PDAF_OMI observation module or in the user-supplied routine `obs_op_pdaf` if PDAF-OMI is not used. |
| | 92 | |
| | 93 | The routine an be useful if the observation operator does not actually operate on the state vector that is provided by PDAF. For the special situation where one, e.g., reads the observed state vector from a file (because it might be initialized separately). There might also 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). Inthese cases one need to member index as provided by `PDAF_get_obsmemberid`. |
| | 94 | |
| | 95 | Full documentation: [wiki:PDAF_get_obsmemberid] |
| | 96 | |
| 142 | | This routie allows to sepacify the communicator on which the overall PDAF communication bases. |
| 143 | | |
| 144 | | By default, PDAF bases on `MPI_COMM_WORLD`, thus all processes in a program. This routine allows to set a different communicator. This can be useful if a model is e.g. run with an OI-server so that the world communicator is split into processes for the IO (file) operations and other processes for the actual model run. In this casem, the model would run using a communicator distinct from `MPI_COMM_WORLD` and PDAF should operate only with this communicator. `PDAF_set_comm_pdaf` allows the user to specify this communicator for PDAF. |
| 145 | | |
| 146 | | {{{ |
| 147 | | SUBROUTINE PDAF_set_comm_pdaf(comm_pdaf) |
| 148 | | |
| 149 | | INTEGER,INTENT(in) :: comm_pdaf ! MPI communicator for PDAF |
| 150 | | }}} |
| 151 | | |
| 152 | | Notes: |
| 153 | | * `comm_pdaf` has to be used consistently in `init_parallel_pdaf` where the commuicators for PDAF are prepared on the user side. |
| 154 | | * The size of `comm_pdaf` has to be large enough so that the ensemble run can be performed |
| 155 | | * `PDAF_set_comm_pdaf` has to be called before calling `PDAF_init` |
| | 108 | This routime allows to specify the MPI communicator on which the overall PDAF communication bases. |
| | 109 | |
| | 110 | By default, PDAF bases on `MPI_COMM_WORLD`, thus all processes in a program. This routine allows to set a different communicator. This can be useful if a model is e.g. run with an OI-server so that the world communicator is split into processes for the file (I/O) operations and other processes for the actual model run. In this case, the model would run using a communicator distinct from `MPI_COMM_WORLD` and PDAF should operate only with this communicator. `PDAF_set_comm_pdaf` allows the user to specify this communicator for PDAF. |
| | 111 | |
| | 112 | Full documentation: [wiki:PDAF_set_comm_pdaf] |
| 163 | | the routine allows to activate debugging output. See the [wiki:PDAF_debugging documention on PDAF debuggging] for more information. |
| | 120 | The routine allows to activate debugging output. |
| | 121 | |
| | 122 | Full documentation: [wiki:PDAF_debugging PDAF debuggging]. |
| | 123 | |
| | 124 | == Information on localization == |
| | 125 | |
| | 126 | === PDAF_localfilter === |
| | 127 | |
| | 128 | This is a Fortran function that was introduced with PDAF V3.0 |
| | 129 | |
| | 130 | The function is an alternative to the subroutine `PDAF_get_localfilter`. In PDAF_localfilter the return value of the function is directly used, while for PDAF_get_localfilter the return value is an argument of the routine. |
| | 131 | |
| | 132 | The function returns the information whether the chosen filter is a domain-localized filter (LESTKF, LETKF, LSEIK, LNETF). It also indicates the ENSRF since these filters use the same observation handling of the domain-localized filters. |
| | 133 | |
| | 134 | Full documentation: [wiki:PDAF_localfilter] |
| | 135 | |
| | 136 | There is also a variant in the form of a subroutine: [wiki:PDAF_get_localfilter] |
| | 137 | |
| | 138 | === PDAF_local_type === |
| | 139 | |
| | 140 | This is a Fortran function that was introduced with PDAF V3.0 |
| | 141 | |
| | 142 | The function returns the information on the localization type of the filter set in the call to `PDAF_init`. With this one can distinguish filters using domain localization (LESTKF, LETKF, LSEIK, LNETF), covariance localization (LEnKF), or covariance localization with observation handling like domain localization (ENSRF/EAKF). This information is more detailed than what is returned by `PDAF_localfilter`. |
| | 143 | |
| | 144 | Full documentation: [wiki:PDAF_local_type] |
| | 145 | |
| | 146 | There is also a variant in the form of a subroutine: [wiki:PDAF_get_local_type] |
| | 147 | |
| | 151 | === PDAF_print_DA_types === |
| | 152 | |
| | 153 | This routine was introduced with PDAF V3.0. |
| | 154 | |
| | 155 | `PDAF_print_DA_types` can be called to show a list of IDs of the DA methods in PDAF. It will list the integer values of `filtertype` that can be specified in the call to `PDAF_init`. In addition, it will list the pre-defined parameter values `PDAF_DA_X` which are set to these values. These pre-define parameter values allow the user to specify e.g. the LESTKF with `PDAF_DA_LESTKF` as filtertype argument in the call to `PDAF_init`. |
| | 156 | |
| | 157 | Full documentation: [wiki:PDAF_print_DA_types] |
| | 158 | |
| | 159 | |
| | 160 | === PDAF_set_seedset === |
| | 161 | |
| | 162 | This routine was introduced with PDAF V2.1. |
| | 163 | |
| | 164 | This routine can be called to choose a seedset for the random number generator used in PDAF. With this one can perform experiments using different random numbers. |
| | 165 | |
| | 166 | Full documentation: [wiki:PDAF_set_seedset] |
| | 167 | |
| | 168 | |
| 173 | | For the local ensemble Kalman filters the forgetting factor can be set either globally of differently for each local analysis domain. For the LNETF and the global filters only a global setting of the forgeting factor is possible. This routine allows users to set the forgetting factor case-specific. In addition, the implementation of adaptive choices for the forgetting factor (beyond what is implemented in PDAF) are possible. |
| 174 | | |
| 175 | | The interface is the following: |
| 176 | | {{{ |
| 177 | | SUBROUTINE PDAF_reset_forget(forget) |
| 178 | | }}} |
| 179 | | with the following argument: |
| 180 | | * `forget`: `real, intent(in)`[[BR]] The new value of the forgetting factor |
| 181 | | |
| 182 | | '''How to use PDAF_reset_forget''' |
| 183 | | |
| 184 | | * '''Global Filters and LNETF''': For global filters `PDAF_reset_forget` has to be called before the actual analysis step. Within the PDAF context the call can be inserted in `prepoststep_pdaf`. Alternatively, the call can be inserted in the routine `assimilation_pdaf` before the call to the PDAF_assimilate_X or PDAF_put_state_X routines |
| 185 | | * '''Local Filters''': |
| 186 | | * global setting: The forgetting factor is reset globally, thus equal for all local analysis dimains, if `PDAF_reset_forget` is called before the local analysis loop is executed (e.g. in `init_obs_pdomi` or earlier in the analysis step; see [ImplementAnalysisLocal] for the order of the execution of the call-back routines). Thus, it can also be called in `prepoststep_pdaf` to get a global seeting as fo rthe global filters. |
| 187 | | * To reset `forget` specific for each local analysis domain, `PDAF_reset_forget` should be called during the local analysis loop. In particular the routines `init_dim_l` or `init_dim_obs_l_pdafomi` are suited for this. |
| | 175 | Full documentation: [wiki:PDAF_reset_forget] |
| | 176 | |
| | 177 | Note: Starting from PDAF V.30 one can also use `PDAF_set_rparam` to reset the value of the forgetting factor. |
| | 178 | |
| 194 | | The routine allows a user to enforce the execution of the analysis step at the next call to `PDAF_put_state_X` or `PDAF_assimilate_X`. |
| 195 | | |
| 196 | | In particular for `PDAF_assimilate_X`, the number of time steps is set before the forecast phase is entered. However, one might not know the actual length of the forecast time, e.g. the time when new observation arrive. In this case, one can set for number of time steps to a large value and then check for new observations during the time stepping and call `PDAF_force_analysis` just before `PDAF_assimilate_X` is called to enforce that the analysis step is executed. |
| 197 | | |
| 198 | | [[span(style=color: #FF0000, '''Warning:''' This is a routine for advanced functionality of PDAF. Use it carefully, since it can break the assimilation process.)]] |
| 199 | | |
| 200 | | For `PDAF_put_state_X`, one can use `PDAF_force_analysis` to overwrite the counting of the ensemble members that PDAF does internally. |
| 201 | | |
| 202 | | {{{ |
| 203 | | SUBROUTINE PDAF_reset_forget() |
| 204 | | }}} |
| 205 | | without any argument |
| | 185 | The routine allows a user to enforce the execution of the analysis step at the next call to `PDAF*_put_state` or `PDAF*_assimilate`. |
| | 186 | |
| | 187 | In particular for `PDAF*_assimilate`, the number of time steps is set before the forecast phase is entered. However, one might not know the actual length of the forecast phase, e.g. the time when new observations arrive. In this case, one can set for number of time steps to a large value and then check for new observations during the time stepping and call `PDAF_force_analysis` just before `PDAF*_assimilate` is called to enforce that the analysis step is executed. |
| | 188 | |
| | 189 | Full documentation: [wiki:PDAF_force_analysis] |
| | 190 | |
