Changes between Version 3 and Version 4 of Implement3DVarAnalysisPDAF3_3DEnVar

Timestamp:

May 27, 2025, 1:38:55 PM (7 weeks ago)

Author:

lnerger

Comment:

--

Implement3DVarAnalysisPDAF3_3DEnVar

@@ -34 +34 @@
 == Overview ==
 
-This page describes the recommended implementation of the analysis step for the 3D ensemble Var schemes using the PDAF3 interface.
-
-|| 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]. ||
-
-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.
-
-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. 
-
-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.
+This page describes the implementation of the analysis step for the 3D ensemble Var schemes using the PDAF3 interface.
+
+|| 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]. ||
+
+The 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. 
+
+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 as was examplained on the [wiki:Implement3DVarAnalysisOverviewPDAF3 page providing the verview of the Analysis Step for 3D-Var Methods]. 
+
+For 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.
 
 
 == Analysis Routines ==
 
-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.
+The 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.
 
 There are two variants that either compute the transformataion of the ensemble transformation using the local LESTKF method, or the global ESTKF.
@@ -53 +53 @@
 === `PDAF3_assimilate_en3dvar` ===
 
-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.
-
-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)
+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.
+
+This 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).
 
 The interface is:
@@ -82 +82 @@
  * `status`: The integer status flag. It is zero, if the routine is exited without errors.
 
-=== `PDAF3_assim_offline_3dvar_all` ===
-
-This routine is used to perform the analysi step for the offline mode of PDAF.
-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. 
-
-The interface when using one of the global filters is the following:
+=== `PDAF3_assim_offline_en3dvar` ===
+
+This routine is used to perform the analysis step for the offline mode of PDAF.
+The 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. 
+
+The interface is:
 {{{
   SUBROUTINE PDAF3_assim_offline_en3dvar(&
@@ -99 +99 @@
 === `PDAF3_put_state_en3dvar` ===
 
-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. 
-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.
-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. 
-
-The interface when using one of the global filters is the following:
+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. 
+When 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.
+The 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. 
+
+The interface is:
 {{{
   SUBROUTINE PDAF3_put_state_en3dvar(U_collect_state, &
@@ -112 +112 @@
                                  U_prepoststep, outflag)
 }}}
-
+where all arguments, except the last one, are the names of call-back routines. See the description of the arguments for `PDAF3_assimilate_en3dvar`.
 
 == Analysis Routines specific for using global ESTKF ==
@@ -143 +143 @@
 The interface is:
 {{{
-SUBROUTINE PDAF3_assimilate_en3dvar_estkf(&
+SUBROUTINE PDAF3_assim_offline_en3dvar_estkf(&
                                  init_dim_obs_pdafomi, obs_op_pdafomi, &
                                  cvt_ens_pdaf, cvt_adj_ens_pdaf, &
@@ -163 +163 @@
 The interface is:
 {{{
-SUBROUTINE PDAF3_assimilate_en3dvar_estkf(collect_state_pdaf, &
+SUBROUTINE PDAF3_put_state_en3dvar_estkf(collect_state_pdaf, &
                                  init_dim_obs_pdafomi, obs_op_pdafomi, &
                                  cvt_ens_pdaf, cvt_adj_ens_pdaf,  &
@@ -176 +176 @@
 == User-supplied routines ==
 
-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].
-
-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.
-
-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.
+Here, 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].
+
+The 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.
+
+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. Further, the suffix `_l` indices variables that are specific for a local analysis domain in the LESTKF.
 
 
@@ -187 +187 @@
 This routine is independent of the filter algorithm used.
 
-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.
+See 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.
 
 === `distribute_state_pdaf` (distribute_state_pdaf.F90) ===
@@ -193 +193 @@
 This routine is independent of the filter algorithm used.
 
-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.
+See 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.
 
 
@@ -210 +210 @@
 
 See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
-
 
 
@@ -229 +228 @@
 
 The routine is called during the analysis step during the iterative minimization of the cost function. 
-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.
+It 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. 
 
 If 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.
+
 
 
@@ -250 +250 @@
 
 The routine is called during the analysis step during the iterative minimization of the cost function. 
-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.
+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'''. 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. 
 
 If 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.
-