Changes between Version 9 and Version 10 of ImplementAnalysisLocal


Ignore:
Timestamp:
Nov 24, 2020, 2:44:32 PM (6 months ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • ImplementAnalysisLocal

    v9 v10  
    3838The general aspects of the filter-specific routines `PDAF_assimilate_*` have been described on the page [ModifyModelforEnsembleIntegration Modification of the model code for the ensemble integration] and its sub-page on [InsertAnalysisStep inserting the analysis step].  The routine is used in the fully-parallel implementation variant of the data assimilation system. When the 'flexible' implementation variant is used, the routines `PDAF_put_state_*' is used as described further below.
    3939
    40 The interface for the routine `PDAFomi_assimilate_local` contains two routine names for routines that operate on the local analysis domains (marked by `_l` at the end of the routine name). Further there are routines that convert between a local and a global model state vector (`U_g2l_state` and `U_l2g_state`).
     40The interface for the routine `PDAFomi_assimilate_local` contains names for routines that operate on the local analysis domains (marked by the suffix `_l`). Further there are routines that convert between a local and a global model state vector (`U_g2l_state` and `U_l2g_state`).
    4141Here, we list the full interface of the routine. Subsequently, the user-supplied routines specified in the call is explained.
    4242
     
    4444{{{
    4545  SUBROUTINE PDAFomi_assimilate_local(U_collect_state, U_distribute_state, &
    46                                   U_init_dim_obs, U_obs_op, &
     46                                  U_init_dim_obs_pdafomi, U_obs_op_pdafomi, &
    4747                                  U_prepoststep, U_init_n_domains, U_init_dim_l, &
    48                                   U_init_dim_obs_l, U_g2l_state, U_l2g_state, &
     48                                  U_init_dim_obs_l_pdafomi, U_g2l_state, U_l2g_state, &
    4949                                  U_next_observation, status)
    5050}}}
     
    5252 * [#U_collect_statecollect_state_pdaf.F90 U_collect_state]: 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_get_state PDAF_get_state] and also here.
    5353 * [#U_distribute_statedistribute_state_pdaf.F90 U_distribute_state]:  The name of a user supplied routine that initializes the model fields from the array holding the ensemble of model state vectors.
    54  * [#U_init_dim_obscallback_obs_pdafomi.F90 U_init_dim_obs]: The name of the user-supplied routine that initializes the observation information and provides the size of observation vector
    55  * [#U_obs_opcallback_obs_pdafomi.F90 U_obs_op]: The name of the user-supplied routine that acts as the observation operator on some state vector
     54 * [#U_init_dim_obs_pdafomicallback_obs_pdafomi.F90 U_init_dim_obs_pdafomi]: The name of the user-supplied routine that initializes the observation information and provides the size of observation vector
     55 * [#U_obs_op_pdafomicallback_obs_pdafomi.F90 U_obs_op_pdafomi]: The name of the user-supplied routine that acts as the observation operator on some state vector
    5656 * [#U_prepoststepprepoststep_ens_pdaf.F90 U_prepoststep]: The name of the pre/poststep routine as in `PDAF_get_state`
    5757 * [#U_init_n_domainsinit_n_domains_pdaf.F90 U_init_n_domains]: The name of the routine that provides the number of local analysis domains
    5858 * [#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
    59  * [#U_init_dim_obs_lcallback_obs_pdafomi.F90 U_init_dim_obs_l]: The name of the routine that initializes the size of the observation vector for a local analysis domain
     59 * [#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
    6060 * [#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
    6161 * [#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
     
    7575{{{
    7676  SUBROUTINE PDAFomi_put_state_local(U_collect_state, &
    77                                   U_init_dim_obs, U_obs_op, &
     77                                  U_init_dim_obs_pdafomi, U_obs_op_pdafomi, &
    7878                                  U_prepoststep, U_init_n_domains, U_init_dim_l, &
    79                                   U_init_dim_obs_l, U_g2l_state, U_l2g_state, &
     79                                  U_init_dim_obs_l_pdafomi, U_g2l_state, U_l2g_state, &
    8080                                  status)
    8181}}}
     
    8585Here, all user-supplied routines are described that are required in the call to `PDAFomi_assimilate_local` or `PDAFomi_put_state_local`. For some of the generic routines, we link to the page on [ModifyModelforEnsembleIntegration modifying the model code for the ensemble integration].
    8686
    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').
     87To 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
     89In 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
    9091
    9192=== `U_collect_state` (collect_state_pdaf.F90) ===
    9293
    9394This routine is independent of the filter algorithm used.
     95
    9496See the page on [InsertAnalysisStep#U_collect_statecollect_state_pdaf.F90 inserting the analysis step] for the description of this routine.
    9597
     98
    9699=== `U_distribute_state` (distribute_state_pdaf.F90) ===
    97100
    98101This routine is independent of the filter algorithm used.
     102
    99103See the page on [InsertAnalysisStep#U_distribute_statedistribute_state_pdaf.F90 inserting the analysis step] for the description of this routine.
    100104
    101105
    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
     108This 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
     110See 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
     116This 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
     118See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
    133119
    134120
    135121=== `U_prepoststep` (prepoststep_ens_pdaf.F90) ===
    136122
    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])
     123The routine has already been described for modifying the model for the ensemble integration and for inserting the analysis step.
     124
     125See the page on [InsertAnalysisStep#U_prepoststepprepoststep_ens_pdaf.F90 inserting the analysis step] for the description of this routine.
     126
    169127
    170128
     
    204162
    205163
    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
     166This 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
     168See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
    222169
    223170
     
    267214
    268215This routine is independent of the filter algorithm used.
     216
    269217See the page on [InsertAnalysisStep#U_next_observationnext_observation_pdaf.F90 inserting the analysis step] for the description of this routine.
    270218
     
    280228 1. [#U_prepoststepprepoststep_ens_pdaf.F90 U_prepoststep] (Call to act on the forecast ensemble, called with negative value of the time step)
    281229 1. [#U_init_n_domainsinit_n_domains_pdaf.F90 U_init_n_domains]
    282  1. [#U_init_dim_obsback_obs_pdafomi.F90 U_init_dim_obs]
    283  1. [#U_obs_opcallback_obs_pdafomi.F90 U_obs_op] (Called `dim_ens` times; once for each ensemble member)
     230 1. [#U_init_dim_obs_pdafomicallback_obs_pdafomi.F90 U_init_dim_obs_pdafomi]
     231 1. [#U_obs_op_pdadfomicallback_obs_pdafomi.F90 U_obs_op_pdafomi] (Called `dim_ens` times; once for each ensemble member)
    284232
    285233In the loop over all local analysis domains, it is executed for each local analysis domain:
    286234 1. [#U_init_dim_linit_dim_l_pdaf.F90 U_init_dim_l]
    287  1. [#U_init_dim_obs_linit_dim_obs_l_pdaf.F90 U_init_dim_obs_l]
     235 1. [#U_init_dim_obs_l_pdafomiinit_dim_obs_l_pdaf.F90 U_init_dim_obs_l_pdafomi]
    288236 1. [#U_g2l_stateg2l_state_pdaf.F90 U_g2l_state] (Called `dim_ens+1` times: Once for each ensemble member and once for the mean state estimate)
    289237 1. [#U_l2g_statel2g_state_pdaf.F90 U_l2g_state] (Called `dim_ens+1` times: Once for each ensemble member and once for the mean state estimate)