Changes between Version 1 and Version 2 of Implement3DVarAnalysisPDAF3Universal


Ignore:
Timestamp:
May 26, 2025, 4:11:28 PM (7 weeks ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Implement3DVarAnalysisPDAF3Universal

    v1 v2  
    3838There are genenerally three different variants of 3D-Var provided by PDAF: parameterized 3D-Var, 3D Ensemble Var, and hybrid (parameterized + ensemble) 3D-Var. All can be called using the universal interface routines described here.
    3939
    40 For the analysis step of 3D-Var we need different operations related to the observations. These operations are requested by PDAF by call-back routines supplied by the user and provided in the OMI structure. The names of the routines that are provided by the user are specified in the call to the routine `PDAF3_assimilate_3dvar_all` in the online mode of PDAF or `PDAF3_assim_offline_3dvar_all` for the offline mode. With regard to the parallelization, all these routines (except `U_collect_state`, `U_distribute_state`, and `U_next_observation`) are executed by the filter processes (`filterpe=.true.`) only.
     40For the analysis step of 3D-Var we need different operations related to the observations. These operations are requested by PDAF by call-back routines supplied by the user and provided in the OMI structure. The names of the routines that are provided by the user are specified in the call to the routine `PDAF3_assimilate_3dvar_all` in the online mode of PDAF or `PDAF3_assim_offline_3dvar_all` for the offline mode. With regard to the parallelization, all these routines (except `collect_state_pdaf`, `distribute_state_pdaf`, and `next_observation_pdaf`) are executed by the filter processes (`filterpe=.true.`) only.
    4141
    4242The universal interface has more arguments than the specific interfaces for the parameterized 3D-Var or the 3D ensemble Var methods. It is useful if one implements both the 3D-Var with parameterized covariances and rhe 3D ensemble Var. The hybrid 3D-Var using the LESTKF is always called using this unversal interface.
     
    6767}}}
    6868where all arguments, except the last one, are the names of call-back routines:
    69  * [#U_collect_state_pdafcollect_state_pdaf.F90 collect_state_pdaf]: The name of the user-supplied routine that initializes a state vector from the array holding the ensemble of model states from the model fields. This is basically the inverse operation to `distribute_state` used in `PDAF_init_forecast` as well as here.
    70  * [#U_distribute_state_pdafdistribute_state_pdaf.F90 distribute_state_pdaf]:  The name of a user supplied routine that initializes the model fields from the array holding the ensemble of model state vectors.
    71  * [#U_init_dim_obs_pdafomicallback_obs_pdafomi.F90 init_dim_obs_pdafomi]: The name of the user-supplied routine that initializes the observation information and provides the size of observation vector
    72  * [#U_obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_pdafomi]: The name of the user-supplied routine that acts as the observation operator on some state vector
    73  * [#U_cvt_ens_pdafcvt_ens_pdaf.F90 cvt_ens_pdaf]: The name of the user-supplied routine that applies the ensemble control-vector transformation (square-root of the B-matrix) on some control vector to obtain a state vector.
    74  * [#U_cvt_adj_ens_pdafcvt_adj_ens_pdaf.F90 cvt_adj_ens_pdaf]: The name of the user-supplied routine that applies the adjoint ensemble control-vector transformation (with square-root of the B-matrix) on some state vector to obtain the control vector.
    75  * [#U_cvt_pdafcvt_pdaf.F90 cvt_pdaf]: The name of the user-supplied routine that applies the control-vector transformation (square-root of the B-matrix) on some control vector to obtain a state vector.
    76  * [#U_cvt_adj_pdafcvt_adj_pdaf.F90 cvt_adj_pdaf]: The name of the user-supplied routine that applies the adjoint control-vector transformation (with square-root of the B-matrix) on some state vector to obtain the control vector.
    77  * [#U_obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_lin_pdafomi]: The name of the user-supplied routine that acts as the linearized observation operator on some state vector
    78  * [#U_obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_lin_pdafomi]: The name of the user-supplied routine that acts as the adjoint observation operator on some state vector
    79  * [#U_init_n_domains_pdafinit_n_domains_pdaf.F90 init_n_domains_pdaf]: The name of the routine that provides the number of local analysis domains
    80  * [#U_init_dim_l_pdafinit_dim_l_pdaf.F90 init_dim_l_pdaf]: The name of the routine that provides the state dimension for a local analysis domain
    81  * [#U_init_dim_obs_l_pdafomicallback_obs_pdafomi.F90 init_dim_obs_l_pdafomi]: The name of the routine that initializes the size of the observation vector for a local analysis domain
    82  * [#U_prepoststep_pdafprepoststep_ens_pdaf.F90 prepoststep_pdaf]: The name of the pre/poststep routine as in `PDAF_init_forecast`
    83  * [#U_next_observation_pdafnext_observation.F90 next_observation_pdaf]: The name of a user supplied routine that initializes the variables `nsteps`, `timenow`, and `doexit`. The same routine is also used in `PDAF_init_forecast`.
     69 * [#collect_state_pdafcollect_state_pdaf.F90 collect_state_pdaf]: The name of the user-supplied routine that initializes a state vector from the array holding the ensemble of model states from the model fields. This is basically the inverse operation to `distribute_state` used in `PDAF_init_forecast` as well as here.
     70 * [#distribute_state_pdafdistribute_state_pdaf.F90 distribute_state_pdaf]:  The name of a user supplied routine that initializes the model fields from the array holding the ensemble of model state vectors.
     71 * [#init_dim_obs_pdafomicallback_obs_pdafomi.F90 init_dim_obs_pdafomi]: The name of the user-supplied routine that initializes the observation information and provides the size of observation vector
     72 * [#obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_pdafomi]: The name of the user-supplied routine that acts as the observation operator on some state vector
     73 * [#cvt_ens_pdafcvt_ens_pdaf.F90 cvt_ens_pdaf]: The name of the user-supplied routine that applies the ensemble control-vector transformation (square-root of the B-matrix) on some control vector to obtain a state vector.
     74 * [#cvt_adj_ens_pdafcvt_adj_ens_pdaf.F90 cvt_adj_ens_pdaf]: The name of the user-supplied routine that applies the adjoint ensemble control-vector transformation (with square-root of the B-matrix) on some state vector to obtain the control vector.
     75 * [#cvt_pdafcvt_pdaf.F90 cvt_pdaf]: The name of the user-supplied routine that applies the control-vector transformation (square-root of the B-matrix) on some control vector to obtain a state vector.
     76 * [#cvt_adj_pdafcvt_adj_pdaf.F90 cvt_adj_pdaf]: The name of the user-supplied routine that applies the adjoint control-vector transformation (with square-root of the B-matrix) on some state vector to obtain the control vector.
     77 * [#obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_lin_pdafomi]: The name of the user-supplied routine that acts as the linearized observation operator on some state vector
     78 * [#obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_lin_pdafomi]: The name of the user-supplied routine that acts as the adjoint observation operator on some state vector
     79 * [#init_n_domains_pdafinit_n_domains_pdaf.F90 init_n_domains_pdaf]: The name of the routine that provides the number of local analysis domains
     80 * [#init_dim_l_pdafinit_dim_l_pdaf.F90 init_dim_l_pdaf]: The name of the routine that provides the state dimension for a local analysis domain
     81 * [#init_dim_obs_l_pdafomicallback_obs_pdafomi.F90 init_dim_obs_l_pdafomi]: The name of the routine that initializes the size of the observation vector for a local analysis domain
     82 * [#prepoststep_pdafprepoststep_ens_pdaf.F90 prepoststep_pdaf]: The name of the pre/poststep routine as in `PDAF_init_forecast`
     83 * [#next_observation_pdafnext_observation.F90 next_observation_pdaf]: The name of a user supplied routine that initializes the variables `nsteps`, `timenow`, and `doexit`. The same routine is also used in `PDAF_init_forecast`.
    8484 * `status`: The integer status flag. It is zero, if the routine is exited without errors.
    8585
     
    130130
    131131
    132 === `U_collect_state` (collect_state_pdaf.F90) ===
     132=== `collect_state_pdaf` (collect_state_pdaf.F90) ===
    133133
    134134This routine is independent of the filter algorithm used.
    135135
    136 See the page on [InsertAnalysisStep#U_collect_statecollect_state_pdaf.F90 inserting the analysis step] for the description of this routine.
    137 
    138 
    139 === `U_distribute_state` (distribute_state_pdaf.F90) ===
     136See the page on [ModifyModelforEnsembleIntegration#collect_state_pdafcollect_state_pdaf.F90 modifying the model code for the ensemble integration] for the description of this routine.
     137
     138=== `distribute_state_pdaf` (distribute_state_pdaf.F90) ===
    140139
    141140This routine is independent of the filter algorithm used.
    142141
    143 See the page on [InsertAnalysisStep#U_distribute_statedistribute_state_pdaf.F90 inserting the analysis step] for the description of this routine.
    144 
    145 
    146 === `U_init_dim_obs_pdafomi` (callback_obs_pdafomi.F90) ===
    147 
    148 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.
    149 
    150 See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
    151 
    152 
    153 
    154 === `U_obs_op_pdafomi` (callback_obs_pdafomi.F90) ===
    155 
    156 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.
    157 
    158 See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
    159 
    160 
    161 
    162 
    163 === `U_cvt_ens` (cvt_ens_pdaf.F90) ===
     142See the page on [ModifyModelforEnsembleIntegration#distribute_state_pdafdistribute_state_pdaf.F90 modifying the model code for the ensemble integration] for the description of this routine.
     143
     144
     145
     146=== `init_dim_obs_pdafomi` (callback_obs_pdafomi.F90) ===
     147
     148This is a call-back routine initializing the observation information. The routine just calls a routine from the observation module for each observation type.
     149
     150See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
     151
     152
     153
     154=== `obs_op_pdafomi` (callback_obs_pdafomi.F90) ===
     155
     156This is a call-back routine applying the observation operator to the state vector. The routine calls a routine from the observation module for each observation type.
     157
     158See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
     159
     160
     161
     162=== `cvt_ens_pdaf` (cvt_ens_pdaf.F90) ===
    164163
    165164The interface for this routine is:
     
    182181
    183182
    184 === `U_cvt_adj` (cvt_adj_pdaf.F90) ===
     183=== `cvt_adj_pdaf` (cvt_adj_pdaf.F90) ===
    185184
    186185The interface for this routine is:
     
    204203
    205204
    206 === `U_cvt` (cvt_pdaf.F90) ===
     205=== `cvt_pdaf` (cvt_pdaf.F90) ===
    207206
    208207The interface for this routine is:
     
    223222
    224223
    225 === `U_cvt_adj` (cvt_adj_pdaf.F90) ===
     224=== `cvt_adj_pdaf` (cvt_adj_pdaf.F90) ===
    226225
    227226The interface for this routine is:
     
    244243
    245244
    246 === `U_obs_op_lin_pdafomi` (callback_obs_pdafomi.F90) ===
     245=== `obs_op_lin_pdafomi` (callback_obs_pdafomi.F90) ===
    247246
    248247This is a call-back routine for PDAF-OMI applying the linearized observation operator to the state vector. The routine calls a routine from the observation module for each observation type. If the full observation operator is lineaer the same operator can be used here.
     
    251250
    252251
    253 === `U_obs_op_adj_pdafomi` (callback_obs_pdafomi.F90) ===
     252=== `obs_op_adj_pdafomi` (callback_obs_pdafomi.F90) ===
    254253
    255254This is a call-back routine for PDAF-OMI applying the adjoint observation operator to some vector inthe observation space. The routine calls a routine from the observation module for each observation type.
     
    259258
    260259
    261 === `U_init_n_domains` (init_n_domains_pdaf.F90) ===
    262 
    263 The interface for this routine is:
    264 {{{
    265 SUBROUTINE init_n_domains(step, n_domains_p)
     260=== `init_n_domains_pdaf` (init_n_domains_pdaf.F90) ===
     261
     262This routine is only used for localization. It is called during the analysis step before the loop over the local analysis domains is entered. It has to provide the number of local analysis domains. In case of a domain-decomposed model, the number of local analysis domain for the model sub-domain of the calling process has to be initialized.
     263
     264The interface for this routine is:
     265{{{
     266SUBROUTINE init_n_domains_pdaf(step, n_domains_p)
    266267
    267268  INTEGER, INTENT(in)  :: step        ! Current time step
     
    269270}}}
    270271
    271 The routine is called during the analysis step before the loop over the local analysis domains is entered.
    272 It has to provide the number of local analysis domains. In case of a domain-decomposed model the number of local analysis domain for the model sub-domain of the calling process has to be initialized.
    273 
    274272Hints:
    275  * As a simple case, if the localization is only performed horizontally, the local analysis domains can be single vertical columns of the model grid. In this case, `n_domains_p` is simply the number of vertical columns in the local model sub-domain.
    276 
    277 
    278 
    279 
    280 === `U_init_dim_l` (init_dim_l_pdaf.F90) ===
    281 
    282 The interface for this routine is:
    283 {{{
    284 SUBROUTINE init_dim_l(step, domain_p, dim_l)
     273 * As a simple case, if the localization is only performed horizontally, the local analysis domains can be single vertical columns of the model grid. In this case, `n_domains_p` is simply the number of vertical columns in the process-local model sub-domain.
     274
     275
     276=== `init_dim_l_pdaf` (init_dim_l_pdaf.F90) ===
     277
     278This routine is only used for localization.
     279
     280The interface for this routine is:
     281{{{
     282SUBROUTINE init_dim_l_pdaf(step, domain_p, dim_l)
    285283
    286284  INTEGER, INTENT(in)  :: step        ! Current time step
     
    290288
    291289The routine is called during the loop over the local analysis domains in the analysis step.
    292 For PDAF it has to provide in `dim_l` the dimension of the state vector for the local analysis domain with index `domain_p`.
    293 
    294 In addition, for PDAFlocal the routine has to provide the index array containing the indices of the elements of the local state vector in the global (or domain-decomposed) state vector to PDAFlocal by calling `PDAFlocal_set_indices`. (in the template files, this array is called `id_lstate_in_pstate`)
     290
     291It provides in `dim_l` the dimension of the state vector for the local analysis domain with index `domain_p` to PDAF.
     292
     293In the recommended implementation shown in the tutorial and template codes, there are two further initializations:
     2941. The routine has initialize the index array `id_lstate_in_pstate` containing the indices of the elements of the local state vector in the global (or domain-decomposed) state vector. Then it has to provide this array to PDAF by calling `PDAFlocal_set_indices` (see below).
     2952. The routine initializes an array `coords_l` containing the coordinates of the local analysis domain. This is shared with `U_init_dim_obs_l_pdafomi` via the module `mod_assimilation`.
    295296
    296297Hints:
    297  * For sharing through the module `mod_assimilation`, we further initialize an array `coords_l` containing the coordinates that describe the local domain.
    298   * These coordinates have to describe one location in space that is used in the OMI observation modules to compute the distance from observations.
     298  * The coordinates in `coords_l` have to describe one location in space that is used for localization to compute the distance from observations.
    299299  * The coordinates in `coords_l` have the same units as those used for the observations
    300300  * For geographic distance computations, the unit of the coordinates needs to be radian, thus (0, 2*pi) or (-pi,pi) for longitude and (-pi/2, pi/2) for latitude.
     
    305305   * In this case only the horizontal coordinates are used in `coords_l`.
    306306
    307 The index array `id_lstate_in_pstate` is an integer array in form of a one-dimensional vector. One initializes this vector by determining the indices of the elements of the local state vector in the global, or domain decomposed, state vector. After initializing `id_lstate_in_pstate`, one has to provided it to PDAFlocal by calling `PDAFlocal_set_indices'. The interface interface is:
     307The index array `id_lstate_in_pstate` is an integer array in form of a one-dimensional vector. One initializes this vector by determining the indices of the elements of the local state vector in the global, or domain decomposed, state vector. After initializing `id_lstate_in_pstate`, one has to provided it to PDAF by calling `PDAFlocal_set_indices'. The interface interface is:
    308308
    309309{{{
     
    319319
    320320
    321 === `U_init_dim_obs_l_pdafomi` (callback_obs_pdafomi.F90) ===
    322 
    323 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.
    324 
    325 See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
    326 
    327 
    328 === `U_prepoststep` (prepoststep_ens_pdaf.F90) ===
     321=== `init_dim_obs_l_pdafomi` (callback_obs_pdafomi.F90) ===
     322
     323This routine is only used for localization. It 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.
     324
     325See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
     326
     327
     328=== `prepoststep_pdaf` (prepoststep_ens_pdaf.F90) ===
    329329
    330330The routine has already been described for modifying the model for the ensemble integration and for inserting the analysis step.
    331331
    332 See the page on [InsertAnalysisStep#U_prepoststepprepoststep_ens_pdaf.F90 inserting the analysis step] for the description of this routine.
    333 
    334 
    335 === `U_next_observation` (next_observation_pdaf.F90) ===
     332See the page on [ModifyModelforEnsembleIntegration#distribute_state_pdafdistribute_state_pdaf.F90 modifying the model code for the ensemble integration] for the description of this routine.
     333
     334
     335=== `next_observation_pdaf` (next_observation_pdaf.F90) ===
    336336
    337337This routine is independent of the filter algorithm used.
    338338
    339 See the page on [InsertAnalysisStep#U_next_observationnext_observation_pdaf.F90 inserting the analysis step] for the description of this routine.
    340 
     339See the page on [ModifyModelforEnsembleIntegration#distribute_state_pdafdistribute_state_pdaf.F90 modifying the model code for the ensemble integration] for the description of this routine.
    341340
    342341== Execution order of user-supplied routines ==
    343342
    344 The user-supplied routines are essentially executed in the order they are listed in the interface to `PDAFomi_assimilate_3dvar`. The order can be important as some routines can perform preparatory work for later routines. For example, `U_init_dim_obs_pdafomi` prepares an index array that provides the information for executing the observation operator in `U_obs_op_pdafomi`. How this information is initialized is described in the documentation of OMI.
     343The user-supplied routines are executed in the order listed below.  The order can be important as some routines can perform preparatory work for later routines. For example, `init_dim_obs_pdafomi` prepares an index array that provides the information for executing the observation operator in `obs_op_pdafomi`. How this information is initialized is described in the documentation of OMI.
    345344
    346345Before the analysis step is called the following routine is executed:
    347  1. [#U_collect_statecollect_state_pdaf.F90 U_collect_state]
     346 1. [#collect_state_pdafcollect_state_pdaf.F90 collect_state_pdaf]
    348347
    349348The analysis step is executed when the ensemble integration of the forecast is completed. During the analysis step the following routines are executed in the given order:
    350  1. [#U_prepoststepprepoststep_ens_pdaf.F90 U_prepoststep] (Call to act on the forecast ensemble, called with negative value of the time step)
    351  1. [#U_init_dim_obs_pdafomicallback_obs_pdafomi.F90 U_init_dim_obs_pdafomi]
    352  1. [#U_obs_op_pdafomicallback_obs_pdafomi.F90 U_obs_op_pdafomi] (multiple calls, one for each ensemble member)
     349 1. [#prepoststep_pdafprepoststep_ens_pdaf.F90 prepoststep_pdaf] (Call to act on the forecast ensemble, called with negative value of the time step)
     350 1. [#init_dim_obs_pdafomicallback_obs_pdafomi.F90 init_dim_obs_pdafomi]
     351 1. [#obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_pdafomi] (multiple calls, one for each ensemble member)
    353352
    354353Inside the analysis step the interative optimization is computed. This involves the repeated call of the routines:
    355  1. [#U_cvtcvt_pdaf.F90 U_cvt]
    356  1. [#U_cvt_enscvt_ens_pdaf.F90 U_cvt_ens]
    357  1. [#U_obs_op_lin_pdafomicallback_obs_pdafomi.F90 U_obs_op_lin_pdafomi]
    358  1. [#U_obs_op_adj_pdafomicallback_obs_pdafomi.F90 U_obs_op_adj_pdafomi]
    359  1. [#U_cvt_adjcvt_adj_pdaf.F90 U_cvt_adj]
    360  1. [#U_cvt_adj_enscvt_adj_ens_pdaf.F90 U_cvt_adj_ens]
     354 1. [#cvt_pdafcvt_pdaf.F90 cvt_pdaf]
     355 1. [#cvt_ens_pdafcvt_ens_pdaf.F90 cvt_ens_pdaf]
     356 1. [#obs_op_lin_pdafomicallback_obs_pdafomi.F90 U_obs_op_lin_pdafomi]
     357 1. [#obs_op_adj_pdafomicallback_obs_pdafomi.F90 U_obs_op_adj_pdafomi]
     358 1. [#cvt_adj_pdafcvt_adj_pdaf.F90 cvt_adj_pdaf]
     359 1. [#cvt_adj_ens_pdafcvt_adj_ens_pdaf.F90 cvt_adj_ens_pdaf]
    361360
    362361After the iterative optimization the following routines are executes to complte the analysis step:
    363  1. [#U_cvt_enscvt_pdaf.F90 U_cvt] (Call to the parameterized part of the control vector transform to compute the final state vector increment)
    364  1. [#U_cvt_enscvt_ens_pdaf.F90 U_cvt_ens] (Call to the eensemble-part of the control vector transform to compute the final state vector increment)
    365  1. [#U_prepoststepprepoststep_ens_pdaf.F90 U_prepoststep] (Call to act on the analysis ensemble, called with (positive) value of the time step)
    366 
    367 The iterative optimization abovve computes an updated ensemble mean state. Subsequently, the ensemble perturbations are updated using the LESTKF or ESTKF. The execution of the routines for these filters is described for the LESTKF on the [wiki:ImplementAnalysisLocal page on implementing the local filter analysis step] and for the ESTKF on the [wiki:ImplementAnalysisGlobal page on implementing the global filter analysis step].
    368 
    369 In case of the routine `PDAFomi_assimilate_*`, the following routines are executed after the analysis step:
    370  1. [#U_distribute_statedistribute_state_pdaf.F90 U_distribute_state]
    371  1. [#U_next_observationnext_observation_pdaf.F90 U_next_observation]
     362 1. [#cvt_enscvt_pdaf.F90 U_cvt] (Call to the parameterized part of the control vector transform to compute the final state vector increment)
     363 1. [#cvt_enscvt_ens_pdaf.F90 U_cvt_ens] (Call to the eensemble-part of the control vector transform to compute the final state vector increment)
     364 1. [#prepoststepprepoststep_ens_pdaf.F90 U_prepoststep] (Call to act on the analysis ensemble, called with (positive) value of the time step)
     365
     366The iterative optimization abovve computes an updated ensemble mean state. Subsequently, the ensemble perturbations are updated using the LESTKF or ESTKF. The execution of the routines for these filters is described on the [wiki:ImplementAnalysisPDAF3Universal page on implementing the local filter analysis step] .
     367
     368In case of the routine `PDAF3_assimilate_3dvar_all`, the following routines are executed after the analysis step:
     369 1. [#distribute_state_pdafdistribute_state_pdaf.F90 distribute_state_pdaf]
     370 1. [#next_observation_pdafnext_observation_pdaf.F90 next_observation_pdaf]