Changes between Version 3 and Version 4 of Implement3DVarAnalysisPDAF3_3DEnVar


Ignore:
Timestamp:
May 27, 2025, 1:38:55 PM (7 weeks ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Implement3DVarAnalysisPDAF3_3DEnVar

    v3 v4  
    3434== Overview ==
    3535
    36 This page describes the recommended implementation of the analysis step for the 3D ensemble Var schemes using the PDAF3 interface.
    37 
    38 || The interface for 3D ensemble Var are specialized version of the universal interface with a reduced number of arguments. If one implements both 3D ensemble Var and parameterlized 3D-Var we recommend to use the [wiki:Implement3DVarAnalysisPDAF3Universal universal assimilation routines for 3D-Var]. ||
    39 
    40 For the analysis step of 3D ensemble Var we need different operations related to the observations. These operations are requested by PDAF by call-back routines supplied by the user and provided in the OMI structure. The names of the routines that are provided by the user are specified in the call to the assimilation routines. With regard to the parallelization, all these routines (except `collect_state_pdaf`, `distribute_state_pdaf`, and `next_observation_pdaf`) are executed by the filter processes (`filterpe=.true.`) only.
    41 
    42 The different 3D-Var methods in PDAF were explained on the [wiki:Implement3DVarAnalysisOverview page providing the verview of the Analysis Step for 3D-Var Methods]. Depending the type of 3D-Var, the background covariance matrix '''B''' is represented either in a parameterized form, by an ensemble, or by a combination of both. The 3D-Var methods that use an ensemble need to transform the ensemble perturbations using an ensemble Kalman filter. PDAF uses for this the error-subspace transform filter ESTKF. There are two variants: The first uses the localized filter LESTKF, while the second uses the global filter ESTKF.
    43 
    44 For completeness we discuss here all user-supplied routines that are specified in the interface to `PDAF3_assimilate_en3dvar_X`. Thus, some of the user-supplied routines that are explained on the page describing the modification of the model code for the ensemble integration are repeated here.
     36This page describes the implementation of the analysis step for the 3D ensemble Var schemes using the PDAF3 interface.
     37
     38|| The interface routines for 3D Ensemble Var are specialized versions of the universal interface with a reduced number of arguments. If one implements both 3D Ensemble Var and parameterlized 3D-Var we recommend to use the [wiki:Implement3DVarAnalysisPDAF3Universal universal interface routines for 3D-Var]. ||
     39
     40The different 3D-Var methods in PDAF were explained on the [wiki:Implement3DVarAnalysisOverviewPDAF3 page providing the verview of the Analysis Step for 3D-Var Methods]. Depending the type of 3D-Var, the background covariance matrix '''B''' is represented either in a parameterized form, by an ensemble, or by a combination of both. The 3D-Var methods that use an ensemble need to transform the ensemble perturbations using an ensemble Kalman filter. PDAF uses for this the error-subspace transform filter ESTKF. There are two variants: The first uses the localized filter LESTKF, while the second uses the global filter ESTKF.
     41
     42For the analysis step of 3D Ensemble Var we need different operations related to the observations. These operations are requested by PDAF by call-back routines supplied by the user and provided in the OMI structure. The names of the routines that are provided by the user are specified in the call to the assimilation routines as was examplained on the [wiki:Implement3DVarAnalysisOverviewPDAF3 page providing the verview of the Analysis Step for 3D-Var Methods].
     43
     44For completeness we discuss here all user-supplied routines that are specified as arguments. Thus, some of the user-supplied routines, which were explained on the page describing the modification of the model code for the ensemble integration, are repeated here.
    4545
    4646
    4747== Analysis Routines ==
    4848
    49 The general aspects of the filter (or solver) specific routines `PDAF3_assimilate_*` have been described on the page [OnlineModifyModelforEnsembleIntegration_PDAF3 Modification of the model code for the ensemble integration]. Here, we list the full interface of the routine. Subsequently, the user-supplied routines specified in the call is explained.
     49The general aspects of the filter (or solver) specific routines for the 3D-Var analysis step have been described on the page [wiki:OnlineModifyModelforEnsembleIntegration_PDAF3 Modification of the model code for the ensemble integration]. Here, we list the full interface of the routine. Subsequently, the user-supplied routines specified in the call is explained.
    5050
    5151There are two variants that either compute the transformataion of the ensemble transformation using the local LESTKF method, or the global ESTKF.
     
    5353=== `PDAF3_assimilate_en3dvar` ===
    5454
    55 This routine can be used to run both variants of the 3D ensemble Var, i.e., using the local LESTKF or the global ESTKF for the transformation of the ensemble perturbations.
    56 
    57 This routine is used both in the ''fully-parallel'' and the ''flexible'' implementation variants of the data assimilation system. (See the page [OnlineModifyModelforEnsembleIntegration_PDAF3 Modification of the model code for the ensemble integration] for these variants)
     55This routine can be used to run both variants of the 3D Ensemble Var, i.e., using the local LESTKF or the global ESTKF for the transformation of the ensemble perturbations.
     56
     57This routine is used both in the ''fully-parallel'' and the ''flexible'' implementation variants of the data assimilation system. (See the page [wiki:OnlineModifyModelforEnsembleIntegration_PDAF3 Modification of the model code for the ensemble integration] for these variants).
    5858
    5959The interface is:
     
    8282 * `status`: The integer status flag. It is zero, if the routine is exited without errors.
    8383
    84 === `PDAF3_assim_offline_3dvar_all` ===
    85 
    86 This routine is used to perform the analysi step for the offline mode of PDAF.
    87 The interface of the routine is identical with that of `PDAF3_assimilate_3dvar_all`, except that the user-supplied routines `U_distribute_state`, `U_collect_state` and `U_next_observation` are missing.
    88 
    89 The interface when using one of the global filters is the following:
     84=== `PDAF3_assim_offline_en3dvar` ===
     85
     86This routine is used to perform the analysis step for the offline mode of PDAF.
     87The interface of the routine is identical with that of `PDAF3_assimilate_en3dvar`, except that the user-supplied routines `distribute_state_pdaf`, `collect_state` and `next_observation_pdaf` are missing.
     88
     89The interface is:
    9090{{{
    9191  SUBROUTINE PDAF3_assim_offline_en3dvar(&
     
    9999=== `PDAF3_put_state_en3dvar` ===
    100100
    101 This 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. This routine 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_en3dvar`, except that the user-supplied routines `U_distribute_state` and `U_next_observation` are missing.
    104 
    105 The interface when using one of the global filters is the following:
     101This 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.
     102When the ''flexible'' implementation variant is chosen for the assimilation system, the routine. This routine allows to port such implementations to the PDAF3 interface with minimal changes.
     103The interface of the routine is identical with that of `PDAF3_assimilate_en3dvar`, except that the user-supplied routines `distribute_state_pdaf` and `next_observation_padf` are missing.
     104
     105The interface is:
    106106{{{
    107107  SUBROUTINE PDAF3_put_state_en3dvar(U_collect_state, &
     
    112112                                 U_prepoststep, outflag)
    113113}}}
    114 
     114where all arguments, except the last one, are the names of call-back routines. See the description of the arguments for `PDAF3_assimilate_en3dvar`.
    115115
    116116== Analysis Routines specific for using global ESTKF ==
     
    143143The interface is:
    144144{{{
    145 SUBROUTINE PDAF3_assimilate_en3dvar_estkf(&
     145SUBROUTINE PDAF3_assim_offline_en3dvar_estkf(&
    146146                                 init_dim_obs_pdafomi, obs_op_pdafomi, &
    147147                                 cvt_ens_pdaf, cvt_adj_ens_pdaf, &
     
    163163The interface is:
    164164{{{
    165 SUBROUTINE PDAF3_assimilate_en3dvar_estkf(collect_state_pdaf, &
     165SUBROUTINE PDAF3_put_state_en3dvar_estkf(collect_state_pdaf, &
    166166                                 init_dim_obs_pdafomi, obs_op_pdafomi, &
    167167                                 cvt_ens_pdaf, cvt_adj_ens_pdaf,  &
     
    176176== User-supplied routines ==
    177177
    178 Here all user-supplied routines are described that are required in the call to the assimilation routines for hybrid 3D-Var. For some of the generic routines, we link to the page on [wiki:OnlineModifyModelforEnsembleIntegration_PDAF3 modifying the model code for the ensemble integration].
    179 
    180 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.
    181 
    182 In 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.
     178Here, all user-supplied routines are described that are required in the call to the assimilation routines for 3D Ensemble Var. For some of the generic routines, we link to the page on [wiki:OnlineModifyModelforEnsembleIntegration_PDAF3 modifying the model code for the ensemble integration].
     179
     180The names of the user-suppled routines routines ending on `_pdaf` relate to operations on the model state, while those ensing on `_pdafomi` handle observations using the structured appraoch guided by [wiki:PDAF_OMI_Overview PDAF-OMI]. The user-routines relating to PDAF-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.
     181
     182In 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. Further, the suffix `_l` indices variables that are specific for a local analysis domain in the LESTKF.
    183183
    184184
     
    187187This routine is independent of the filter algorithm used.
    188188
    189 See the page on [ModifyModelforEnsembleIntegration#collect_state_pdafcollect_state_pdaf.F90 modifying the model code for the ensemble integration] for the description of this routine.
     189See the page on [wiki:OnlineModifyModelforEnsembleIntegration_PDAF3#collect_state_pdafcollect_state_pdaf.F90 modifying the model code for the ensemble integration] for the description of this routine.
    190190
    191191=== `distribute_state_pdaf` (distribute_state_pdaf.F90) ===
     
    193193This routine is independent of the filter algorithm used.
    194194
    195 See the page on [ModifyModelforEnsembleIntegration#distribute_state_pdafdistribute_state_pdaf.F90 modifying the model code for the ensemble integration] for the description of this routine.
     195See the page on [wiki:OnlineModifyModelforEnsembleIntegration_PDAF3#distribute_state_pdafdistribute_state_pdaf.F90 modifying the model code for the ensemble integration] for the description of this routine.
    196196
    197197
     
    210210
    211211See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
    212 
    213212
    214213
     
    229228
    230229The routine is called during the analysis step during the iterative minimization of the cost function.
    231 It has to apply the control vector transformation to the control vector and return the transformed result vector. Usually this transformation is the multiplication with the square-root of the background error covariance matrix '''B'''. For the 3D Ensemble Var, this square root is usually expressed through the ensemble.
     230It has to apply the control vector transformation to the control vector and return the transformed result state vector. Usually this transformation is the multiplication with the square-root of the background error covariance matrix '''B'''. For the 3D Ensemble Var, this square root is usually expressed through the ensemble.  More complex transformation, including the combination with a parameterized covariance matrix, are possible and the routine permits the flexiblity to implement any transformation.
    232231
    233232If the control vector is decomposed in case of parallelization it first needs to the gathered on each processor and afterwards the transformation is computed on the potentially domain-decomposed state vector.
     233
    234234
    235235
     
    250250
    251251The routine is called during the analysis step during the iterative minimization of the cost function.
    252 It has to apply the adjoint control vector transformation to a state vector and return the control vector. Usually this transformation is the multiplication with transpose of the square-root of the background error covariance matrix '''B'''. or the 3D Ensemble Var, this square root is usually expressed through the ensemble.
     252It has to apply the adjoint control vector transformation to a state vector and return the control vector. Usually this transformation is the multiplication with transpose of the square-root of the background error covariance matrix '''B'''. For the 3D Ensemble Var, this square root is usually expressed through the ensemble. More complex transformation, including the combination with a parameterized covariance matrix, are possible and the routine permits the flexiblity to implement any transformation.
    253253
    254254If the state vector is decomposed in case of parallelization one needs to take care that the application of the trasformation is complete. This usually requries a comminucation with MPI_Allreduce to obtain a global sun.
    255 
    256255
    257256