Changes between Initial Version and Version 1 of PDAF_debugging

Timestamp:

Feb 20, 2023, 2:42:00 PM (15 months ago)

Author:

lnerger

Comment:

--

PDAF_debugging

@@ +1 @@
+= PDAF Debugging Information = 
+
+
+[[PageOutline(2-3,Contents of this page)]]
+
+== Overview ==
+
+When implementing PDAF with your model or adding functionality like extending the state vector or adding support for new observations, it cab useful to check whether the inputs to the PDAF routines are correctly used inside PDAF. For this purpose, PDAF provides a debugging functionality. It allows you to activate debug output e.g. for a single local analysis domain on a single process of a complex application of a local filter like LEKSTF.
+
+Note: When you use PDAF-OMI for the observation handling, there is a separate debug functionality for the observation part. For details see the [wiki:OMI_debugging documentation on PDAF-OMI debuggging].
+
+
+== Activating Debugging Output ==
+
+Debugging output is activated by a call 
+{{{
+   INTEGER :: dbg_id  ! Debugging flag: >0 for debug output; =0 for no debug output
+
+   CALL PDAF_set debug_flag(dbg_id) 
+}}}
+Setting the single argument of `PDAFomi_set_debug_flag` to a value larger 0 will active the output, while =0 will deactivate it.
+
+The call to `PDAF_set_debug_flag` call can be inserted in different routines. Some recommended places are
+- `init_pdaf`: If the call is inserted before `PDAF_init` is called, one obtains debug output from `PDAF_init`. This allows one to check if the control parameters are handed over correctly and whether the values of the initial ensemble are correct inside PDAF
+- `assimilate_pdaf`: If the call is inserted before `PDAF_assimilate_*` or `PDAF_put_state_*` are called, one obtains debug output for the full analysis step. This variant is particularly useful for the global filters or the 3D-Var schemes.
+- `init_dim_l_pdaf`: If the call is used in this routine one can activate the debug output for a single local analysis domain. For example, to activate debug output only for the local analysis domain `domain_p=10` and filter process 0 (`mype_filter=0`), one uses
+{{{
+SUBROUTINE init_dim_l_pdaf(step, domain_p, dim_l))
+
+  USE mod_parallel_pdaf, ONLY: mype_filter
+
+  ...
+
+  IF (domain_p==10 .AND. mype_filter==0) THEN
+    CALL PDAF_set_debug_flag(domain_p)
+  ELSE
+    CALL PDAF_set_debug_flag(0)
+  ENDIF
+
+  ...
+
+}}}
+
+For the debugging it is useful to keep the number of observations low since for a large number of observations or a large ensemble, the output will be very lengthy. To this end, it can be useful to intentionally reduce the size of the local state vector or the ensemble size for the debugging. For the localized filters it is recommended to only activate the debugging for a single local analysis domain as shown above. The particular domain index can be chosen e.g. based on the coordinates of the domain, which are usually determined in `init_dim_l_pdaf`. Thus, if one encounters an issue in the analysis step for some coordinates one can find the corresponding coordinates in `init_dim_l_pdaf` and subsequently use `PDAF_set_debug_flag` to activate the debug output for this location.
+
+For the domain-local filters vectors like the local state vector are shown with their full length. Likewise vector or matrices whose dimension is the ensemble size are shown with their full length.
+
+For the global filters the state vector or the innovation can have a high dimension. To keep the debug output limited, the outputs of the global filters and the 3D-Var methods are generally limited to the first 6 elements of vectors that have the size of the state vector (like single ensemble states) or the size of the observation vector (like the innovation). Only vectors or matrices whose dimension is the ensemble size are shown with their full length.
+
+
+