Changes between Version 1 and Version 2 of Implement3DVarAnalysisPDAF3Universal

Timestamp:

May 26, 2025, 4:11:28 PM (7 weeks ago)

Author:

lnerger

Comment:

--

Implement3DVarAnalysisPDAF3Universal

@@ -38 +38 @@
 There are genenerally three different variants of 3D-Var provided by PDAF: parameterized 3D-Var, 3D Ensemble Var, and hybrid (parameterized + ensemble) 3D-Var. All can be called using the universal interface routines described here.
 
-For the analysis step of 3D-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 routine `PDAF3_assimilate_3dvar_all` in the online mode of PDAF or `PDAF3_assim_offline_3dvar_all` for the offline mode. With regard to the parallelization, all these routines (except `U_collect_state`, `U_distribute_state`, and `U_next_observation`) are executed by the filter processes (`filterpe=.true.`) only.
+For the analysis step of 3D-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 routine `PDAF3_assimilate_3dvar_all` in the online mode of PDAF or `PDAF3_assim_offline_3dvar_all` for the offline mode. 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 universal interface has more arguments than the specific interfaces for the parameterized 3D-Var or the 3D ensemble Var methods. It is useful if one implements both the 3D-Var with parameterized covariances and rhe 3D ensemble Var. The hybrid 3D-Var using the LESTKF is always called using this unversal interface.
@@ -67 +67 @@
 }}}
 where all arguments, except the last one, are the names of call-back routines:
- * [#U_collect_state_pdafcollect_state_pdaf.F90 collect_state_pdaf]: 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 `distribute_state` used in `PDAF_init_forecast` as well as here. 
- * [#U_distribute_state_pdafdistribute_state_pdaf.F90 distribute_state_pdaf]:  The name of a user supplied routine that initializes the model fields from the array holding the ensemble of model state vectors.
- * [#U_init_dim_obs_pdafomicallback_obs_pdafomi.F90 init_dim_obs_pdafomi]: The name of the user-supplied routine that initializes the observation information and provides the size of observation vector
- * [#U_obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_pdafomi]: The name of the user-supplied routine that acts as the observation operator on some state vector
- * [#U_cvt_ens_pdafcvt_ens_pdaf.F90 cvt_ens_pdaf]: The name of the user-supplied routine that applies the ensemble control-vector transformation (square-root of the B-matrix) on some control vector to obtain a state vector.
- * [#U_cvt_adj_ens_pdafcvt_adj_ens_pdaf.F90 cvt_adj_ens_pdaf]: The name of the user-supplied routine that applies the adjoint ensemble control-vector transformation (with square-root of the B-matrix) on some state vector to obtain the control vector.
- * [#U_cvt_pdafcvt_pdaf.F90 cvt_pdaf]: The name of the user-supplied routine that applies the control-vector transformation (square-root of the B-matrix) on some control vector to obtain a state vector.
- * [#U_cvt_adj_pdafcvt_adj_pdaf.F90 cvt_adj_pdaf]: The name of the user-supplied routine that applies the adjoint control-vector transformation (with square-root of the B-matrix) on some state vector to obtain the control vector.
- * [#U_obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_lin_pdafomi]: The name of the user-supplied routine that acts as the linearized observation operator on some state vector
- * [#U_obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_lin_pdafomi]: The name of the user-supplied routine that acts as the adjoint observation operator on some state vector
- * [#U_init_n_domains_pdafinit_n_domains_pdaf.F90 init_n_domains_pdaf]: The name of the routine that provides the number of local analysis domains
- * [#U_init_dim_l_pdafinit_dim_l_pdaf.F90 init_dim_l_pdaf]: The name of the routine that provides the state dimension for a local analysis domain
- * [#U_init_dim_obs_l_pdafomicallback_obs_pdafomi.F90 init_dim_obs_l_pdafomi]: The name of the routine that initializes the size of the observation vector for a local analysis domain
- * [#U_prepoststep_pdafprepoststep_ens_pdaf.F90 prepoststep_pdaf]: The name of the pre/poststep routine as in `PDAF_init_forecast`
- * [#U_next_observation_pdafnext_observation.F90 next_observation_pdaf]: 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`.
+ * [#collect_state_pdafcollect_state_pdaf.F90 collect_state_pdaf]: 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 `distribute_state` used in `PDAF_init_forecast` as well as here. 
+ * [#distribute_state_pdafdistribute_state_pdaf.F90 distribute_state_pdaf]:  The name of a user supplied routine that initializes the model fields from the array holding the ensemble of model state vectors.
+ * [#init_dim_obs_pdafomicallback_obs_pdafomi.F90 init_dim_obs_pdafomi]: The name of the user-supplied routine that initializes the observation information and provides the size of observation vector
+ * [#obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_pdafomi]: The name of the user-supplied routine that acts as the observation operator on some state vector
+ * [#cvt_ens_pdafcvt_ens_pdaf.F90 cvt_ens_pdaf]: The name of the user-supplied routine that applies the ensemble control-vector transformation (square-root of the B-matrix) on some control vector to obtain a state vector.
+ * [#cvt_adj_ens_pdafcvt_adj_ens_pdaf.F90 cvt_adj_ens_pdaf]: The name of the user-supplied routine that applies the adjoint ensemble control-vector transformation (with square-root of the B-matrix) on some state vector to obtain the control vector.
+ * [#cvt_pdafcvt_pdaf.F90 cvt_pdaf]: The name of the user-supplied routine that applies the control-vector transformation (square-root of the B-matrix) on some control vector to obtain a state vector.
+ * [#cvt_adj_pdafcvt_adj_pdaf.F90 cvt_adj_pdaf]: The name of the user-supplied routine that applies the adjoint control-vector transformation (with square-root of the B-matrix) on some state vector to obtain the control vector.
+ * [#obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_lin_pdafomi]: The name of the user-supplied routine that acts as the linearized observation operator on some state vector
+ * [#obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_lin_pdafomi]: The name of the user-supplied routine that acts as the adjoint observation operator on some state vector
+ * [#init_n_domains_pdafinit_n_domains_pdaf.F90 init_n_domains_pdaf]: The name of the routine that provides the number of local analysis domains
+ * [#init_dim_l_pdafinit_dim_l_pdaf.F90 init_dim_l_pdaf]: The name of the routine that provides the state dimension for a local analysis domain
+ * [#init_dim_obs_l_pdafomicallback_obs_pdafomi.F90 init_dim_obs_l_pdafomi]: The name of the routine that initializes the size of the observation vector for a local analysis domain
+ * [#prepoststep_pdafprepoststep_ens_pdaf.F90 prepoststep_pdaf]: The name of the pre/poststep routine as in `PDAF_init_forecast`
+ * [#next_observation_pdafnext_observation.F90 next_observation_pdaf]: 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`.
  * `status`: The integer status flag. It is zero, if the routine is exited without errors.
 
@@ -130 +130 @@
 
 
-=== `U_collect_state` (collect_state_pdaf.F90) ===
+=== `collect_state_pdaf` (collect_state_pdaf.F90) ===
 
 This routine is independent of the filter algorithm used.
 
-See the page on [InsertAnalysisStep#U_collect_statecollect_state_pdaf.F90 inserting the analysis step] for the description of this routine.
-
-
-=== `U_distribute_state` (distribute_state_pdaf.F90) ===
+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.
+
+=== `distribute_state_pdaf` (distribute_state_pdaf.F90) ===
 
 This routine is independent of the filter algorithm used.
 
-See the page on [InsertAnalysisStep#U_distribute_statedistribute_state_pdaf.F90 inserting the analysis step] for the description of this routine.
-
-
-=== `U_init_dim_obs_pdafomi` (callback_obs_pdafomi.F90) ===
-
-This 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.
-
-See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
-
-
-
-=== `U_obs_op_pdafomi` (callback_obs_pdafomi.F90) ===
-
-This 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.
-
-See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
-
-
-
-
-=== `U_cvt_ens` (cvt_ens_pdaf.F90) ===
+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.
+
+
+
+=== `init_dim_obs_pdafomi` (callback_obs_pdafomi.F90) ===
+
+This is a call-back routine initializing the observation information. The routine just calls a routine from the observation module for each observation type.
+
+See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
+
+
+
+=== `obs_op_pdafomi` (callback_obs_pdafomi.F90) ===
+
+This 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.
+
+See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
+
+
+
+=== `cvt_ens_pdaf` (cvt_ens_pdaf.F90) ===
 
 The interface for this routine is:
@@ -182 +181 @@
 
 
-=== `U_cvt_adj` (cvt_adj_pdaf.F90) ===
+=== `cvt_adj_pdaf` (cvt_adj_pdaf.F90) ===
 
 The interface for this routine is:
@@ -204 +203 @@
 
 
-=== `U_cvt` (cvt_pdaf.F90) ===
+=== `cvt_pdaf` (cvt_pdaf.F90) ===
 
 The interface for this routine is:
@@ -223 +222 @@
 
 
-=== `U_cvt_adj` (cvt_adj_pdaf.F90) ===
+=== `cvt_adj_pdaf` (cvt_adj_pdaf.F90) ===
 
 The interface for this routine is:
@@ -244 +243 @@
 
 
-=== `U_obs_op_lin_pdafomi` (callback_obs_pdafomi.F90) ===
+=== `obs_op_lin_pdafomi` (callback_obs_pdafomi.F90) ===
 
 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.
@@ -251 +250 @@
 
 
-=== `U_obs_op_adj_pdafomi` (callback_obs_pdafomi.F90) ===
+=== `obs_op_adj_pdafomi` (callback_obs_pdafomi.F90) ===
 
 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.
@@ -259 +258 @@
 
 
-=== `U_init_n_domains` (init_n_domains_pdaf.F90) ===
-
-The interface for this routine is:
-{{{
-SUBROUTINE init_n_domains(step, n_domains_p)
+=== `init_n_domains_pdaf` (init_n_domains_pdaf.F90) ===
+
+This 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.
+
+The interface for this routine is:
+{{{
+SUBROUTINE init_n_domains_pdaf(step, n_domains_p)
 
   INTEGER, INTENT(in)  :: step        ! Current time step
@@ -269 +270 @@
 }}}
 
-The routine 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.
-
 Hints: 
- * As a simple case, if the localization is only performed horizontally, the local analysis domains can be single vertical columns of the model grid. In this case, `n_domains_p` is simply the number of vertical columns in the local model sub-domain.
-
-
-
-
-=== `U_init_dim_l` (init_dim_l_pdaf.F90) ===
-
-The interface for this routine is:
-{{{
-SUBROUTINE init_dim_l(step, domain_p, dim_l)
+ * As a simple case, if the localization is only performed horizontally, the local analysis domains can be single vertical columns of the model grid. In this case, `n_domains_p` is simply the number of vertical columns in the process-local model sub-domain.
+
+
+=== `init_dim_l_pdaf` (init_dim_l_pdaf.F90) ===
+
+This routine is only used for localization. 
+
+The interface for this routine is:
+{{{
+SUBROUTINE init_dim_l_pdaf(step, domain_p, dim_l)
 
   INTEGER, INTENT(in)  :: step        ! Current time step
@@ -290 +288 @@
 
 The routine is called during the loop over the local analysis domains in the analysis step. 
-For PDAF it has to provide in `dim_l` the dimension of the state vector for the local analysis domain with index `domain_p`. 
-
-In addition, for PDAFlocal the routine has to provide the index array containing the indices of the elements of the local state vector in the global (or domain-decomposed) state vector to PDAFlocal by calling `PDAFlocal_set_indices`. (in the template files, this array is called `id_lstate_in_pstate`)
+
+It provides in `dim_l` the dimension of the state vector for the local analysis domain with index `domain_p` to PDAF. 
+
+In the recommended implementation shown in the tutorial and template codes, there are two further initializations:
+1. The routine has initialize the index array `id_lstate_in_pstate` containing the indices of the elements of the local state vector in the global (or domain-decomposed) state vector. Then it has to provide this array to PDAF by calling `PDAFlocal_set_indices` (see below).
+2. The routine initializes an array `coords_l` containing the coordinates of the local analysis domain. This is shared with `U_init_dim_obs_l_pdafomi` via the module `mod_assimilation`.
 
 Hints: 
- * For sharing through the module `mod_assimilation`, we further initialize an array `coords_l` containing the coordinates that describe the local domain. 
-  * These coordinates have to describe one location in space that is used in the OMI observation modules to compute the distance from observations. 
+  * The coordinates in `coords_l` have to describe one location in space that is used for localization to compute the distance from observations. 
   * The coordinates in `coords_l` have the same units as those used for the observations
   * For geographic distance computations, the unit of the coordinates needs to be radian, thus (0, 2*pi) or (-pi,pi) for longitude and (-pi/2, pi/2) for latitude.
@@ -305 +305 @@
    * In this case only the horizontal coordinates are used in `coords_l`.
 
-The index array `id_lstate_in_pstate` is an integer array in form of a one-dimensional vector. One initializes this vector by determining the indices of the elements of the local state vector in the global, or domain decomposed, state vector. After initializing `id_lstate_in_pstate`, one has to provided it to PDAFlocal by calling `PDAFlocal_set_indices'. The interface interface is:
+The index array `id_lstate_in_pstate` is an integer array in form of a one-dimensional vector. One initializes this vector by determining the indices of the elements of the local state vector in the global, or domain decomposed, state vector. After initializing `id_lstate_in_pstate`, one has to provided it to PDAF by calling `PDAFlocal_set_indices'. The interface interface is:
 
 {{{
@@ -319 +319 @@
 
 
-=== `U_init_dim_obs_l_pdafomi` (callback_obs_pdafomi.F90) ===
-
-This 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.
-
-See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
-
-
-=== `U_prepoststep` (prepoststep_ens_pdaf.F90) ===
+=== `init_dim_obs_l_pdafomi` (callback_obs_pdafomi.F90) ===
+
+This 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.
+
+See the [wiki:OMI_Callback_obs_pdafomi documentation on callback_obs_pdafomi.F90] for more information.
+
+
+=== `prepoststep_pdaf` (prepoststep_ens_pdaf.F90) ===
 
 The routine has already been described for modifying the model for the ensemble integration and for inserting the analysis step. 
 
-See the page on [InsertAnalysisStep#U_prepoststepprepoststep_ens_pdaf.F90 inserting the analysis step] for the description of this routine.
-
-
-=== `U_next_observation` (next_observation_pdaf.F90) ===
+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.
+
+
+=== `next_observation_pdaf` (next_observation_pdaf.F90) ===
 
 This routine is independent of the filter algorithm used.
 
-See the page on [InsertAnalysisStep#U_next_observationnext_observation_pdaf.F90 inserting the analysis step] for the description of this routine.
-
+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.
 
 == Execution order of user-supplied routines ==
 
-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.
+The user-supplied routines are executed in the order listed below.  The order can be important as some routines can perform preparatory work for later routines. For example, `init_dim_obs_pdafomi` prepares an index array that provides the information for executing the observation operator in `obs_op_pdafomi`. How this information is initialized is described in the documentation of OMI.
 
 Before the analysis step is called the following routine is executed:
- 1. [#U_collect_statecollect_state_pdaf.F90 U_collect_state]
+ 1. [#collect_state_pdafcollect_state_pdaf.F90 collect_state_pdaf]
 
 The 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:
- 1. [#U_prepoststepprepoststep_ens_pdaf.F90 U_prepoststep] (Call to act on the forecast ensemble, called with negative value of the time step)
- 1. [#U_init_dim_obs_pdafomicallback_obs_pdafomi.F90 U_init_dim_obs_pdafomi]
- 1. [#U_obs_op_pdafomicallback_obs_pdafomi.F90 U_obs_op_pdafomi] (multiple calls, one for each ensemble member)
+ 1. [#prepoststep_pdafprepoststep_ens_pdaf.F90 prepoststep_pdaf] (Call to act on the forecast ensemble, called with negative value of the time step)
+ 1. [#init_dim_obs_pdafomicallback_obs_pdafomi.F90 init_dim_obs_pdafomi]
+ 1. [#obs_op_pdafomicallback_obs_pdafomi.F90 obs_op_pdafomi] (multiple calls, one for each ensemble member)
 
 Inside the analysis step the interative optimization is computed. This involves the repeated call of the routines:
- 1. [#U_cvtcvt_pdaf.F90 U_cvt] 
- 1. [#U_cvt_enscvt_ens_pdaf.F90 U_cvt_ens] 
- 1. [#U_obs_op_lin_pdafomicallback_obs_pdafomi.F90 U_obs_op_lin_pdafomi]
- 1. [#U_obs_op_adj_pdafomicallback_obs_pdafomi.F90 U_obs_op_adj_pdafomi]
- 1. [#U_cvt_adjcvt_adj_pdaf.F90 U_cvt_adj] 
- 1. [#U_cvt_adj_enscvt_adj_ens_pdaf.F90 U_cvt_adj_ens] 
+ 1. [#cvt_pdafcvt_pdaf.F90 cvt_pdaf] 
+ 1. [#cvt_ens_pdafcvt_ens_pdaf.F90 cvt_ens_pdaf] 
+ 1. [#obs_op_lin_pdafomicallback_obs_pdafomi.F90 U_obs_op_lin_pdafomi]
+ 1. [#obs_op_adj_pdafomicallback_obs_pdafomi.F90 U_obs_op_adj_pdafomi]
+ 1. [#cvt_adj_pdafcvt_adj_pdaf.F90 cvt_adj_pdaf] 
+ 1. [#cvt_adj_ens_pdafcvt_adj_ens_pdaf.F90 cvt_adj_ens_pdaf] 
 
 After the iterative optimization the following routines are executes to complte the analysis step:
- 1. [#U_cvt_enscvt_pdaf.F90 U_cvt] (Call to the parameterized part of the control vector transform to compute the final state vector increment)
- 1. [#U_cvt_enscvt_ens_pdaf.F90 U_cvt_ens] (Call to the eensemble-part of the control vector transform to compute the final state vector increment)
- 1. [#U_prepoststepprepoststep_ens_pdaf.F90 U_prepoststep] (Call to act on the analysis ensemble, called with (positive) value of the time step)
-
-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].
-
-In case of the routine `PDAFomi_assimilate_*`, the following routines are executed after the analysis step:
- 1. [#U_distribute_statedistribute_state_pdaf.F90 U_distribute_state]
- 1. [#U_next_observationnext_observation_pdaf.F90 U_next_observation]
+ 1. [#cvt_enscvt_pdaf.F90 U_cvt] (Call to the parameterized part of the control vector transform to compute the final state vector increment)
+ 1. [#cvt_enscvt_ens_pdaf.F90 U_cvt_ens] (Call to the eensemble-part of the control vector transform to compute the final state vector increment)
+ 1. [#prepoststepprepoststep_ens_pdaf.F90 U_prepoststep] (Call to act on the analysis ensemble, called with (positive) value of the time step)
+
+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 on the [wiki:ImplementAnalysisPDAF3Universal page on implementing the local filter analysis step] .
+
+In case of the routine `PDAF3_assimilate_3dvar_all`, the following routines are executed after the analysis step:
+ 1. [#distribute_state_pdafdistribute_state_pdaf.F90 distribute_state_pdaf]
+ 1. [#next_observation_pdafnext_observation_pdaf.F90 next_observation_pdaf]