Changes between Version 1 and Version 2 of OfflineInitPdaf_PDAF3


Ignore:
Timestamp:
Sep 1, 2025, 11:01:02 AM (21 hours ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • OfflineInitPdaf_PDAF3

    v1 v2  
    2020The PDAF release provides example code for the offline mode in `tutorial/offline_2D_parallel`. We refer to this code to use it as a basis.
    2121
    22 The routine `PDAF_init` is called to initialize PDAF. This call sets parameters for the data assimilation, chooses the data assimilation method and initializes the ensemble. In the tutorial and template codes we collect the initialization of all variables required for the call to `PDAF_init` into the single subroutine `init_pdaf_offline`, which yields a clean code. The file `templates/offline/init_pdaf_offline.F90` provides a commented template for this routine, which can be used as the basis of the implementation.
    23 
    24 `PDAF_init` itself calls a user-supplied call-back routine to initialize the ensemble of model states. In the example, this is the routine in the file `init_ens_offline.F90`.
     22The initialization of PDAF is done in the subroutine `init_pdaf`. This routine is called from the driver program code and sets all variables required for the initialization. Then the subroutine `PDAF3_init` is called, which performs the actual internal initialization of PDAF. Thus, it sets the internal parameters for the data assimilation, chooses the data assimilation method, allocates the internal ensemble array, and initializes the ensemble. The file `templates/offline/init_pdaf_offline.F90` provides a commented template for this routine, which can be used as the basis of the implementation.
     23
     24`PDAF3_init` itself calls a user-supplied call-back routine to initialize the ensemble of model states. In the example, this is the routine in the file `init_ens_offline.F90`.
    2525
    2626== Using `init_pdaf_offline` ==
    … …  
    2828In the offline mode, the routine `init_pdaf_offline` is executed after the initialization of the parallelization.
    2929
    30 In `init_pdaf_offline` a number of variables are defined that are used in the call to `PDAF_init` as described below.  There are also a few variables that are initialized in `init_pdaf_offline` but not used in the call to `PDAF_init`. These are variables that are specific for the data assimilation system, but only shared in between the user-supplied routines. For the tutorial example, these variables are described below in the section '[#Othervariablesfortheassimilation Other variables for the assimilation]'.
     30In `init_pdaf_offline` a number of variables are defined that are used in the call to `PDAF3_init` as described below.  There are also a few variables that are initialized in `init_pdaf_offline` but not used in the call to `PDAF3_init`. These are variables that are specific for the data assimilation system, but only shared in between the user-supplied routines. For the tutorial example, these variables are described below in the section '[#Othervariablesfortheassimilation Other variables for the assimilation]'.
    3131
    3232The example implementation and the template code allow to specify all options at run time using a command line parser. These options are specified as the combination `-VARIABLE VALUE`. This method provides a convenient way to define an experiment and could also be used for other models. The parser module is provided by the file `tutorial/offline_2D_parallel/parser_mpi.F90`
    3333
    34 == Arguments of `PDAF_init` ==
    35 
    36 In the tutorial codes and the template, the call to `PDAF_init` is fully implemented. Here, we provide an overview of the arguments that are set in the call to `PDAF_init`.
    37 
    38 The call to `PDAF_init` has the following structure:
    39 {{{
    40 CALL PDAF_init(filtertype, subtype, step_null, &
     34== Arguments of `PDAF3_init` ==
     35
     36In the tutorial codes and the template, the call to `PDAF3_init` is fully implemented. Here, we provide an overview of the arguments that are set in the call to `PDAF3_init`.
     37
     38The call to `PDAF3_init` has the following structure:
     39{{{
     40CALL PDAF3_init(filtertype, subtype, step_null, &
    4141               filter_param_i, length_filter_param_i, &
    4242               filter_param_r, length_filter_param_r, &
    43                COMM_model, COMM_filter, COMM_couple, &
    44                task_id, n_modeltasks, filterpe, &
    4543               init_ens_offline, screen, status_pdaf)
    4644}}}
    … …  
    5856  1. The value of the forgetting factor controlling inflation (required to be larger than zero)
    5957 * **length_filter_param_r**:[[BR]] An integer defining the length of the array `filter_param_r`. The entries in the array are parsed up to this index.
    60  * `COMM_model`:[[BR]] The communicator variable `COMM_model` as initialized by `init_parallel_pdaf`. If the model-communicator is named differently in the actual program, the name has to be adapted
    61  * `COMM_filter`:[[BR]] The communicator variable `COMM_filter` as initialized by `init_parallel_pdaf`.
    62  * `COMM_couple`:[[BR]] The communicator variable `COMM_couple` as initialized by `init_parallel_pdaf`.
    63  * `task_id`:[[BR]] The index of the model tasks  as initialized by `init_parallel_pdaf`. Always 1 for the offline mode
    64  * `n_modeltasks`:[[BR]] The number of model tasks as defined before the call to `init_parallel_pdaf`.
    65  * `filterpe`:[[BR]] The flag showing if a process belongs to `COMM_filter` as initialized by `init_parallel_pdaf`.
    66  * **init_ens_offline**:[[BR]] The name of the user-supplied routine that is called by `PDAF_init` to initialize the ensemble of model states. (See below: '[#User-suppliedroutineinit_ens_offline User-supplied routine init_ens_offline]'
     58 * **init_ens_offline**:[[BR]] The name of the user-supplied routine that is called by `PDA3_init` to initialize the ensemble of model states. (See below: '[#User-suppliedroutineinit_ens_offline User-supplied routine init_ens_offline]'
    6759 * `screen`:[[BR]] An integer defining whether information output is written to the screen (i.e. standard output). The following choices are available:
    6860  * 0: quite mode - no information is displayed.
    6961  * 1: Display standard information (recommended)
    7062  * 2: as 1 plus display of timing information during the assimilation process
    71  * `status_pdaf`:[[BR]] An integer used as status flag of PDAF. If `status_pdaf` is zero upon exit from `PDAF_init`, the initialization was successful. An error occurred for non-zero values. (The error codes are documented in the routine PDAF_init.)
     63 * `status_pdaf`:[[BR]] An integer used as status flag of PDAF. If `status_pdaf` is zero upon exit from `PDAF3_init`, the initialization was successful. An error occurred for non-zero values. (The error codes are documented in the routine PDAF3_init.)
    7264
    7365PDAF uses two arrays **filter_param_i** and **filter_param_r** to respectively specify integer and real-valued options for PDAF. As described above, 2 integer values (state vector size, ensemble size) and 1 real value (forgetting factor) are mandatory. Additional options can be set by specifying a larger array and setting the corresponding size value (`length_filter_param_i`, `length_filter_param_r`). However, with PDAF V3.0 it can be more convenient to use the subroutines `PDAF_set_iparam` and `PDAF_set_rparam`, which are explained further below.
    … …  
    7567An **overview of available integer and real-valued options** for each DA method can be found on the page [wiki:AvailableOptionsforInitPDAF Available options for the different DA methods]. The available options for a specific DA method can also be displayed by running the assimilation program for the selected DA method setting `subtype = -1`. (In the tutorial and template codes one can set `-subtype -1` on the command line). Generally, available options and valid settings are also listed in `mod_assimilation.F90` of the tutorials and template codes.
    7668
    77 We recommended to check the value of `status_pdaf` in the program after PDAF_init (and potentially `PDAF_set_iparam and `PDAF_set_rparam`) are executed. Only if its value is 0, the initialization was successful.
     69We recommended to check the value of `status_pdaf` in the program after PDAF3_init (and potentially `PDAF_set_iparam and `PDAF_set_rparam`) are executed. Only if its value is 0, the initialization was successful.
     70
     71**Notes:**
     72- Implementations done before PDAF V3.0, used the routine `PDAF_init` which is described on the [wiki:OfflineInitPdaf_PDAF23 Page on initialized PDAF without the PDAF3 interface].
     73- For using `PDAF3_init`, the routine `init_parallel_pdaf` has to contain a call to `PDAF3_set_parallel`. This is included in the template and tutorial codes for PDAF V3.0 and later.
    7874
    7975=== Note on available options ===
    … …  
    8581== Other variables for the assimilation ==
    8682
    87 The routine `init_pdaf_offline` in the example also initializes several variables that are not used to call `PDAF_init`. These variables control some functionality of the user-supplied routines for the data assimilation system and are shared with these routines through `mod_assimilation`. These variables are for example:
     83The routine `init_pdaf_offline` in the example also initializes several variables that are not used to call `PDAF3_init`. These variables control some functionality of the user-supplied routines for the data assimilation system and are shared with these routines through `mod_assimilation`. These variables are for example:
    8884 * `cradius`: Localization cut-off radius in grid points for the observation domain
    8985 * `sradius`: support radius, if observation errors are weighted (i.e. `locweight>0`)
    … …  
    110106== User-supplied routine `init_ens_offline` ==
    111107
    112 The user-supplied routine that we named `init_ens_offline` here, is the call-back routine that is called by PDAF through the defined interface described below. For the offline mode the routine is called by all processes. `init_ens_pdaf` is only called by `PDAF_init` if no error occurred before; thus the status flag is zero.
     108The user-supplied routine that we named `init_ens_offline` here, is the call-back routine that is called by PDAF through the defined interface described below. For the offline mode the routine is called by all processes. `init_ens_pdaf` is only called by `PDAF3_init` if no error occurred before; thus the status flag is zero.
    113109
    114110The interface details can be looked up in the template and tutorial codes. It is the following:
    … …  
    118114}}}
    119115with
    120  * `filtertype`, `integer, intent(in)`:[[BR]]The type of filter algorithm as given in the call to `PDAF_init`
    121  * `dim_p`, `integer, intent(in)`:[[BR]] The size of the state dimension for the calling process as specified in the call to `PDAF_init`
     116 * `filtertype`, `integer, intent(in)`:[[BR]]The type of filter algorithm as given in the call to `PDAF3_init`
     117 * `dim_p`, `integer, intent(in)`:[[BR]] The size of the state dimension for the calling process as specified in the call to `PDAF3_init`
    122118 * `dim_ens`, `integer, intent(in)`:[[BR]]The size of the ensemble
    123119 * `state_p`, `real, dimension(dim_p), intent(inout)`:[[BR]]Array for the local model state of the calling process (can be used freely for ensemble-based methods)
    124120 * `Uinv`, `real, dimension(dim_ens-1, dim_ens-1), intent(inout)`:[[BR]]A possible weight matrix (Not relevant for ensemble-based methods)
    125121 * `ens_p`, `real, dimension(dim_p, dim_ens), intent(inout)`:[[BR]] The ensemble array, which has to be filled with the ensemble of model states.
    126  * `flag`, `integer, intent(inout)`:[[BR]]Status flag for PDAF. It is 0 upon entry and can be set by in the user-supplied routine, depending on the success of the ensemble initialization.  Preferably, values above 102 should be used for failures to avoid conflicts with the error codes defined within PDAF_init.
     122 * `flag`, `integer, intent(inout)`:[[BR]]Status flag for PDAF. It is 0 upon entry and can be set by in the user-supplied routine, depending on the success of the ensemble initialization.  Preferably, values above 102 should be used for failures to avoid conflicts with the error codes defined within PDAF3_init.
    127123
    128124=== Defining the state vector ===
    … …  
    145141== Setting additional options ==
    146142
    147 In PDAF V3.0 we added the possibility to set options for PDAF after the call to `PDAF_init`. For these there are the subroutines
     143In PDAF V3.0 we added the possibility to set options for PDAF after the call to `PDAF3_init`. For these there are the subroutines
    148144{{{
    149145   PDAF_set_iparam(id, value, status_pdaf)
    … …  
    156152* `id`:[[BR]] The index value of a parameter
    157153* `value`:[[BR]] The value of the parameter with index `id`
    158 * `status_pdaf`:[[BR]] Status flag for PDAF. Both routines increment in the input value. The increment is 0 for no error (this allows to check `flag` once after all calls to `PDAF_init`, `PDAF_set_iparam`, and `PDAF_set_rparam`.)
     154* `status_pdaf`:[[BR]] Status flag for PDAF. Both routines increment in the input value. The increment is 0 for no error (this allows to check `flag` once after all calls to `PDAF3_init`, `PDAF_set_iparam`, and `PDAF_set_rparam`.)
    159155
    160156The tutorial code uses these routines for a few settings while the template code include an extended set of calls specific for different DA methods.
    … …  
    167163The PDAF initialization can be tested by compiling the assimilation program (one can out-comment the call to `PDAF3_assim_offline` if one likes to focus on the initialization) and executing it.
    168164
    169 Standard output from PDAF_init looks like the following:
     165Standard output from PDAF3_init looks like the following:
    170166{{{
    171167PDAF    ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    … …  
    173169PDAF    +++       Parallel Data Assimilation Framework         +++
    174170PDAF    +++                                                    +++
    175 PDAF    +++                 Version 3.0beta                    +++
     171PDAF    +++                   Version 3.0                      +++
    176172PDAF    +++                                                    +++
    177173PDAF    +++                   Please cite                      +++