| 73 | | * `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. |
| 74 | | * `COMM_model`: |
| 75 | | * `COMM_filter`: |
| 76 | | * `COMM_couple`: |
| 77 | | * `task_id`: |
| 78 | | * `n_modeltasks`: |
| 79 | | * `filterpe`: |
| 80 | | * `U_init_ens`: The name of the user-supplied routine that is called by `PDAF_init` to initialize the ensemble of model states. (See '[#User-suppliedroutineU_init_ens User-supplied routine U_init_ens]' |
| 81 | | * `screen`: |
| | 72 | * `length_filter_param_r`:[[BR]] An integer defining the length of the array `filter_param_r`. The entries in the array are parsed up to this index. |
| | 73 | * `COMM_model`:[[BR]] 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 |
| | 74 | * `COMM_filter`:[[BR]] The communicator variable `COMM_filter` as initialized by `init_parallel_pdaf`. |
| | 75 | * `COMM_couple`:[[BR]] The communicator variable `COMM_couple` as initialized by `init_parallel_pdaf`. |
| | 76 | * `task_id`:[[BR]] The index of the model tasks as initialized by `init_parallel_pdaf`. |
| | 77 | * `n_modeltasks`:[[BR]] The number of model tasks as defined before the call to `init_parallel_pdaf`. |
| | 78 | * `filterpe`:[[BR]] The flag showing if a process belongs to `COMM_filter` as initialized by `init_parallel_pdaf`. |
| | 79 | * `init_ens_pdaf`:[[BR]] The name of the user-supplied routine that is called by `PDAF_init` to initialize the ensemble of model states. (See below: '[#User-suppliedroutineU_init_ens User-supplied routine U_init_ens]' |
| | 80 | * `screen`:[[BR]] An integer defining whether information output is written to the screen (i.e. standard output). The following choices are available: |
| 85 | | * `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.) |
| 86 | | |
| 87 | | An overview of available options for each filter an be found on the [wiki:AvailableOptionsforInitPDAF overview page on options]. |
| 88 | | |
| 89 | | 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. |
| | 84 | * `status_pdaf`:[[BR]] 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.) |
| | 85 | |
| | 86 | PDAF uses two arrays `filter_param_i` and `filter_param_r` to respectively specify integer and real-valued options for PDAF. As described above, 2 integer values (state vector size, ensemble size) and 1 real option (forgetting factor for inflation) are mandatory. Additional options can be set by specifying a larger array and setting the corresponding size value (`length_filter_param_i`, `length_filter_param_r`). However, with PDAF V3.0 it can be more convenient to use the subroutines `PDAF_set_iparam and `PDAF_set_rparam`, which are explained further below. |
| | 87 | |
| | 88 | An overview of available integer and real-valued options for each DA method can be found on the page[wiki:AvailableOptionsforInitPDAF Available options for the different DA methods]. The available options for a specific DA method can also be displayed by running the assimilation program for the selected DA method setting `subtype = -1`. (In the tutorial and template codes one can set `-subtype -1` on the command line). |
| | 89 | |
| | 90 | It is recommended to check the value of `status_pdaf` in the program after PDAF_init (and potentially `PDAF_set_iparam and `PDAF_set_rparam`) are executed. Only if its value is 0 the initialization was successful. |
| | 91 | |
| 100 | | == User-supplied routine `U_init_ens` == |
| 101 | | |
| 102 | | The user-supplied routine the we named `U_init_ens` here, is called by PDAF through the defined interface described below. The routine is called by all MPI processes that compute the filter analysis step (i.e. those for which 'filterpe' is set to true. In the standard configuration of `init_parallel_pdaf` these are all processes of the first model task, i.e. task_id=1.) `U_init_ens_pdaf` is only called by `PDAF_init` if no error occurred before; thus the status flag is zero. |
| 103 | | |
| 104 | | The interface is the following: |
| 105 | | {{{ |
| 106 | | SUBROUTINE U_init_ens(filtertype, dim_p, dim_ens, & |
| | 101 | Apart from the generic variables for loclaization, we also specify variables that are specific for each obseration type, for example |
| | 102 | * `assim_A`: Flag whether to assimialtion observations of type A |
| | 103 | * `rms_obs_A`: Assumed observation error standard deviation of observation type A |
| | 104 | |
| | 105 | == User-supplied routine `init_ens_pdaf` == |
| | 106 | |
| | 107 | The user-supplied routine the we named `init_ens_pdaf` here, is the call-back routine that called by PDAF through the defined interface described below. The routine is called by all MPI processes that compute the filter analysis step (i.e. those for which 'filterpe' is set to true. In the standard configuration of `init_parallel_pdaf` these are all processes of the first model task, i.e. task_id=1.) `init_ens_pdaf` is only called by `PDAF_init` if no error occurred before; thus the status flag is zero. |
| | 108 | |
| | 109 | The interface can be looked up in the template and tutorial codes. It is the following: |
| | 110 | {{{ |
| | 111 | SUBROUTINE init_ens_pdaf(filtertype, dim_p, dim_ens, & |
| 110 | | * `filtertype`: The integer defining the type of filter algorithm as given in the call to `PDAF_init` |
| 111 | | * `dim_p`: An integer holding the size of the state dimension for the calling process as specified in the call to `PDAF_init` |
| 112 | | * `dim_ens`: An integer holding the size of the ensemble (or the rank of the state covariance matrix for SEEK) |
| 113 | | * `state_p`: A real array of size (`dim_p`) for the local model state of the calling process (Only relevant for mode-based filters) |
| 114 | | * `Uinv`: A real array of size (`dim_ens-1`, `dim_ens-1`) for the inverse of matrix '''U''' from the decomposition of the state error covariance matrix '''P''' = '''VUV^T^''' (Only relevant for mode-based filters like SEEK.) |
| 115 | | * `ens_p`: A real array of size (`dim_p`, `dim_ens`) the has to hold upon exit the ensemble of model states. |
| 116 | | * `flag`: Status flag for PDAF. It is 0 upon entry and can be set by in the user-supplied routine, depending on the success of the ensemble initialization. Preferably, values above 102 should be used for failures to avoid conflicts with the error codes defined within PDAF_init. |
| 117 | | |
| 118 | | In the initialization routine `U_init_ens_pdaf` one has to distinguish between ensemble-based and mode-based filters. The only mode based filter supplied with PDAF is SEEK, while all other methods are ensemble-based. |
| | 115 | * `filtertype`:[[BR]] The integer defining the type of filter algorithm as given in the call to `PDAF_init` |
| | 116 | * `dim_p`:[[BR]] An integer holding the size of the state dimension for the calling process as specified in the call to `PDAF_init` |
| | 117 | * `dim_ens`:[[BR]] An integer holding the size of the ensemble |
| | 118 | * `state_p`:[[BR]] A real array of size (`dim_p`) for the local model state of the calling process (can be used freely for ensemble-based methods) |
| | 119 | * `Uinv`:[[BR]] A real array of size (`dim_ens-1`, `dim_ens-1`) for the inverse of matrix '''U''' from the decomposition of the state error covariance matrix '''P''' = '''VUV^T^''' (Not relevant for ensemble-based methods) |
| | 120 | * `ens_p`:[[BR]] A real array of size (`dim_p`, `dim_ens`), which has to be filled with the ensemble of model states. |
| | 121 | * `flag`:[[BR]] Status flag for PDAF. It is 0 upon entry and can be set by in the user-supplied routine, depending on the success of the ensemble initialization. Preferably, values above 102 should be used for failures to avoid conflicts with the error codes defined within PDAF_init. |
| | 122 | |
| 122 | | Generally, we work with ensemble-based filters (an exception is only the parameterized 3D-Var). For the ensemble-based filters only the array `ens_p` needs to be initialized by the ensemble of model states. If a model with domain decomposition is used, the full ensemble for the local sub-domain of the MPI process has to be initialized. |
| 123 | | |
| 124 | | The arrays `state_p` and `Uinv` are allocated to their correct sizes because they are used during the assimilation cycles. They are not yet initialized and it is allowed to use these arrays in the initialization. An exception from this is |
| | 126 | Most data assimilation methods are based on ensembles (an exception is only the parameterized 3D-Var). For the ensemble-based methods only the array `ens_p` needs to be initialized by the ensemble of model states. If a model with domain decomposition is used, the full ensemble for the local sub-domain of the MPI process has to be initialized. |
| | 127 | |
| | 128 | The arrays `state_p` and `Uinv` are allocated to their correct sizes because they are used during the assimilation cycles. They are not yet initialized and it is allowed to use these arrays in the initialization. An exception from this is the EnKF for which `Uinv` is allocated only with size (`1`,`1`), because `Uinv` is not using for EnKF. |
| 128 | | |
| 129 | | == Activating the offline mode with `PDAF_set_offline_mode` == |
| 130 | | |
| 131 | | To use the offline mode, it has to be activated by calling `PDAF_set_offline_mode`. This is usally done at the end of `init_pdaf`. The routine has a simple interface as follows: |
| 132 | | {{{ |
| 133 | | SUBROUTINE PDAF_set_offline_mode(screen) |
| 134 | | |
| 135 | | INTEGER, INTENT(in) :: screen ! Control verbosity of routine |
| 136 | | ! >0: display information output |
| 137 | | }}} |
| 138 | | here `screen` is usually the same variable as what is used as argument in the call to `PDAF_init`. |
| 139 | | |
| 140 | | '''Note: ''' |
| 141 | | * Before PDAF V2.2 one had to activate the offline mode by setting `subtype=5`. This has been replaced by the call to `PDAF_set_offline_mode` to give users flexibility in specifying `subtype`. Up to PDAF V2.3.1 the use of `subtype=5` was still possible. In PDAF V3.0 we removed this possibility and the call to `PDAF_set_offline_mode` is mandatory. |
| | 132 | == Setting additional options == |
| | 133 | |
| | 134 | In PDAF V3.0 we added the possibility to set options for PDAF after the call to `PDAF_init`. For these there are the subroutines |
| | 135 | {{{ |
| | 136 | PDAF_set_iparam(id, value, status_pdaf) |
| | 137 | }}} |
| | 138 | to set interger parameters and |
| | 139 | {{{ |
| | 140 | PDAF_set_rparam(id, value, status_pdaf) |
| | 141 | }}} |
| | 142 | to set REAL (floating point) parameters. The arguments are |
| | 143 | * `id`:[[BR]] The index value of a parameter |
| | 144 | * `value`:[[BR]] The value of the parameter with index `id` |
| | 145 | * `status_pdaf`:[[BR]] Status flag for PDAF. Both routines increment in the input value. The increment is 0 for no error (this allows to check `flag` once after all calls to `PDAF_init`, `PDAF_set_iparam`, and `PDAF_set_rparam`.) |
| | 146 | |
| | 147 | An overview of available integer and real-valued options for each DA method can be found on the page[wiki:AvailableOptionsforInitPDAF Available options for the different DA methods]. The available options for a specific DA method can also be displayed by running the assimilation program for the selected DA method setting `subtype = -1`. (In the tutorial and template codes one can set `-subtype -1` on the command line). |
| | 148 | |
