| 87 | | To indicate user-supplied routines we use the prefix `U_`. In the template directory `templates/` as well as in the example implementation in `testsuite/src/dummymodel_1D` these routines exist without the prefix, but with the extension `_pdaf.F90`. In the section titles below we provide the name of the template file in parentheses. |
| 88 | | |
| 89 | | In the subroutine interfaces some variables appear with the suffix `_p` (short for 'process'). This suffix indicates that the variable is particular to a model sub-domain, if a domain decomposed model is used. Thus, the value(s) in the variable will be different for different model sub-domains. In addition, there will be variables with the suffix `_f` (for 'full') and with the suffix `_l` (for 'local'). |
| | 87 | To indicate user-supplied routines we use the prefix `U_`. In the template directory `templates/` as well as in the example implementation in `testsuite/src/dummymodel_1D` these routines exist without the prefix, but with the extension `_pdaf.F90`. The user-routines relating to OMI are collected in the file callback_obs_pdafomi.F90. In the section titles below we provide the name of the template file in parentheses. |
| | 88 | |
| | 89 | In the subroutine interfaces some variables appear with the suffix `_p` (short for 'process'). This suffix indicates that the variable is particular to a model sub-domain, if a domain decomposed model is used. In addition, there will be variables with suffix `_l` (indicating 'local'). |
| | 90 | |
| 102 | | === `U_init_dim_obs` (callback_obs_pdafomi.F90) === |
| 103 | | |
| 104 | | The interface for this routine is: |
| 105 | | {{{ |
| 106 | | SUBROUTINE init_dim_obs_pdafomi(step, dim_obs_f) |
| 107 | | |
| 108 | | INTEGER, INTENT(in) :: step ! Current time step |
| 109 | | INTEGER, INTENT(out) :: dim_obs_f ! Dimension of full observation vector |
| 110 | | }}} |
| 111 | | |
| 112 | | The routine is called at the beginning of each analysis step. For PDAF, it has to initialize the size `dim_obs_f` of the observation vector according to the current time step. `dim_obs_f` is usually be the size for the full model domain. When a domain-decomposed model is used, `dim_obs_f` can be reduced to those observations relevant for the local analysis loop in a process domain. |
| 113 | | |
| 114 | | With PDAF-OMI, the routine just calls a routine from the observation module for each observation type. |
| 115 | | |
| 116 | | |
| 117 | | === `U_obs_op` (callback_obs_pdafomi.F90) === |
| 118 | | |
| 119 | | The interface for this routine is: |
| 120 | | {{{ |
| 121 | | SUBROUTINE obs_op_pdafomi(step, dim_p, dim_obs_p, state_p, m_state_f) |
| 122 | | |
| 123 | | INTEGER, INTENT(in) :: step ! Currrent time step |
| 124 | | INTEGER, INTENT(in) :: dim_p ! PE-local dimension of state |
| 125 | | INTEGER, INTENT(in) :: dim_obs_f ! Dimension of observed state |
| 126 | | REAL, INTENT(in) :: state_p(dim_p) ! PE-local model state |
| 127 | | REAL, INTENT(out) :: m_state_f(dim_obs_f) ! Full observed state |
| 128 | | }}} |
| 129 | | |
| 130 | | The routine is called during the analysis step. It has to perform the operation of the observation operator acting on a state vector that is provided as `state_p`. The observed state has to be returned in `m_state_f`. |
| 131 | | |
| 132 | | With PDAF-OMI, the routine just calls a routine from the observation module for each observation type. |
| | 106 | === `U_init_dim_obs_pdafomi` (callback_obs_pdafomi.F90) === |
| | 107 | |
| | 108 | This is a call-back routine for PDAF-OMI initializing the observation information. The routine just calls a routine from the observation module for each observation type. |
| | 109 | |
| | 110 | See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information. |
| | 111 | |
| | 112 | |
| | 113 | |
| | 114 | === `U_obs_op_pdafomi` (callback_obs_pdafomi.F90) === |
| | 115 | |
| | 116 | This is a call-back routine for PDAF-OMI applying the observation operator to the state vector. The routine calls a routine from the observation module for each observation type. |
| | 117 | |
| | 118 | See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information. |
| 137 | | This routine can be identical to that used for the global ESTKF algorithm, which has already been described on the [ModifyModelforEnsembleIntegration#U_prepoststepprepoststep_ens.F90 page on modifying the model code for the ensemble integration]. For completeness, the description is repeated: |
| 138 | | |
| 139 | | The interface of the routine is identical for all filters. However, the particular operations that are performed in the routine can be specific for each filter algorithm. |
| 140 | | |
| 141 | | The interface for this routine is |
| 142 | | {{{ |
| 143 | | SUBROUTINE prepoststep(step, dim_p, dim_ens, dim_ens_p, dim_obs_p, & |
| 144 | | state_p, Uinv, ens_p, flag) |
| 145 | | |
| 146 | | INTEGER, INTENT(in) :: step ! Current time step |
| 147 | | ! (When the routine is called before the analysis -step is provided.) |
| 148 | | INTEGER, INTENT(in) :: dim_p ! PE-local state dimension |
| 149 | | INTEGER, INTENT(in) :: dim_ens ! Size of state ensemble |
| 150 | | INTEGER, INTENT(in) :: dim_ens_p ! PE-local size of ensemble |
| 151 | | INTEGER, INTENT(in) :: dim_obs_p ! PE-local dimension of observation vector |
| 152 | | REAL, INTENT(inout) :: state_p(dim_p) ! PE-local forecast/analysis state |
| 153 | | ! The array 'state_p' is not generally not initialized in the case of SEIK/EnKF/ETKF/ESTKF. |
| 154 | | ! It can be used freely in this routine. |
| 155 | | REAL, INTENT(inout) :: Uinv(dim_ens-1, dim_ens-1) ! Inverse of matrix U |
| 156 | | REAL, INTENT(inout) :: ens_p(dim_p, dim_ens) ! PE-local state ensemble |
| 157 | | INTEGER, INTENT(in) :: flag ! PDAF status flag |
| 158 | | }}} |
| 159 | | |
| 160 | | The routine `U_prepoststep` is called once at the beginning of the assimilation process. In addition, it is called during the assimilation cycles before the analysis step and after the ensemble transformation. The routine is called by all filter processes (that is `filterpe=1`). |
| 161 | | |
| 162 | | The routine provides for the user the full access to the ensemble of model states. Thus, user-controlled pre- and post-step operations can be performed. For example the forecast and the analysis states and ensemble covariance matrix can be analyzed, e.g. by computing the estimated variances. In addition, the estimates can be written to disk. |
| 163 | | |
| 164 | | Hint: |
| 165 | | * If a user considers to perform adjustments to the estimates (e.g. for balances), this routine is the right place for it. |
| 166 | | * Only for the SEEK filter the state vector (`state_p`) is initialized. For all other filters, the array is allocated, but it can be used freely during the execution of `U_prepoststep`. |
| 167 | | * The interface has a difference for LETKF and LESTKF: For the LETKF, the array `Uinv` has size `dim_ens` x `dim_ens`. In contrast it has size `dim_ens-1` x `dim_ens-1` for the LESTKF. |
| 168 | | * The interface through which `U_prepoststep` is called does not include the array of smoothed ensembles. In order to access the smoother ensemble array one has to set a pointer to it using a call to the routine `PDAF_get_smootherens` (see page on [AuxiliaryRoutines auxiliary routines]) |
| | 123 | The routine has already been described for modifying the model for the ensemble integration and for inserting the analysis step. |
| | 124 | |
| | 125 | See the page on [InsertAnalysisStep#U_prepoststepprepoststep_ens_pdaf.F90 inserting the analysis step] for the description of this routine. |
| | 126 | |
| 206 | | === `U_init_dim_obs_l` (callback_obs_pdafomi.F90) === |
| 207 | | |
| 208 | | The interface for this routine is: |
| 209 | | {{{ |
| 210 | | SUBROUTINE init_dim_obs_l_pdafomi(domain_p, step, dim_obs_f, dim_obs_l) |
| 211 | | |
| 212 | | INTEGER, INTENT(in) :: domain_p ! Current local analysis domain |
| 213 | | INTEGER, INTENT(in) :: step ! Current time step |
| 214 | | INTEGER, INTENT(in) :: dim_obs_f ! Full dimension of observation vector |
| 215 | | INTEGER, INTENT(out) :: dim_obs_l ! Local dimension of observation vector |
| 216 | | }}} |
| 217 | | |
| 218 | | The routine is called during the loop over the local analysis domains in the analysis step. |
| 219 | | It has to initialize in `dim_obs_l` the size of the observation vector used for the local analysis domain with index `domain_p`. |
| 220 | | |
| 221 | | With PDAF-OMI, the routine just calls a routine from the observation module for each observation type. PDAF-OMI will perform the necessary intializations based on the coordinates of the observations. |
| | 164 | === `U_init_dim_obs_l_pdafomi` (callback_obs_pdafomi.F90) === |
| | 165 | |
| | 166 | This is a call-back routine for PDAF-OMI that initializes the local observation vector. The routine calls a routine from the observation module for each observation type. |
| | 167 | |
| | 168 | See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information. |
