Changes between Version 1 and Version 2 of ImplementAnalysisPDAF3UniversalLocal


Ignore:
Timestamp:
May 24, 2025, 6:09:26 PM (8 days ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • ImplementAnalysisPDAF3UniversalLocal

    v1 v2  
    1212<li><a href="ImplementAnalysisPDAF3Universal">Universal interface</a></li>
    1313<li>Universal interface using g2l/l2g_state</li>
    14 <li><a href="ImplementAnalysisPDAF3UniversalGlobal">Interface for all global filters</a></li>
     14<li><a href="ImplementAnalysisPDAF3UniversalGlobal">Specific Interface for global filters</a></li>
    1515</ol>
    1616<li> <a href="Implement3DVarAnalysisOverview"> General overview for 3D-Var methods</a></li>
    … …  
    4949This 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)
    5050
    51 The interface for the routine `PDAF3_assimilate` contains names for routines that operate on the local analysis domains (marked by the suffix `_l`).
     51The interface for the routine `PDAF3_assimilate_local` contains names for routines that operate on the local analysis domains (marked by the suffix `_l`).
    5252Here, we list the full interface of the routine. Subsequently, the user-supplied routines specified in the call are explained.
    5353
    5454The interface when using one of the local filters is the following:
    5555{{{
    56   SUBROUTINE PDAF3_assimilate(U_collect_state, U_distribute_state, &
    57                               U_init_dim_obs_pdafomi, U_obs_op_pdafomi, &
    58                               U_init_n_domains, U_init_dim_l, U_init_dim_obs_l_pdafomi, &
    59                               U_gel_state, U_l2g_state, &
    60                               U_prepoststep, U_next_observation, status)
     56  SUBROUTINE PDAF3_assimilate(collect_state_pdaf, distribute_state_pdaf, &
     57                init_dim_obs_pdafomi, obs_op_pdafomi, &
     58                init_n_domains_pdaf, init_dim_l_pdaf, init_dim_obs_l_pdafomi, &
     59                g2l_state_pdaf, l2g_state_pdaf, &
     60                prepoststep_pdaf, next_observation_pdaf, status)
    6161}}}
    6262with the following arguments:
    6363* Routines to transfer between model fields and state vector:
    64  * [#U_collect_statecollect_state_pdaf.F90 U_collect_state]:[[BR]] 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 `U_distribute_state` used in [ModifyModelforEnsembleIntegration#PDAF_init_forecast PDAF_init_forecast] and also here.
    65  * [#U_distribute_statedistribute_state_pdaf.F90 U_distribute_state]:[[BR]]  The name of a user supplied routine that initializes the model fields from the array holding the ensemble of model state vectors.
     64 * [#collect_state_pdafcollect_state_pdaf.F90 collect_state_pdaf]:[[BR]] 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.
     65 * [#distribute_state_pdafdistribute_state_pdaf.F90 distribute_state_pdaf]:[[BR]]  The name of a user supplied routine that initializes the model fields from the array holding the ensemble of model state vectors. (The same routine is also used in `PDAF_init_forecast`.)
    6666* Observation routines using PDAF-OMI:
    67  * [#U_init_dim_obs_pdafomicallback_obs_pdafomi.F90 U_init_dim_obs_pdafomi]:[[BR]] The name of the user-supplied routine that initializes the observation information and provides the size of observation vector
    68  * [#U_obs_op_pdafomicallback_obs_pdafomi.F90 U_obs_op_pdafomi]:[[BR]] The name of the user-supplied routine that acts as the observation operator on some state vector
     67 * [#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
     68 * [#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
    6969* Routines only used for localization:
    70  * [#U_init_n_domainsinit_n_domains_pdaf.F90 U_init_n_domains]:[[BR]] The name of the routine that provides the number of local analysis domains
    71  * [#U_init_dim_linit_dim_l_pdaf.F90 U_init_dim_l]:[[BR]] The name of the routine that provides the state dimension for a local analysis domain
    72  * [#U_init_dim_obs_l_pdafomicallback_obs_pdafomi.F90 U_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.
     70 * [#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
     71 * [#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
     72 * [#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.
     73 * [#g2l_state_pdafg2l_state_pdaf.F90 g2l_state_pdaf]: The name of the routine that initializes a local state vector from the global state vector
     74 * [#l2g_state_pdafl2g_state_pdaf.F90 l2g_state_pdaf]: The name of the routine that initializes the corresponding part of the global state vector from the provided local state vector
    7375* Prepoststep and initialization for next forecast phase
    74  * [#U_prepoststepprepoststep_ens_pdaf.F90 U_prepoststep]:[[BR]] The name of the pre/poststep routine as in `PDAF_init_forecast`
    75  * [#U_next_observationnext_observation.F90 U_next_observation]:[[BR]] 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`.
     76 * [#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`.)
     77 * [#next_observation_pdafnext_observation.F90 next_observation_pdaf]:[[BR]] 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`.)
    7678* Status flag
    7779 * `status`:[[BR]] The integer status flag. It is zero, if the routine is exited without errors.
    … …  
    8183 
    8284
    83 === `PDAF3_assim_offline` ===
    84 
    85 For the offline mode of PDAF, the routine `PDAF3_assim_offline` is used to perform the analysis step.
    86 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.
     85=== `PDAF3_assim_offline_local` ===
     86
     87For the offline mode of PDAF, the routine `PDAF3_assim_offline_local` is used to perform the analysis step.
     88The interface of the routine is identical with that of `PDAF3_assimilate_local`, except that the user-supplied routines `U_distribute_state`, `U_collect_state` and `U_next_observation` are missing.
    8789
    8890The interface is:
    8991{{{
    90   SUBROUTINE PDAF3_assim_offline( &
    91              U_init_dim_obs_pdafomi, U_obs_op_pdafomi, &
    92              U_init_n_domains, U_init_dim_l, U_init_dim_obs_l_pdafomi, &
    93              U_prepoststep, status)
    94 }}}
    95 
    96 
    97 
    98 
    99 === `PDAF3_put_state` ===
     92  SUBROUTINE PDAF3_assim_offline_local( &
     93                init_dim_obs_pdafomi, obs_op_pdafomi, &
     94                init_n_domains_pdaf, init_dim_l_pdaf, init_dim_obs_l_pdafomi, &
     95                g2l_state_pdaf, l2g_state_pdaf, &
     96                prepoststep_pdaf, status)
     97}}}
     98
     99
     100
     101
     102=== `PDAF3_put_state_local` ===
    100103
    101104This 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.
    102 When 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.
    103 The interface of the routine is identical with that of `PDAF3_assimilate`, except that the user-supplied routines `U_distribute_state` and `U_next_observation` are missing.
     105When the 'flexible' implementation variant is chosen for the assimilation system, the routine. The routine `PDAF3_put_state_local` allows to port such implemnetations to the PDAF3 interface with minimal changes.
     106The 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.
    104107
    105108The interface when using one of the local filters is the following:
    106109{{{
    107   SUBROUTINE PDAF3_put_state(U_collect_state, &
    108                              U_init_dim_obs_pdafomi, U_obs_op_pdafomi, &
    109                              U_init_n_domains, U_init_dim_l, U_init_dim_obs_l_pdafomi, &
    110                              U_prepoststep, status)
    111 }}}
    112 
    113  * If your code shows a call to `PDAFomi_put_state_local`, it uses the implementation variant without PDAFlocal. This is documented on the page on [wiki:ImplementAnalysisLocal Implementing the Analysis Step for the Local Filters with OMI without PDAFlocal (until V2.2.1 of PDAF)].
     110  SUBROUTINE PDAF3_put_state_local(collect_state_pdaf, &
     111                init_dim_obs_pdafomi, obs_op_pdafomi, &
     112                init_n_domains_pdaf, init_dim_l_pdaf, init_dim_obs_l_pdafomi, &
     113                g2l_state_pdaf, l2g_state_pdaf, &
     114                prepoststep_pdaf, status)
     115}}}
     116
    114117
    115118== User-supplied routines ==
    116119
    117 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].
    118 
    119 To indicate user-supplied routines we use the prefix `U_`. In the tutorials in `tutorial/` and in the template directory `templates/` these routines exist without the prefix, but with the extension `_pdaf`. The files are named correspondingly. 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.
     120Here, all user-supplied routines are described that are required in the call to `PDAF3_assimilate_local`, `PDAF3_assim_offline_local` or `PDAF3_put_state_local`. For some of the generic routines, we link to the page on [ModifyModelforEnsembleIntegration modifying the model code for the ensemble integration].
    120121
    121122In 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').
    122123
    123124
    124 === `U_collect_state` (collect_state_pdaf.F90) ===
     125=== `collect_state_pdaf` (collect_state_pdaf.F90) ===
    125126
    126127This routine is independent of the filter algorithm used.
    … …  
    128129See the page on [ModifyModelforEnsembleIntegration#collect_state_pdafcollect_state_pdaf.F90 modifying the model code for the ensemble integration] for the description of this routine.
    129130
    130 === `U_distribute_state` (distribute_state_pdaf.F90) ===
     131=== `distribute_state_pdaf` (distribute_state_pdaf.F90) ===
    131132
    132133This routine is independent of the filter algorithm used.
    … …  
    135136
    136137
    137 === `U_init_dim_obs_pdafomi` (callback_obs_pdafomi.F90) ===
     138=== `init_dim_obs_pdafomi` (callback_obs_pdafomi.F90) ===
    138139
    139140This is a call-back routine initializing the observation information. The routine just calls a routine from the observation module for each observation type.
    … …  
    143144
    144145
    145 === `U_obs_op_pdafomi` (callback_obs_pdafomi.F90) ===
     146=== `obs_op_pdafomi` (callback_obs_pdafomi.F90) ===
    146147
    147148This 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.
    … …  
    150151
    151152
    152 === `U_init_n_domains` (init_n_domains_pdaf.F90) ===
     153=== `init_n_domains_pdaf` (init_n_domains_pdaf.F90) ===
    153154
    154155This 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.
    … …  
    156157The interface for this routine is:
    157158{{{
    158 SUBROUTINE init_n_domains(step, n_domains_p)
     159SUBROUTINE init_n_domains_pdaf(step, n_domains_p)
    159160
    160161  INTEGER, INTENT(in)  :: step        ! Current time step
    … …  
    166167
    167168
    168 === `U_init_dim_l` (init_dim_l_pdaf.F90) ===
     169=== `init_dim_l_pdaf` (init_dim_l_pdaf.F90) ===
    169170
    170171This routine is only used for localization.
    … …  
    172173The interface for this routine is:
    173174{{{
    174 SUBROUTINE init_dim_l(step, domain_p, dim_l)
     175SUBROUTINE init_dim_l_pdaf(step, domain_p, dim_l)
    175176
    176177  INTEGER, INTENT(in)  :: step        ! Current time step
    … …  
    211212
    212213
    213 === `U_init_dim_obs_l_pdafomi` (callback_obs_pdafomi.F90) ===
     214=== `init_dim_obs_l_pdafomi` (callback_obs_pdafomi.F90) ===
    214215
    215216This 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.
    … …  
    217218See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
    218219
    219 === `U_g2l_state` (g2l_state_pdaf.F90) ===
     220=== `g2l_state_pdaf` (g2l_state_pdaf.F90) ===
    220221
    221222The interface for this routine is:
    222223{{{
    223 SUBROUTINE g2l_state(step, domain_p, dim_p, state_p, dim_l, state_l)
     224SUBROUTINE g2l_state_pdaf(step, domain_p, dim_p, state_p, dim_l, state_l)
    224225
    225226  INTEGER, INTENT(in) :: step           ! Current time step
    … …  
    235236Hints:
    236237 * 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`.
    237  * Usually, one can use the index array `id_lstate_in_pstate`, which is initialized in `U_init_dim_l`. The array holds the indices of the local state vector elements in the global state vector.
    238 
    239 
    240 === `U_l2g_state` (l2g_state_pdaf.F90) ===
     238 * Usually, one can use the index array `id_lstate_in_pstate`, which is initialized in `init_dim_l_pdaf`. The array holds the indices of the local state vector elements in the global state vector.
     239
     240
     241=== `l2g_state_pdaf` (l2g_state_pdaf.F90) ===
    241242
    242243The interface for this routine is:
    243244{{{
    244 SUBROUTINE l2g_state(step, domain_p, dim_l, state_l, dim_p, state_p)
     245SUBROUTINE l2g_state_pdaf(step, domain_p, dim_l, state_l, dim_p, state_p)
    245246
    246247  INTEGER, INTENT(in) :: step           ! Current time step
    … …  
    256257Hints:
    257258 * 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`.
    258  * Usually, one can use the index array `id_lstate_in_pstate`, which is initialized in `U_init_dim_l`. The array holds the indices of the local state vector elements in the global state vector.
    259 
    260 
    261 === `U_prepoststep` (prepoststep_ens_pdaf.F90) ===
     259 * Usually, one can use the index array `id_lstate_in_pstate`, which is initialized in `init_dim_l_pdaf`. The array holds the indices of the local state vector elements in the global state vector.
     260
     261
     262=== `prepoststep_pdaf` (prepoststep_ens_pdaf.F90) ===
    262263
    263264The routine has already been described for modifying the model for the ensemble integration and for inserting the analysis step.
    … …  
    266267
    267268
    268 === `U_next_observation` (next_observation_pdaf.F90) ===
     269=== `next_observation_pdaf` (next_observation_pdaf.F90) ===
    269270
    270271This routine is independent of the filter algorithm used.