Changes between Version 1 and Version 2 of ImplementanalysisPDAF3Global


Ignore:
Timestamp:
May 25, 2025, 12:05:49 PM (7 days ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • ImplementanalysisPDAF3Global

    v1 v2  
    4343== Assimilation routines ==
    4444
    45 === `PDAF3_assimilate` ===
     45=== `PDAF3_assimilate_global` ===
    4646
    4747This routine is used both in the ''fully-parallel'' and the ''flexible'' implementation variants of the data assimilation system. (See the page [ModifyModelforEnsembleIntegration Modification of the model code for the ensemble integration] for these variants)
    4848
    49 The interface for the routine `PDAF3_assimilate` contains names for routines that operate on the local analysis domains (marked by the suffix `_l`).
    5049Here, we list the full interface of the routine. Subsequently, the user-supplied routines specified in the call are explained.
    5150
    5251The unversal interface is the following:
    5352{{{
    54   SUBROUTINE PDAF3_assimilate(collect_state_pdaf, distribute_state_pdaf, &
     53  SUBROUTINE PDAF3_assimilate_global(collect_state_pdaf, distribute_state_pdaf, &
    5554                init_dim_obs_pdafomi, obs_op_pdafomi, &
    56                 init_n_domains_pdaf, init_dim_l_pdaf, init_dim_obs_l_pdafomi, &
    57                 g2l_state_pdaf, l2g_state_pdaf, &
    5855                prepoststep_pdaf, next_observation_pdaf, status)
    5956}}}
    … …  
    6562 * [#init_dim_obs_pdafomicallback_obs_pdafomi.F90 init_dim_obs_pdafomi]:[[BR]] The name of the user-supplied routine that initializes the observation information and provides the size of observation vector
    6663 * [#obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_pdafomi]:[[BR]] The name of the user-supplied routine that acts as the observation operator on some state vector
    67 * Routines only used for localization:
    68  * [#init_n_domains_pdafinit_n_domains_pdaf.F90 init_n_domains_pdaf]:[[BR]] The name of the routine that provides the number of local analysis domains
    69  * [#init_dim_l_pdafinit_dim_l_pdaf.F90 init_dim_l_pdaf]:[[BR]] The name of the routine that provides the state dimension for a local analysis domain
    70  * [#init_dim_obs_l_pdafomicallback_obs_pdafomi.F90 init_dim_obs_l_pdafomi]:[[BR]] The name of the routine that initializes the size of the observation vector for a local analysis domain and the index arrays used to map between the global state vector and the local state vector.
    7164* Prepoststep and initialization for next forecast phase
    7265 * [#prepoststep_pdafprepoststep_ens_pdaf.F90 prepoststep_pdaf]:[[BR]] The name of the pre/poststep routine as in `PDAF_init_forecast`. (The same routine is also used in `PDAF_init_forecast`.)
    … …  
    7972 
    8073
    81 === `PDAF3_assim_offline` ===
     74=== `PDAF3_assim_offline_global` ===
    8275
    83 For the offline mode of PDAF, the routine `PDAF3_assim_offline_local` is used to perform the analysis step.
    84 The interface of the routine is identical with that of `PDAF3_assimilate`, except that the user-supplied routines `U_distribute_state`, `U_collect_state` and `U_next_observation` are missing.
     76For the offline mode of PDAF, the routine `PDAF3_assim_offline_global` is used to perform the analysis step.
     77The interface of the routine is identical with that of `PDAF3_assimilate_global`, except that the user-supplied routines `U_distribute_state`, `U_collect_state` and `U_next_observation` are missing.
    8578
    8679The interface is:
    8780{{{
    88   SUBROUTINE PDAF3_assim_offline( &
     81  SUBROUTINE PDAF3_assim_offline_global( &
    8982                init_dim_obs_pdafomi, obs_op_pdafomi, &
    90                 init_n_domains_pdaf, init_dim_l_pdaf, init_dim_obs_l_pdafomi, &
    9183                prepoststep_pdaf, status)
    9284}}}
    … …  
    9587
    9688
    97 === `PDAF3_put_state` ===
     89=== `PDAF3_put_state_global` ===
    9890
    9991This routine exists for backward-compatibility. In implementations that were done before the release of PDAF V3.0, a 'put_state' routine was used for the `flexible` parallelization variant and for the offline mode.
    10092When the 'flexible' implementation variant is chosen for the assimilation system, the routine. The routine `PDAF3_put_state` allows to port such implemnetations to the PDAF3 interface with minimal changes.
    101 The interface of the routine is identical with that of `PDAF3_assimilate_local`, except that the user-supplied routines `U_distribute_state` and `U_next_observation` are missing.
     93The interface of the routine is identical with that of `PDAF3_assimilate_global`, except that the user-supplied routines `U_distribute_state` and `U_next_observation` are missing.
    10294
    10395The interface when using one of the local filters is the following:
    10496{{{
    105   SUBROUTINE PDAF3_put_state(collect_state_pdaf, &
     97  SUBROUTINE PDAF3_put_state_global(collect_state_pdaf, &
    10698                init_dim_obs_pdafomi, obs_op_pdafomi, &
    107                 init_n_domains_pdaf, init_dim_l_pdaf, init_dim_obs_l_pdafomi, &
    10899                prepoststep_pdaf, status)
    109100}}}
    … …  
    112103== User-supplied routines ==
    113104
    114 Here, all user-supplied routines are described that are required in the call to `PDAF3_assimilate`, `PDAF3_assim_offline` or `PDAF3_put_state`. For some of the generic routines, we link to the page on [ModifyModelforEnsembleIntegration modifying the model code for the ensemble integration].
     105Here, all user-supplied routines are described that are required in the call to `PDAF3_assimilate_global`, `PDAF3_assim_offline_global` or `PDAF3_put_state_global`. For some of the generic routines, we link to the page on [ModifyModelforEnsembleIntegration modifying the model code for the ensemble integration].
    115106
    116107In 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').
    … …  
    147138
    148139
    149 === `init_n_domains_pdaf` (init_n_domains_pdaf.F90) ===
    150140
    151 This 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.
    152 
    153 The interface for this routine is:
    154 {{{
    155 SUBROUTINE init_n_domains_pdaf(step, n_domains_p)
    156 
    157   INTEGER, INTENT(in)  :: step        ! Current time step
    158   INTEGER, INTENT(out) :: n_domains_p ! Number of analysis domains for local model sub-domain
    159 }}}
    160 
    161 Hints:
    162  * 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.
    163 
    164 
    165 === `init_dim_l_pdaf` (init_dim_l_pdaf.F90) ===
    166 
    167 This routine is only used for localization.
    168 
    169 The interface for this routine is:
    170 {{{
    171 SUBROUTINE init_dim_l_pdaf(step, domain_p, dim_l)
    172 
    173   INTEGER, INTENT(in)  :: step        ! Current time step
    174   INTEGER, INTENT(in)  :: domain_p    ! Current local analysis domain
    175   INTEGER, INTENT(out) :: dim_l       ! Local state dimension
    176 }}}
    177 
    178 The routine is called during the loop over the local analysis domains in the analysis step.
    179 
    180 It provides in `dim_l` the dimension of the state vector for the local analysis domain with index `domain_p` to PDAF.
    181 
    182 In the recommended implementation shown in the tutorial and template codes, there are two further initializations:
    183 1. 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).
    184 2. 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`.
    185 
    186 Hints:
    187   * The coordinates in `coords_l` have to describe one location in space that is used for localization to compute the distance from observations.
    188   * The coordinates in `coords_l` have the same units as those used for the observations
    189   * 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.
    190  * Any form of local domain is possible as long as it can be describe as a single location.
    191   * If the local domain is a single grid point, `dim_l` will be the number of model variables at this grid point.
    192   * 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).
    193    * 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.
    194    * In this case only the horizontal coordinates are used in `coords_l`.
    195 
    196 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 PDAF by calling `PDAFlocal_set_indices'. The interface interface is:
    197 
    198 {{{
    199 SUBROUTINE PDAFlocal_set_indices(dim_l, id_lstate_in_pstate)
    200 
    201   INTEGER, INTENT(in) :: dim_l                          ! Dimension of local state vector
    202   INTEGER, INTENT(in) :: id_lstate_in_pstate(dim_l)     ! Index array for mapping
    203 }}}
    204 
    205 Hint for `id_lstate_in_pstate`:
    206  * 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.
    207  * See the [wiki:PDAFlocal_overview PDAFlocal overview page] for more information on the functionality of PDAFlocal.
    208 
    209 
    210 === `init_dim_obs_l_pdafomi` (callback_obs_pdafomi.F90) ===
    211 
    212 This 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.
    213 
    214 See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
    215141
    216142
    … …  
    232158== Execution order of user-supplied routines ==
    233159
    234 The user-supplied routines are executed in the order listed below. The order can be important as some routines can perform preparatory work for routines executed later on during the analysis. For example, in `init_dim_l_pdaf` we can prepare the index array that provides the information how to localize a global state vector.
     160The user-supplied routines are executed in the order listed below. The order can be important as some routines can perform preparatory work for routines executed later on during the analysis.
    235161
    236162Before the analysis step is called the following is executed by `PDAF3_assimilate` and `PDAF3_put_state`:
    … …  
    242168 1. [#obs_op_pdadfomicallback_obs_pdafomi.F90 obs_op_pdafomi] (Called `dim_ens` times; once for each ensemble member)
    243169
    244 Now the analysis step is entered and the number of local analysis domain is initialized by calling:
    245  1. [#init_n_domains_pdafinit_n_domains_pdaf.F90 init_n_domains_pdaf]
    246 
    247 In the loop over all local analysis domains, it is executed for each local analysis domain:
    248  1. [#init_dim_l_pdafinit_dim_l_pdaf.F90 init_dim_l_pdaf]
    249  1. [#init_dim_obs_l_pdafomiinit_dim_obs_l_pdaf.F90 U_init_dim_obs_l_pdafomi]
    250 
    251 After the loop over all local analysis domains, it is executed:
     170Now the analysis step is entered. Afterwards, it is executed:
    252171 1. [#prepoststep_pdafprepoststep_ens_pdaf.F90 prepoststep_pdaf] (Call to act on the analysis ensemble, called with (positive) value of the time step)
    253172