Version 1 (modified by 4 weeks ago) (diff) | ,
---|
User-provided routine for initialization of local observations
PDAF-OMI provides the routine PDAFomi_init_dim_obs_l to initialize local observations in a routine init_dim_obs_p_OBSTYPE of an PDAF-OMI observation module. PDAFomi_init_dim_obs_l
provides a convenient functionality with observation search for all isotropic and non-isotropic localization variants in different dimensions. However, because the routine covers all cases with various IF-checks it can be relatively slow.
While we improved the search performance in PDAF V2.3, we also found that a user-provided routine that is designed for the particular case of the user's application can be significantly faster. Thus, if you have the impression that PDAFomi_init_dim_obs_l
is 'too slow' in your application, you can implement 'your own' case -specific variant of PDAFomi_init_dim_obs_l
. In PDAF V2.3 we added routines that help in the implementation, by initialized parameters and allocating arrays of PDAF-OMI, so that one does not need to perform such oeprations in the user code.
Structure of a user-provided routine
An example of a user-provided initialization routine for local observations is the file init_dim_obs_l_pdafomi_user.F90
in /tutorial/offline_2D_parallel
.
The calling interface of the user-provided routine should usually be the same as that of PDAFomi_init_dim_obs_l
. This is for isotropic localization:
SUBROUTINE init_dim_obs_l_pdafomi_user(thisobs_l, thisobs, coords_l, locweight, cradius, & sradius, cnt_obs_l_all) USE PDAFomi, & ! Include observation type definitions and OMI-provided routines ONLY: obs_f, obs_l, & PDAFomi_set_dim_obs_l, PDAFomi_set_localization IMPLICIT NONE TYPE(obs_f), INTENT(inout) :: thisobs !< Data type with full observation TYPE(obs_l), TARGET, INTENT(inout) :: thisobs_l !< Data type with local observation REAL, INTENT(in) :: coords_l(thisobs%ncoord) !< Coordinates of current analysis domain INTEGER, INTENT(in) :: locweight !< Type of localization function REAL, INTENT(in) :: cradius !< Vector of localization cut-off radii REAL, INTENT(in) :: sradius !< Vector of support radii of localization function INTEGER, INTENT(inout) :: cnt_obs_l_all !< Local dimension of observation vector over all observation types
The structure of the body of the routine needs to be as follows
IF (thisobs%doassim == 1) THEN CALL PDAFomi_set_localization(thisobs_l, cradius, sradius, locweight) ... Loop over full observations and count number 'cnt_obs' of observations within localization radius ... CALL PDAFomi_set_dim_obs_l(thisobs_l, thisobs, cnt_obs_l_all, cnt_obs) ... Initialize local observation arrays ... thisobs_l%id_obs_l(cnt_obs_l) = i ! index of local obs. in full obs. vector thisobs_l%distance_l(cnt_obs_l) = SQRT(distance2) ! distance thisobs_l%cradius_l(cnt_obs_l) = thisobs_l%cradius(1) ! cut-off radius thisobs_l%sradius_l(cnt_obs_l) = thisobs_l%sradius(1) ! support radius ENDIF
Notes:
- The check
thisobs%doassim==1
is mandatory because init_dim_obs_l_OBSTYPE is called for all observations. cnt_obs_l
is the counter of the valid local observations inside the loop, whilei
is the index of a local observation on the full observation vector- We recommend to compute use the square distance
distance2
and only compute the actual distance asSQRT(distance2)
only for those observations that are within the localization cut-off radius. Since compute a square-root is a costly operation, one should only compute it if needed. - In the tutorial example routine we use a module to enclose the user routine. This allows for syntax checking, but is not mandatory.
- The initialization of the local observation arrays of
thisobs_l
can be done by the routinePDAFomi_store_obs_l_index
provided by PDAF-OMI (see below). However, for performance reasons we recommend to use the direct initialization if possible. cnt_obs_l_all
should only be passed through from PDAF to the PDAFomi routines. If it is changed by the user, the consistency of the observation-handling inside PDAF-OMI will be broken.
PDAF-OMI provided helper routines
PDAFomi_set_localization
This routine stores the localization parameters (cradius, sradius, locweight). It further allocates localization parameter arrays of thisobs_l
. The inputs to the routine are values provided as arguments in the call to init_dim_obs_l_pdafomi_user
.
The full interface of the routine is
SUBROUTINE PDAFomi_set_localization(thisobs_l, cradius, sradius, locweight) TYPE(obs_l), INTENT(inout) :: thisobs_l ! Data type with local observation REAL, INTENT(in) :: cradius ! Localization cut-off radius REAL, INTENT(in) :: sradius ! Support radius of localization function INTEGER, INTENT(in) :: locweight ! Type of localization function
For non-isotropic localization there is the alternative routine PDAFomi_set_localization_noniso.
PDAFomi_set_dim_obs_l
This routine stores the local number of observations cnt_obs
and uses the value of cnt_obs_l_all
for OMI-internal initializations. The routine also does further initializations for the OMI-internal handling of observations.
The full interface is
SUBROUTINE PDAFomi_set_dim_obs_l(thisobs_l, thisobs, cnt_obs_l_all, cnt_obs_l) TYPE(obs_f), INTENT(inout) :: thisobs ! Data type with full observation TYPE(obs_l), INTENT(inout) :: thisobs_l ! Data type with local observation INTEGER, INTENT(inout) :: cnt_obs_l_all ! Local dimension of observation vector over all obs. types INTEGER, INTENT(inout) :: cnt_obs_l ! Local dimension of single observation type vector
here thisobs
, thisobs_l
, and cnt_obs_l_all
are just passed to the routine.
Additional helper routines
We recommend to perform the initialization of the vectors in thisobs_l
at the last step of init_dim_obs_l_pdafomi_user
in this user-provided routine. For convenience we, however, provide a routine for this step.
PDAFomi_store_obs_l_index
This routine takes the index 'cnt_obs_l' in the example above (idx
below), the distance as well as the local cut-off radius (cradius_l
) and support radius (sradius_l
) and stores the values in the vectors of thisobs_l
.
SUBROUTINE PDAFomi_store_obs_l_index(thisobs_l, idx, id_obs_l, distance, & cradius_l, sradius_l) TYPE(obs_l), INTENT(inout) :: thisobs_l ! Data type with local observation INTEGER, INTENT(in) :: idx ! Element of local observation array to be filled INTEGER, INTENT(in) :: id_obs_l ! Index of local observation in full observation array REAL, INTENT(in) :: distance ! Distance between local analysis domain and observation REAL, INTENT(in) :: cradius_l ! cut-off radius for this local observation ! (directional radius in case of non-isotropic localization) REAL, INTENT(in) :: sradius_l ! support radius for this local observation ! (directional radius in case of non-isotropic localization)
PDAFomi_store_obs_l_index_vdist
For 2+1D factorized localization the distance in the vertical direction has to be stored separately. For this the alternativve routine PDAFomi_store_obs_l_index_vdist
is used.
SUBROUTINE PDAFomi_store_obs_l_index_vdist(thisobs_l, idx, id_obs_l, distance, & cradius_l, sradius_l, vdist) TYPE(obs_l), INTENT(inout) :: thisobs_l ! Data type with local observation INTEGER, INTENT(in) :: idx ! Element of local observation array to be filled INTEGER, INTENT(in) :: id_obs_l ! Index of local observation in full observation array REAL, INTENT(in) :: distance ! Distance between local analysis domain and observation REAL, INTENT(in) :: cradius_l ! cut-off radius for this local observation ! (directional radius in case of non-isotropic localization) REAL, INTENT(in) :: sradius_l ! support radius for this local observation ! (directional radius in case of non-isotropic localization) REAL, INTENT(in) :: vdist ! support radius in vertical direction for 2+1D factorized localization