Changes between Version 1 and Version 2 of ImplementAnalysis_3DEnVar_classical


Ignore:
Timestamp:
Dec 9, 2021, 12:44:01 PM (12 months ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • ImplementAnalysis_3DEnVar_classical

    v1 v2  
    8585 * [#U_prepoststepprepoststep_ens_pdaf.F90 U_prepoststep]: The name of the pre/poststep routine as in `PDAF_get_state`
    8686 * [#U_prodRinvA_lprodrinva_l_pdaf.F90 U_prodRinvA_l]: The name of the user-supplied routine that computes the product of the inverse of the observation error covariance matrix with some matrix provided to the routine by PDAF.
    87  * [#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
     87 * [#U_init_n_domains_pinit_n_domains_pdaf.F90 U_init_n_domains]: The name of the routine that provides the number of local analysis domains
    8888 * [#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
    8989 * [#U_init_dim_obs_linit_dim_obs_l_pdaf.F90 U_init_dim_obs_l]: The name of the routine that initializes the size of the observation vector for a local analysis domain
     
    9595 * [#U_prepoststepprepoststep_ens_pdaf.F90 U_prepoststep]: The name of the pre/poststep routine as in `PDAF_get_state`
    9696 * [#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`.
    97  * `status`: The integer status flag. It is zero, if `PDAFomi_assimilate_global` is exited without errors.
    98 
    99 
    100 
    101 === `PDAFomi_assimilate_en3dvar_estkf` ===
     97 * `status`: The integer status flag. It is zero, if the routine is exited without errors.
     98
     99
     100
     101=== `PDAF_assimilate_en3dvar_estkf` ===
    102102
    103103This routine is called for the case of transforming the ensemble perturbations using the global ESTKF. 
     
    124124 * [#U_prepoststepprepoststep_ens_pdaf.F90 U_prepoststep]: The name of the pre/poststep routine as in `PDAF_get_state`
    125125 * [#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`.
    126  * `status`: The integer status flag. It is zero, if `PDAFomi_assimilate_global` is exited without errors.
    127 
    128 Note that the interface of `PDAFomi_assimilate_en3dvar_estkf` is identical to that of `PDAFomi_assimilate_3dvar` apart from using the routines `U_cvt_ens` and `U_cvt_adj_ens` in case of the ensemble variational method.
    129 
    130 
    131 === `PDAFomi_put_state_en3dvar_lestkf` ===
    132 
    133 When 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.
     126 * `status`: The integer status flag. It is zero, if the routine is exited without errors.
     127
     128
     129=== `PDAF_put_state_en3dvar_lestkf` ===
     130
     131When the 'flexible' implementation variant is chosen for the assimilation system, the routine `PDAF_put_state_*` has to be used instead of `PDAF_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.
    134132
    135133The interface when using one of the global filters is the following:
    136134{{{
    137   SUBROUTINE PDAFomi_put_state_en3dvar_lestkf(U_collect_state, &
    138                                  U_init_dim_obs_pdafomi, U_obs_op_pdafomi, &
    139                                  U_cvt_ens, U_cvt_adj_ens, U_obs_op_lin_pdafomi, U_obs_op_adj_pdafomi, &
    140                                  U_init_n_domains_p, U_init_dim_l, U_init_dim_obs_l_pdafomi, &
    141                                  U_g2l_state, U_l2g_state, U_prepoststep, outflag)
    142 }}}
    143 
    144 === `PDAFomi_put_state_en3dvar_estkf` ===
    145 
    146 The interface of this routine is analogous to that of `PDAFomi_assimilate_en3dvar_estkf'. Thus it is identical to this routine with the exception the specification of the user-supplied routines `U_distribute_state` and `U_next_observation` are missing.
     135  SUBROUTINE PDAF_put_state_en3dvar_lestkf(U_collect_state, &
     136                                 U_init_dim_obs, U_obs_op, U_init_obs, U_prodRinvA, &
     137                                 U_cvt_ens, U_cvt_adj_ens, U_obs_op_lin, U_obs_op_adj, &
     138                                 U_init_dim_obs_f, U_obs_op_f, U_init_obs_f, U_init_obs_l, U_prodRinvA_l, &
     139                                 U_init_n_domains_p, U_init_dim_l, U_init_dim_obs_l, U_g2l_state, U_l2g_state, &
     140                                 U_g2l_obs, U_init_obsvar, U_init_obsvar_l, &
     141                                 U_prepoststep, outflag)
     142}}}
     143
     144=== `PDAF_put_state_en3dvar_estkf` ===
     145
     146The interface of this routine is analogous to that of `PDAF_assimilate_en3dvar_estkf'. Thus it is identical to this routine with the exception the specification of the user-supplied routines `U_distribute_state` and `U_next_observation` are missing.
    147147
    148148The interface when using one of the global filters is the following:
    149149{{{
    150   SUBROUTINE PDAFomi_put_state_en3dvar_estkf(U_collect_state, &
    151                                  U_init_dim_obs_pdafomi, U_obs_op_pdafomi, &
    152                                  U_cvt_ens, U_cvt_adj_ens, U_obs_op_lin_pdafomi, U_obs_op_adj_pdafomi, &
    153                                  U_prepoststep, outflag)
     150  SUBROUTINE PDAF_put_state_en3dvar_estkf(U_collect_state, &
     151                                 U_init_dim_obs, U_obs_op, U_init_obs, U_prodRinvA, &
     152                                 U_cvt_ens, U_cvt_adj_ens, U_obs_op_lin, U_obs_op_adj, &
     153                                 U_init_obsvar, U_prepoststep, outflag)
    154154}}}
    155155
    156156== User-supplied routines ==
    157157
    158 Here all user-supplied routines are described that are required in the call to `PDAFomi_assimilate_3dvar`. For some of the generic routines, we link to the page on [ModifyModelforEnsembleIntegration modifying the model code for the ensemble integration].
    159 
    160 To indicate user-supplied routines we use the prefix `U_`. In the template directory `templates/` as well as in the tutorial implementations in `tutorial/` 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.
     158Here all user-supplied routines are described that are required in the calls to `PDAF_assimilate_en3dvar_*` and `PDAF_put_state_en3dvar_*`. For some of the generic routines, we link to the page on [ModifyModelforEnsembleIntegration modifying the model code for the ensemble integration].
     159
     160To 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.
    161161
    162162In the subroutine interfaces some variables appear with the suffix `_p`. 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.
     
    309309
    310310
    311 === `U_obs_op_lin_pdafomi` (callback_obs_pdafomi.F90) ===
    312 
    313 This 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.
    314 
    315 See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
    316 
    317 
    318 === `U_obs_op_adj_pdafomi` (callback_obs_pdafomi.F90) ===
    319 
    320 This 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.
    321 
    322 See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
     311=== `U_obs_op_lin` (obs_op_lin_pdaf.F90) ===
     312
     313This routine is used by all 3D-Var methods.
     314
     315The interface for this routine is:
     316{{{
     317SUBROUTINE obs_op_lin(step, dim_p, dim_obs_p, state_p, m_state_p)
     318
     319  INTEGER, INTENT(in) :: step               ! Current time step
     320  INTEGER, INTENT(in) :: dim_p              ! PE-local dimension of state
     321  INTEGER, INTENT(in) :: dim_obs_p          ! Dimension of observed state
     322  REAL, INTENT(in)    :: state_p(dim_p)     ! PE-local model state
     323  REAL, INTENT(out) :: m_state_p(dim_obs_p) ! PE-local observed state
     324}}}
     325
     326The routine is called during the analysis step. It has to perform the operation of the linearized observation operator acting on a state vector increment that is provided as `state_p`. The observed state has to be returned in `m_state_p`.
     327
     328For a model using domain decomposition, the operation is on the PE-local sub-domain of the model and has to provide the observed sub-state for the PE-local domain.
     329
     330Hint:
     331 * If the observation operator involves a global operation, e.g. some global integration, while using domain-decomposition one has to gather the information from the other model domains using MPI communication.
     332
     333
     334=== `U_obs_op_adj` (obs_op_adj_pdaf.F90) ===
     335
     336This routine is used by all 3D-Var methods.
     337
     338The interface for this routine is:
     339{{{
     340SUBROUTINE obs_op_adj(step, dim_p, dim_obs_p, state_p, m_state_p)
     341
     342  INTEGER, INTENT(in) :: step                 ! Current time step
     343  INTEGER, INTENT(in) :: dim_p                ! PE-local dimension of state
     344  INTEGER, INTENT(in) :: dim_obs_p            ! Dimension of observed state
     345  REAL, INTENT(in)    :: m_state_p(dim_obs_p) ! PE-local observed state
     346  REAL, INTENT(out)   :: state_p(dim_p)       ! PE-local model state
     347}}}
     348
     349The routine is called during the analysis step. It has to perform the operation of the adjoint observation operator acting on a vector in observation space that is provided as m_state_p. The resulting state vector has to be returned in `m_state_p`.
     350
     351For a model using domain decomposition, the operation is on the PE-local sub-domain of the model and has to provide the observed sub-state for the PE-local domain.
     352
     353Hint:
     354 * If the observation operator involves a global operation, e.g. some global integration, while using domain-decomposition one has to gather the information from the other model domains using MPI communication.
     355
    323356
    324357
     
    624657== Execution order of user-supplied routines ==
    625658
    626 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.
     659The user-supplied routines are essentially executed in the order they are listed in the interfaces to the routines. An except is the order of the routines for the local ESTKF. The order can be important as some routines can perform preparatory work for later routines. For example, `U_init_dim_obs` prepares an index array that provides the information for executing the observation operator in `U_obs_op`.
    627660
    628661Before the analysis step is called the following routine is executed:
     
    631664The 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:
    632665 1. [#U_prepoststepprepoststep_ens_pdaf.F90 U_prepoststep] (Call to act on the forecast ensemble, called with negative value of the time step)
    633  1. [#U_init_dim_obs_pdafomicallback_obs_pdafomi.F90 U_init_dim_obs_pdafomi]
    634  1. [#U_obs_op_pdafomicallback_obs_pdafomi.F90 U_obs_op_pdafomi] (multiple calls, one for each ensemble member)
     666 1. [#U_init_dim_obsinit_dim_obs_pdaf.F90 U_init_dim_obs]
     667 1. [#U_obs_opobs_op_pdaf.F90 U_obs_op]
     668 1. [#U_init_obsinit_obs_pdaf.F90 U_init_obs]
    635669
    636670Inside the analysis step the interative optimization is computed. This involves the repeated call of the routines:
    637  1. [#U_cvt_enscvt_ens_pdaf.F90 U_cvt_ens]
    638  1. [#U_obs_op_lin_pdafomicallback_obs_pdafomi.F90 U_obs_op_lin_pdafomi]
    639  1. [#U_obs_op_adj_pdafomicallback_obs_pdafomi.F90 U_obs_op_adj_pdafomi]
    640  1. [#U_cvt_adj_enscvt_adj_ens_pdaf.F90 U_cvt_adj_ens]
     671 1. [#U_cvtcvt_pdaf.F90 U_cvt]
     672 1. [#U_obs_op_linobs_op_lin_pdaf.F90 U_obs_op_lin]
     673 1. [#U_prodRinvAprodrinva_pdaf.F90 U_prodRinvA]
     674 1. [#U_obs_op_adjobs_op_adj_pdaf.F90 U_obs_op_adj]
     675 1. [#U_cvt_adjcvt_adj_pdaf.F90 U_cvt_adj]
    641676
    642677After the iterative optimization the following routines are executes to complte the analysis step:
     
    644679 1. [#U_prepoststepprepoststep_ens_pdaf.F90 U_prepoststep] (Call to act on the analysis ensemble, called with (positive) value of the time step)
    645680
    646 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].
    647 
    648 In case of the routine `PDAFomi_assimilate_*`, the following routines are executed after the analysis step:
     681The 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:ImplementAnalysislestkf page on implementing the analysis step of the LESTKF] and on the [wiki:ImplementAnalysisestkf page on implementing the analysis step of the ESTKF].
     682
     683In case of the routines `PDAF_assimilate_*`, the following routines are executed after the analysis step:
    649684 1. [#U_distribute_statedistribute_state_pdaf.F90 U_distribute_state]
    650685 1. [#U_next_observationnext_observation_pdaf.F90 U_next_observation]