Changes between Version 2 and Version 3 of PDAF_OMI_Overview_PDAF3


Ignore:
Timestamp:
May 27, 2025, 3:01:17 PM (5 days ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • PDAF_OMI_Overview_PDAF3

    v2 v3  
    3636[[PageOutline(2-3,Contents of this page)]]
    3737
    38 PDAF-OMI (Observation Module Infrastructure) provides a structured and modularized approach to implement the observation handling for PDAF. Here we describe OMI in the context of the PDAF3 assimilation routines.
     38PDAF-OMI (Observation Module Infrastructure) provides a structured and modularized approach to implement the observation handling for PDAF.
    3939
    40 || The documention on PDAF-OMI for PDAF2 is still available: [wiki:PDAF_OMI_Overview PDAF-OMI in PDAF2] ||
     40|| Here, we describe OMI in the context of the PDAF3. The documention on PDAF-OMI for PDAF2 is still available: [wiki:PDAF_OMI_Overview PDAF-OMI in PDAF2] ||
    4141
    42 However, one can also [wiki:ImplementationofAnalysisStep_noOMI implement the assimilation without using PDAF-OMI], but using the full interface routines requires significantly more programming.
     42However, one can also [wiki:ImplementationofAnalysisStep_noOMI implement the assimilation using PDAF's full interface without using PDAF-OMI], but this expert mode requires significantly more programming.
    4343
    44 PDAF-OMI permits to implement the observation handling with a low number of user-provided routines. Each observation type is encapsulated in a Fortran module (referred to as 'observation module'). With this, the implementations of different observation types cannot interfere which each other. The code structure is motivated from object-oriented programming, but we avoid here the abstract level of object-orientation in Fortran.
    45 
    46 To guarantee that each observation type (like sea surface temperature data from some satellite sensor, or altimetry data) is handled independently from the others one implements with OMI one Fortran module for each observation type.  Thus, different developers can implement observation types without interfering with the implementations by others.
    47 
    48 Only two routines (in the case of global ensemble filters) or three routines (in the case of localized ensemble filters) need to be implemented for an observation type. Always required are:
    49  - '''init_dim_obs'''[[br]]
    50   Reads observations from a file and initialize the information describing the observations
    51  - '''obs_op'''[[br]]
    52   Calls an observation operator routine
    53 For the domain localized filters LETKF/LESTKF/LNETF/LKNETF one more  routine is required:
    54  - '''init_dim_obs_l''' [[br]]
    55   Calls a generic routine to initialize local observations
    56 Only in the case of '''3D-Var''', two more routines are required:
    57  - '''obs_op_lin'''[[br]]
    58   Calls a routine for the linearized observation operator (equal to `obs_op` if this is linear)
    59  - '''obs_op_adj'''[[br]]
    60   Calls a routine for the adjoint observation operator
    61 
    62 The only 'real' coding effort will be in '''init_dim_obs''' because the other routines merely call a subroutine provided by PDAF-OMI. All functionality needed during the analyis step bases on variables that are initialized by these routines and is provided by PDAF-OMI.
    63 
    64 
     44PDAF-OMI permits to implement the observation handling with a low number of user-provided routines. Each observation type is encapsulated in a Fortran module (referred to as 'observation module'). With this, the implementations of different observation types cannot interfere which each other. The code structure is motivated from object-oriented programming, but we avoid here the abstract level of object-orientation in Fortran. The modularization allows different developers to implement observation types without interfering with the implementations by others.
    6545
    6646
    … …  
    7151  One observation-specific Fortran module for each observation type
    7252 - '''callback_obs_pdafomi.F90'''[[br]]
    73   PDAF can only call a generic call-back routine for the different functionaliteis, e.g. `init_dim_obs_pdafomi` or `obs_op_pdafomi`. This file contains these generic call-back routines, in which the observation-specific subroutines of the differnt observation modules are called. Thus, the subroutines in this file are merely pass-through routines without own functionality.
     53  PDAF can only call a generic call-back routine for the different functionalities, e.g. `init_dim_obs_pdafomi` or `obs_op_pdafomi`, see below. This file contains these generic call-back routines, in which the observation-specific subroutines of the different observation modules are called. Thus, the subroutines in this file are merely pass-through routines without own functionality.
    7454 - '''PDAF-OMI core routines'''[[br]]
    7555  These routines are part of the PDAF library and provide functionality for observation handling, localization, and observation operators
    7656
    77 Figure 1 shows the call structure for the analysis step with PDAF-OMI. For the analysis step, the core routines of PDAF (green) call different user-provided call-back functions. Some of these routines, like those performing state localization, that are not related to observations (blue). PDAF-OMI is concerned with the routines related to observations (red and purple).
     57Figure 1 shows the call structure for the analysis step with PDAF-OMI. For the analysis step, the core routines of PDAF (green) call different user-provided call-back functions. Only the routines in the red box 'callback_obs_pdafomi.F90' are related to observations. PDAF-OMI is concerned with these routines and the observation modules (purple). The call-back functions shown in cyan are only used for domain-localized filters.
    7858
    7959[[Image(//pics/PDAFstructure_PDAF-OMI_PDAF3.png)]]
    80 [[BR]]'''Figure 1:''' Call-structure of PDAF with OMI: (green) PDAF library with core and omi; (blue) call-back routines; (red) OMI call-back routines; (purple) observation-specific modules. If [wiki:PDAFlocal_overview PDAFlocal] is not used, there will be two additional routines `g2l_state` and `l2g_state` relating to localization.
     60[[BR]]'''Figure 1:''' Call-structure of PDAF with OMI: (green) PDAF library with core and omi; (blue) call-back routines; (red) OMI call-back routines; (purple) observation-specific modules. The cyan color marks call-back functions for localization. If [wiki:PDAFlocal_overview PDAFlocal] is not used, there will be two additional routines `g2l_state` and `l2g_state` relating to localization.
    8161
     62With OMI, the functionality to handle observations is included in generic routines in `callback_obs_pdafomi.F90` and observation-specific modules (purple `obs_*_pdafomi` in the third column in Fig. 1, denoted obs-module below). Based on the information initialized in the call-back routines, PDAF will perform further observation handling internally. There is one obs-module per observation type with contains these routines. For example, one can have one obs-module for the satellite sea surface temperature from one data provider and another one for sea level anomaly data. Important is that each of these obs-modules, which are further described below, is independent from the others. This allows us to switch between different combinations of observations ensuring that their implementations don’t interfere.
    8263
    83 With OMI, the functionality to handle observations is included in generic routines and observation-specific modules (obs_*_pdafomi in the third column in Fig. 1, denoted obs-module below). Based on the information initialized in the call-back routines, PDAF can perform further observation handling internally. Only the routines mentioned above that perform observation-specific operations (initialization, observation operator, localization) need to be implemented. There is one obs-module per observation type with contains these routines. For example, one can have one obs-module for the satellite sea surface temperature from one data provider and another one for sea level anomaly data. Important is that each of these obs-modules, which are further described below, is independent from the others. This allows us to switch between different combinations of observations ensuring that their implementations don’t interfere.
     64For each observation type, one needs to implement the follwing routines in the respective obs-module. For ensemble-based filters one needs:
     65 - '''init_dim_obs'''[[br]]
     66  Reads observations from a file and initializes all variables holding the information about one observation type.
     67 - '''obs_op'''[[br]]
     68  Applies the observation operator to a state vector. One can call an observation operator routine provided by PDAF-OMI, or one can to implement a new operator.
     69 - '''init_dim_obs_l''' [[br]]
     70  Calls a generic routine to initialize local observations (only for domain-localizated filters)
     71Only in the case of '''3D-Var'''methods, two more routines are required:
     72 - '''obs_op_lin'''[[br]]
     73  Calls a routine for the linearized observation operator (equal to `obs_op` if this is linear)
     74 - '''obs_op_adj'''[[br]]
     75  Calls a routine for the adjoint observation operator
    8476
    85 Since the actual operations are performed in the obs-modules `obs_*_pdafomi`, the generic call-back routines (init_dim_obs_pdafomi, obs_op_pdafomi, init_dim_obs_l_pdafomi, localize_covar_pdafomi) are reduced to pass-through routines. Thus, each of these routines contains only calls to one observation-specific routine from each obs-module.
    86 Because the generic call-back routines are very compact, they are collected into the file `callback_obs_pdafomi.F90`. This is mainly for convenience, because all these routines are now ‘in one place’. Thus, when adding a new observation type only a new subroutine call has to be added to each of the routines in this file. (Note, that callback_obs_pdafomi.F90 does not define a Fortran module. This is because the call-back routines of PDAF are not contained in a module as this would require to compile the module together with the PDAF core so that the PDAF core would no longer be generic.)
     77The only 'real' coding effort will be in '''init_dim_obs''' because the other routines merely call a subroutine provided by PDAF-OMI. All functionality needed during the analyis step bases on variables that are initialized by these routines and is provided by PDAF-OMI. For each observation type, PDAF-OMI uses a data structure (Fortran 'type') that is initialized in `init_dim_obs` in the obs-module. 
    8778
    88 Each obs-module contains four routines:
    89 1. `init_dim_obs` initializes all variables holding the information about one observation type.   
    90 1. `obs_op` applies the observation operator to a state vector. One can call an observation operator routine provided by PDAF-OMI, or one can to implement a new operator.
    91 1. `init_dim_obs_l` calls a PDAF-OMI routine to initialize the observation information corresponding to a local analysis domain. One can set localization parameters, like the localization radius, for each observation type.
    92 1. `localize_covar` calls a PDAF-OMI routine to apply covariance localization for the LEnKF. One can set localization parameters, like the localization radius, for each observation type.
     79Since the actual operations are performed in the obs-modules `obs_*_pdafomi`, the generic call-back routines (`init_dim_obs_pdafomi`, `obs_op_pdafomi`, `init_dim_obs_l_pdafomi`) are reduced to pass-through routines. Thus, each of these routines contains only calls to one observation-specific routine from each obs-module.
     80Because the generic call-back routines are very compact, they are collected into the file `callback_obs_pdafomi.F90`. This is mainly for convenience, because all these routines are now ‘in one place’.
    9381
    94 For each observation type, PDAF-OMI uses a data structure (Fortran 'type') that is initialized in `init_dim_obs` in the obs-module. The set of routines in `callback_obs_pdafomi.F90` provide the observation handling for all filters and smoothers provided by PDAF. Thus, once the routines in an obs-module are implemented for a particular observation and the subroutine calls in `callback_obs_pdafomi.F90` for this observation type are inserted, one can use this observation type with all of PDAF's assimilation methods.
     82The set of routines in `callback_obs_pdafomi.F90` provide the observation handling for all data assimilation methods provided by PDAF. Thus, once the routines in an obs-module are implemented for a particular observation and the subroutine calls in `callback_obs_pdafomi.F90` for this observation type are inserted, one can use this observation type with all of PDAF's assimilation methods.
    9583
    96 Note that `init_dim_obs_l` is only required if one plans to use domain-localized filters like LESTKF, LETKF or LNETF. Likewise, `localize_covar` is only required if on likes to use the loalized EnKF (LEnKF).
    9784
    9885== Further documentation of PDAF-OMI ==
    … …  
    10491 - [wiki:OMI_observation_operators Observation Operators]
    10592 - [wiki:OMI_debugging Debugging Functionality]
    106  - [wiki:OMI_ImplementationofAnalysisStep Implementing the analysis step with OMI]
    107    - [wiki:ImplementAnalysisLocal Implementation for Local Filters]
    108    - [wiki:ImplementAnalysisGlobal Implementation for Global Filters]
    109    - [wiki:ImplementAnalysislenkfOmi Implementation for localized EnKF]
     93 - [wiki:ImplementationofAnalysisStep Implementing the analysis step]
    11094 - [wiki:Porting_to_OMI Porting an existing implementation to OMI]
    11195 - [wiki:PDAFomi_additional_functionality Additional functionality of OMI]
    … …  
    11498== Implementation examples ==
    11599
    116 From PDAF V1.16, the PDAF package provides several implementation examples:
     100The PDAF package provides several implementation examples:
    117101
    118102 - '''/tutorial/online_2D_serialmodel'''[[BR]]
    … …  
    129113 - PDAF V2.3 added support for non-diagonal observation error covariance matrices **R** while previous versions only supported diagonal observation error covariance matrices  (though, the observation variances can vary). Using nondiagonal **R**-matrices, requires a user-supplied code for operations relating to **R** (see the documentation on the implemenetation for [wiki:OMI_nondiagonal_observation_error_covariance_matrices using non-diagonal R-matrices with OMI])
    130114 - OMI currently only includes observation operators with linear interpolation and for observation located at grid points.
    131  - We have not tested interoperability with other programming languages. Generally Fortran derived data types and C structs should be compatible. Obviously, taking the Fortran routines and calling C functions to perform the actual initializations will work.
     115 - We have not tested interoperability with other programming languages. Generally Fortran derived data types and C structs should be compatible. Obviously, taking the Fortran routines and calling C functions to perform the actual initializations will work. (However, pyPDAF provides interoperability with Python).