Changes between Version 14 and Version 15 of ImplementAnalysis_3DEnVar


Ignore:
Timestamp:
Sep 19, 2024, 2:36:34 PM (9 hours ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • ImplementAnalysis_3DEnVar

    v14 v15  
    2121<li><a href="ImplementAnalysis_3DVar">Implementation for 3D-Var</a></li>
    2222<li>Implementation for 3D Ensemble Var</li>
     23<li><a href="ImplementAnalysis_3DEnVar_untilPDAF221">Implementation for 3D Ensemble Var without PDAFlocal</li>
    2324<li><a href="ImplementAnalysis_Hyb3DVar">Implementation for Hybrid 3D-Var</a></li>
    2425</ol>
    … …  
    3637== Overview ==
    3738
    38 With Version 2.0 with introduced 3D variational assimilation methods to PDAF. There are genenerally three different variants: parameterized 3D-Var, 3D Ensemble Var, and hybrid (parameterized + ensemble) 3D-Var.
     39This page describes the recommended implementation of the analysis step of local filters with OMI using the PDAFlocal interface that was introduced with PDAF V2.3. The older approach calling PDAFomi_assimilate_local or PDAFomi_put_state_local is documented on the page on [wiki:ImplementAnalysis_3DEnVar_untilPDAF221 Implementing the Analysis Step for 3D Ensemble Var with OMI without PDAFlocal (until V2.2.1 of PDAF)].
     40
     41There are genenerally three different variants: parameterized 3D-Var, 3D Ensemble Var, and hybrid (parameterized + ensemble) 3D-Var.
    3942
    4043This page describes the implementation of the analysis step for the 3D Ensemble Var using PDAF-OMI.
    … …  
    5356There are two variants that either compute the transformataion of the ensemble transformation using the local LESTKF method, or the global ESTKF.
    5457
    55 === `PDAFomi_assimilate_en3dvar_lestkf` ===
     58=== `PDAFlocalomi_assimilate_en3dvar_lestkf` ===
    5659
    5760This routine is called for the case of transforming the ensemble perturbations using the local LESTKF.
    … …  
    5962The interface is:
    6063{{{
    61 SUBROUTINE PDAFomi_assimilate_en3dvar_lestkf(U_collect_state, U_distribute_state, &
     64SUBROUTINE PDAFlocalomi_assimilate_en3dvar_lestkf(U_collect_state, U_distribute_state, &
    6265                                 U_init_dim_obs_pdafomi, U_obs_op_pdafomi, &
    6366                                 U_cvt_ens, U_cvt_adj_ens, U_obs_op_lin_pdafomi, U_obs_op_adj_pdafomi, &
    6467                                 U_init_n_domains_p, U_init_dim_l, U_init_dim_obs_l_pdafomi, &
    65                                  U_g2l_state, U_l2g_state, U_prepoststep, U_next_observation, outflag)
     68                                 U_prepoststep, U_next_observation, outflag)
    6669}}}
    6770with the following arguments:
    … …  
    7780 * [#U_init_dim_linit_dim_l_pdaf.F90 U_init_dim_l]: The name of the routine that provides the state dimension for a local analysis domain
    7881 * [#U_init_dim_obs_l_pdafomicallback_obs_pdafomi.F90 U_init_dim_obs_l_pdafomi]: The name of the routine that initializes the size of the observation vector for a local analysis domain
    79  * [#U_g2l_stateg2l_state_pdaf.F90 U_g2l_state]: The name of the routine that initializes a local state vector from the global state vector
    80  * [#U_l2g_statel2g_state_pdaf.F90 U_l2g_state]: The name of the routine that initializes the corresponding part of the global state vector from the provided local state vector
    8182 * [#U_prepoststepprepoststep_ens_pdaf.F90 U_prepoststep]: The name of the pre/poststep routine as in `PDAF_get_state`
    8283 * [#U_next_observationnext_observation.F90 U_next_observation]: The name of a user supplied routine that initializes the variables `nsteps`, `timenow`, and `doexit`. The same routine is also used in `PDAF_get_state`.
    8384 * `status`: The integer status flag. It is zero, if the routine is exited without errors.
    8485
    85 
     86Note:
     87 * If your code shows a call to `PDAFomi_assimilate_en3dvar_lestkf`, it uses the implementation variant without PDAFlocal. This is documented on the page on [wiki:ImplementAnalysis_3DEnVar_untilPDAF221 Implementing the Analysis Step for 3D Ensemble Var with OMI without PDAFlocal (until V2.2.1 of PDAF)].
    8688
    8789=== `PDAFomi_assimilate_en3dvar_estkf` ===
    … …  
    112114
    113115
    114 === `PDAFomi_put_state_en3dvar_lestkf` ===
     116=== `PDAFlocalomi_put_state_en3dvar_lestkf` ===
    115117
    116118When the 'flexible' implementation variant is chosen for the assimilation system, the routine `PDAFomi_put_state_*` has to be used instead of `PDAFomi_assimilate_*`. The general aspects of the filter specific routines `PDAF_put_state_*` have been described on the page [ModifyModelforEnsembleIntegration Modification of the model code for the ensemble integration]. The interface of the routine is identical with that of `PDAF_assimilate_*` with the exception the specification of the user-supplied routines `U_distribute_state` and `U_next_observation` are missing.
    … …  
    122124                                 U_cvt_ens, U_cvt_adj_ens, U_obs_op_lin_pdafomi, U_obs_op_adj_pdafomi, &
    123125                                 U_init_n_domains_p, U_init_dim_l, U_init_dim_obs_l_pdafomi, &
    124                                  U_g2l_state, U_l2g_state, U_prepoststep, outflag)
    125 }}}
     126                                 U_prepoststep, outflag)
     127}}}
     128
     129Note:
     130 * If your code shows a call to `PDAFomi_put_state_en3dvar_lestkf`, it uses the implementation variant without PDAFlocal. This is documented on the page on [wiki:ImplementAnalysis_3DEnVar_untilPDAF221 Implementing the Analysis Step for 3D Ensemble Var with OMI without PDAFlocal (until V2.2.1 of PDAF)].
    126131
    127132=== `PDAFomi_put_state_en3dvar_estkf` ===
    … …  
    252257
    253258
     259
     260
    254261=== `U_init_dim_l` (init_dim_l_pdaf.F90) ===
    255262
    … …  
    264271
    265272The routine is called during the loop over the local analysis domains in the analysis step.
    266 It has to provide in `dim_l` the dimension of the state vector for the local analysis domain with index `domain_p`.
     273For PDAF it has to provide in `dim_l` the dimension of the state vector for the local analysis domain with index `domain_p`.
     274
     275In 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`)
    267276
    268277Hints:
    269  * For sharing through the module 'mod_assimilation', we further initialize an array 'coords_l' containing the coordinates that describe the local domain. These coordinates have to describe one location in space that is used in the OMI observation modules to compute the distance from observations. This requires that the coordinates in 'coords_l' have the same units as those used for the observations.
    270  * Any form of local domain is possible as long as it can be describe as a single location. If observations are only horizontally distributed (a common situation with satellite data in the ocean), the local analysis domain can be a single vertical column of the model grid. In this case, the size of the state in the local analysis domain will be just the number of vertical grid points at this location and the horizontal coordinates are used in 'coords_l'
    271  * Further, we recommend to initialize an array containing the indices of the elements of the local state vector in the global (or domain-decomposed) state vector (`id_lstate_in_pstate` in the template files). This array is also shared through 'mod_assimilation'.
     278 * For sharing through the module `mod_assimilation`, we further initialize an array `coords_l` containing the coordinates that describe the local domain.
     279  * These coordinates have to describe one location in space that is used in the OMI observation modules to compute the distance from observations.
     280  * The coordinates in `coords_l` have the same units as those used for the observations
     281  * 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.
     282 * Any form of local domain is possible as long as it can be describe as a single location.
     283  * If the local domain is a single grid point, `dim_l` will be the number of model variables at this grid point.
     284  * The local analysis domain can also be a single vertical column of the model grid if observations are only horizontally distributed (a common situation with satellite data in the ocean).
     285   * In this case, `dim_l` will be the number of vertical grid points at this location times the number of model fields that exist in the vertical, plus possible variables at e.g. the surface.
     286   * In this case only the horizontal coordinates are used in `coords_l`.
     287
     288The 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:
     289
     290{{{
     291SUBROUTINE PDAFlocal_set_indices(dim_l, id_lstate_in_pstate)
     292
     293  INTEGER, INTENT(in) :: dim_l                          ! Dimension of local state vector
     294  INTEGER, INTENT(in) :: id_lstate_in_pstate(dim_l)     ! Index array for mapping
     295}}}
     296
     297Hint for `id_lstate_in_pstate`:
     298 * The initialization of the index vector `id_lstate_to_pstate` is analogous to a loop that directly performs the initialization of a local state vector. However, here only the indices are stored.
     299 * See the [wiki:PDAFlocal_overview PDAFlocal overview page] for more information on the functionality of PDAFlocal.
    272300
    273301
    … …  
    277305
    278306See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
    279 
    280 
    281 === `U_g2l_state` (g2l_state_pdaf.F90) ===
    282 
    283 The interface for this routine is:
    284 {{{
    285 SUBROUTINE g2l_state(step, domain_p, dim_p, state_p, dim_l, state_l)
    286 
    287   INTEGER, INTENT(in) :: step           ! Current time step
    288   INTEGER, INTENT(in) :: domain_p       ! Current local analysis domain
    289   INTEGER, INTENT(in) :: dim_p          ! State dimension for model sub-domain
    290   INTEGER, INTENT(in) :: dim_l          ! Local state dimension
    291   REAL, INTENT(in)    :: state_p(dim_p) ! State vector for model sub-domain
    292   REAL, INTENT(out)   :: state_l(dim_l) ! State vector on local analysis domain
    293 }}}
    294 
    295 The routine is called during the loop over the local analysis domains in the analysis step. It has to provide the local state vector `state_l` that corresponds to the local analysis domain with index `domain_p`. Provided to the routine is the state vector `state_p`. With a domain decomposed model, this is the state for the local model sub-domain.
    296 
    297 Hints:
    298  * In the simple case that a local analysis domain is a single vertical column of the model grid, the operation in this routine would be to take out of `state_p` the data for the vertical column indexed by `domain_p`.
    299  * Usually, one can initialize the indices of the local state vector elements in the global state vector in `U_init_dim_l` and just use these here.
    300 
    301 
    302 === `U_l2g_state` (l2g_state_pdaf.F90) ===
    303 
    304 The interface for this routine is:
    305 {{{
    306 SUBROUTINE l2g_state(step, domain_p, dim_l, state_l, dim_p, state_p)
    307 
    308   INTEGER, INTENT(in) :: step           ! Current time step
    309   INTEGER, INTENT(in) :: domain_p       ! Current local analysis domain
    310   INTEGER, INTENT(in) :: dim_p          ! State dimension for model sub-domain
    311   INTEGER, INTENT(in) :: dim_l          ! Local state dimension
    312   REAL, INTENT(in)    :: state_p(dim_p) ! State vector for model sub-domain
    313   REAL, INTENT(out)   :: state_l(dim_l) ! State vector on local analysis domain
    314 }}}
    315 
    316 The routine is called during the loop over the local analysis domains in the analysis step. It has to initialize the part of the global state vector `state_p` that corresponds to the local analysis domain with index `domain_p`. Provided to the routine is the state vector `state_l` for the local analysis domain.
    317 
    318 Hints:
    319  * In the simple case that a local analysis domain is a single vertical column of the model grid, the operation in this routine would be to write into `state_p` the data for the vertical column indexed by `domain_p`.
    320  * Usually, one can initialize the indices of the local state vector elements in the global state vector in `U_init_dim_l` and just use these here.
    321 
    322307
    323308