Changes between Version 4 and Version 5 of PDAFomi_observation_diagnostics

Timestamp:

May 16, 2025, 6:59:22 PM (41 hours ago)

Author:

lnerger

Comment:

--

PDAFomi_observation_diagnostics

@@ -38 +38 @@
 || PDAF-OMI observation diagnostics were introduced with PDAF V3.0 ||
 
-The PDAF-OMI observation diagnostics module provides functionality to obtain statistics about the differences between observations and the observed model state. In addition, there are routines that provide the user access to the observations and observed quantities like the observed ensemble mean state. 
+The PDAF-OMI observation diagnostics module provides functionality to obtain statistics about the differences between observations and the observed model state. 
+Additionally, there are routines that provide the user with access to observations and observed quantities, such as the observed ensemble mean state.
 
 Here, we describe the functionalities of the observation diagnostics routines.
 
-A common place to call the `PDAFomi_diag` diagnostics routines is in `prepoststep_pdaf`, which is the usual place to also analyze the ensemble. Usually, PDAF initializes the observations after `prepoststep_pdaf` was executed after the forecast. To be able to compare the observations and the forecast ensemble, one has to switch the place at which observations are initialized. This is done with 
+A common place to call the `PDAFomi_diag` diagnostics routines is in `prepoststep_pdaf`, which is the usual place to also analyze the ensemble. 
+
+By default, PDAF initializes the observations after `prepoststep_pdaf` was executed after the forecast. To be able to compare the observations and the forecast ensemble, one has to switch the place at which observations are initialized. This is done with 
 {{{
   CALL PDAF_set_iparam(9, 0)
 }}}
-which can be called in `init_pdaf` after the initialization of PDAF with `PDAF_init`.
+which can be called in `init_pdaf` subsequently to the initialization of PDAF with `PDAF_init`.
 
 The routines for observation diagnostics can be organized in four groups
@@ -61 +64 @@
    * [wiki:PDAFomi_observation_diagnostics#PDAFomi_diag_get_HXmean PDAFomi_diag_get_HXmean] - access to observed ensemble mean
    * [wiki:PDAFomi_observation_diagnostics#PDAFomi_diag_get_HX PDAFomi_diag_get_HX] - access to observed ensemble 
-   * [wiki:PDAFomi_observation_diagnostics#PDAFomi_diag_get_ivar PDAFomi_diag_get_ivar]- access to inverse obs. error variances
+   * [wiki:PDAFomi_observation_diagnostics#PDAFomi_diag_get_ivar PDAFomi_diag_get_ivar]- access to inverse observation error variances
 
 
@@ -68 +71 @@
 === PDAFomi_set_obs_diag ===
 
-By default, the observation diagnostics are activated. However, as this functionality increases the required alloced memory it might be desirable to deactivate this functionality. The routine is used deactivate the observation diagnostics. It is also possible to re-activate the observation diagnostics at a later time. 
-
-The routine can be called by all processes, but it is sufficient to call it for those processes that handle observations, which usually are the filter processes. A common place is to call the routine in `init_pdaf` afer the initialization of PDAF in `PDAF_init`.
+By default, the observation diagnostics are active. However, as this functionality increases the required memory, it might be desirable to deactivate this functionality. This routine is used deactivate the observation diagnostics. It is also possible to re-activate the observation diagnostics at a later time. 
+
+The routine can be called by all processes, but it is sufficient to call it for those processes that handle observations, which are usually the filter processes. A common place is to call the routine in `init_pdaf` subsequently to the initialization of PDAF in `PDAF_init`.
 
 The interface is: 
@@ -99 +102 @@
 **Note:**
  * The computed RMSD is for the global model domain. Thus, in case of a parallelized model, all process sub-domains are taken into account and calling `PDAFomi_diag_obs_rmsd` will return the same value for all processes.
- * In Fortran user code the pointer should be declared in the form[[BR]] `REAL, POINTER :: rmsd_ptr(:)`[[BR]] It does not need to be allocated. The target vector has the length `nobs`.
- * If the observation diagnostics have not be activated by using `PDAFomi_set_obs_diag` the pointer array will not be set and `nobs=0` is returned. One can check this value before assessing the pointer array.
+ * In Fortran user code, the pointer should be declared in the form[[BR]] `REAL, POINTER :: rmsd_ptr(:)`[[BR]] It does not need to be allocated. The target vector has the length `nobs`.
+ * If the observation diagnostics have been deactivated by using `PDAFomi_set_obs_diag`, the pointer array will not be set and `nobs=0` is returned. One can check the value of `nobs` before assessing the pointer array.
  * A more extensive set of statistics can be obtained using the routine `PDAFomi_diag_stats`.
 
@@ -126 +129 @@
 **Note:**
  * The computed statistics are for the global model domain. Thus, in case of a parallelized model, all process sub-domains are taken into account and calling `PDAFomi_diag_stats` will return the same value for all processes.
- * In Fortran user code the pointer should be declared in the form[[BR]] `REAL, POINTER :: obsstats_ptr(:)`[[BR]] It does not need to be allocated. The target array has the size `(6, nobs)`.
- * If the observation diagnostics have not be activated by using `PDAFomi_set_obs_diag` the pointer array will not be set and `nobs=0` is. One can check this value before assessing the pointer array
+ * In Fortran user code, the pointer should be declared in the form[[BR]] `REAL, POINTER :: obsstats_ptr(:)`.[[BR]] It does not need to be allocated. The target array has the size `(6, nobs)`.
+ * If the observation diagnostics have been deactivated by using `PDAFomi_set_obs_diag`, the pointer array will not be set and `nobs=0` is. One can check this value before assessing the pointer array
  * The routine returns the centered RMSD as displayed in Taylor diagrams. The non-centered RMSD can be computed using `PDAFomi_diag_obs_rmsd`.
 
@@ -145 +148 @@
 
 **Note:**
- * `nobstypes` is commonly used as the upper limit of a loop running over all observation types. In this way `nobstypes` can be used with the PDAFomi_diag routines that return different observation-related arrays for a single observation type.
+ * `nobstypes` is commonly used as the upper limit of a loop running over all observation types. In this way, `nobstypes` can be used with the `PDAFomi_diag` routines that return different observation-related arrays for a single observation type.
 
 
@@ -160 +163 @@
 
 **Note:**
- * In Fortran user code the pointer should be declared in the form[[BR]] `INTEGER, POINTER :: dim_obs_ptr(:)`[[BR]] It does not need to be allocated.
- * If the observation diagnostics have not be activated by using [wiki:PDAFomi_set_obs_diag]. the pointer array will have length 1 and the observation dimension is returned as 0.
-
-
-
-== Acces to observation arrays ==
-
-The routine that provide access to observation arrays all work for a single observation type, which has to be specified as the first argument. TO process all observation types one can implement a loop `DO iobs = 1, nobstypes` where `nobstype` can be obtained with `PDAFomi_diag_nobstypes` which was described before.
+ * In Fortran user code, the pointer should be declared in the form[[BR]] `INTEGER, POINTER :: dim_obs_ptr(:)`[[BR]] It does not need to be allocated.
+ * If the observation diagnostics have been deactivated by using [wiki:PDAFomi_set_obs_diag], the pointer array will have length 1 and the observation dimension is returned as 0.
+
+
+
+== Access to observation arrays ==
+
+The routines that provide access to observation arrays all work for a single observation type, which is specified as the first argument. To process all observation types, one can implement a loop `DO iobs = 1, nobstypes` where `nobstype` can be obtained with `PDAFomi_diag_nobstypes`, which was described before.
 
 === PDAFomi_diag_get_obs ===
@@ -186 +189 @@
 
 **Notes:**
- * In case of a parallelized model, the vector `obs_p_prt` and the array `ocoord_p_prt` contain the values for the process-sub-domain of the calling processor.
- * In Fortran user code the pointer to the observation vector should be declared in the form[[BR]] `REAL, POINTER :: obs_p_ptr(:)`[[BR]] It does not need to be allocated. The target vector has the length `dim_obs_p_diag`.
- * In Fortran user code the pointer to the observation coordinates should be declared in the form[[BR]] `REAL, POINTER :: ocoord_p_ptr(:,:)`[[BR]] It does not need to be allocated. The target array has the size `(ncoord, dim_obs_p_diag)`.
- * If the observation diagnostics have not been activated by using `PDAFomi_set_obs_diag`, the pointers will not be set and `dim_obs_p_diag=0` and `ncoord=0` will be returned. These values can be checked before assessing the pointer arrays
+ * In case of a parallelized model, the vector `obs_p_prt` and the array `ocoord_p_prt` contain the values for the process sub-domain of the calling process.
+ * In Fortran user code, the pointer to the observation vector should be declared in the form[[BR]] `REAL, POINTER :: obs_p_ptr(:)`.[[BR]] It does not need to be allocated. The target vector has the length `dim_obs_p_diag`.
+ * In Fortran user code, the pointer to the observation coordinates should be declared in the form[[BR]] `REAL, POINTER :: ocoord_p_ptr(:,:)`.[[BR]] It does not need to be allocated. The target array has the size `(ncoord, dim_obs_p_diag)`.
+ * If the observation diagnostics have been deactivated by using `PDAFomi_set_obs_diag`, the pointers will not be set and `dim_obs_p_diag=0` and `ncoord=0` will be returned. These values can be checked before assessing the pointer arrays
  * The array `ocoord_p_ptr(:,:)` is organized as in the observation modules:
    * First index: index of different coordinate directions for observation specified by the second index
@@ -211 +214 @@
 
 **Notes:**
- * In case of a parallelized model, the vector `HXmean_p_prt` contains the observed ensemble mean for the process-sub-domain
- * In Fortran user code the pointer to the observed ensemble mean should be declared in the form[[BR]] `REAL, POINTER :: HXmean_p_ptr(:)`[[BR]] It does not need to be allocated. The target vector has the length `dim_obs_p_diag`.
- * If the observation diagnostics have not be activated by using `PDAFomi_set_obs_diag`, the pointer will not be set and `dim_obs_diag=0` will be returned. This value can be checked before assessing the pointer array.
+ * In case of a parallelized model, the vector `HXmean_p_prt` contains the observed ensemble mean for the process sub-domain
+ * In Fortran user code, the pointer to the observed ensemble mean should be declared in the form: [[BR]] `REAL, POINTER :: HXmean_p_ptr(:)`[[BR]] It does not need to be allocated. The target vector has the length `dim_obs_p_diag`.
+ * If the observation diagnostics have been deactivated by using `PDAFomi_set_obs_diag`, the pointer will not be set and `dim_obs_diag=0` will be returned. This value can be checked before assessing the pointer array.
 
 
@@ -231 +234 @@
 
 **Notes:**
- * In case of a parallelized model, the array `HX_p_prt` contains the observed ensemble for the process-sub-domain
- * In Fortran user code the pointer to the observed ensemble should be declared in the form[[BR]] `REAL, POINTER :: HX_p_ptr(:,:)`[[BR]] It does not need to be allocated. The target array has the size `(dim_obs_p_diag, dim_ens)`
- * If the observation diagnostics have not be activated by using `PDAFomi_set_obs_diag`, the pointer will not be set and `dim_obs_diag=0` will be returned. This value can be checked before assessing the pointer array.
+ * In case of a parallelized model, the array `HX_p_prt` contains the observed ensemble for the process sub-domain.
+ * In Fortran user code, the pointer to the observed ensemble should be declared in the form:[[BR]] `REAL, POINTER :: HX_p_ptr(:,:)`[[BR]] It does not need to be allocated. The target array has the size `(dim_obs_p_diag, dim_ens)`
+ * If the observation diagnostics have been deactivated by using `PDAFomi_set_obs_diag`, the pointer will not be set and `dim_obs_diag=0` will be returned. This value can be checked before assessing the pointer array.
 
 
@@ -251 +254 @@
 
 **Notes:**
- * In case of a parallelized model, the vector `ivar_p_prt` contains the observed ensemble mean for the process-sub-domain
- * In Fortran user code the pointer to the vector of inverse observation variances should be declared in the form[[BR]] `REAL, POINTER :: ivar_p_ptr(:)`[[BR]] It does not need to be allocated. The target vector has the length `dim_obs_p_diag`.
- * If the observation diagnostics have not be activated by using `PDAFomi_set_obs_diag` the pointer will not be set and `dim_obs_diag=0` will be returned. This value can be checked before assessing the pointer array.
+ * In case of a parallelized model, the vector `ivar_p_prt` contains the observed ensemble mean for the process sub-domain.
+ * In Fortran user code, the pointer to the vector of inverse observation variances should be declared in the form[[BR]] `REAL, POINTER :: ivar_p_ptr(:)`[[BR]] It does not need to be allocated. The target vector has the length `dim_obs_p_diag`.
+ * If the observation diagnostics have been deactivated by using `PDAFomi_set_obs_diag`, the pointer will not be set and `dim_obs_diag=0` will be returned. This value can be checked before assessing the pointer array.
  * If the feature `thisobs%inno_omit` is used (see the [wiki:PDAFomi_additional_functionality page Additional functionality of PDAF-OMI]), the inverse variance of the omitted observations will show the small value set by `inno_omit`. One can use this information to exclude such observations when analyzing differences between observations and observed ensemble.