Changes between Version 60 and Version 61 of InitPdaf


Ignore:
Timestamp:
May 21, 2025, 9:31:49 PM (11 days ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • InitPdaf

    v60 v61  
    2121The PDAF release provides example code for the online mode in `tutorial/online_2D_parallelmodel` and `tutorial/online_2D_serialmodel`. We refer to these codes to use it as a basis.
    2222
    23 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`. With this only a single additional subroutine call has to be inserted to the model source code for the initialization. The file `templates/online/init_pdaf.F90` provides a commented template for this routine, which can be used as the basis of the implementation.
     23The actual initialization of PDAF is done in the subroutine `PDAF_init`. This routine sets the internal parameters for the data assimilation, chooses the data assimilation method, allocates the internal ensemble array, and initializes the ensemble. The subroutine `init_pdaf`, which is called from the model code, initializes all variables required for the call to `PDAF_init`. By using `init_pdaf`, only a single additional subroutine call has to be inserted to the model source code for the initialization. The file `templates/online/init_pdaf.F90` provides a commented template for this routine, which can be used as the basis of the implementation.
    2424
    2525`PDAF_init` itself calls a user-supplied call-back routine to initialize the ensemble of model states. In the example and templates, this routine can be found in `init_ens_pdaf.F90`.
    2626
    27 == Inserting `init_pdaf` to the model code ==
     27== Inserting `init_pdaf` into the model code ==
    2828
    2929The right place to insert the routine `init_pdaf` into the model code is in between the initialization part of the model and the time stepping loop. At this point, the regular model initialization is completed, which allows PDAF to initialize the ensemble of model states.
    … …  
    3131== Using `init_pdaf` ==
    3232
    33 In `init_pdaf` 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` but not used in the call to `PDAF_init`. In stead they are define here for later use in the user-supplied call-back routines. For the tutorial example, these variables are described below in the section '[#Othervariablesfortheassimilation Other variables for the assimilation]'.
     33In `init_pdaf` 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` for later use in user-supplied call-back routies. For the tutorial example, these variables are described below in the section '[#Othervariablesfortheassimilation Other variables for the assimilation]'. The template file  `templates/online/init_pdaf.F90` provide some more functionality which can be adapted.
    3434
    35 The 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`
     35The 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`. An alterantive could be to use a configuration file.
    3636
    37 In `init_pdaf` a number of variables have to be defined that are used in the call to `PDAF_init` as described below. (Please note: All names of subroutines that start with `PDAF_` are core routines of PDAF, while subroutines whose name end with `_pdaf` are generally user-supplied interface routines) There are also a few variables that are initialized in `init_pdaf` 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 example case, these variables are described below in '[#Othervariablesfortheassimilation Other variables for the assimilation]'.
     37== Calling `PDAF_init` ==
    3838
    39 The tutorial implementations as well as the template routines allow to parse all variables through a command line parser by calls in `init_pdaf_parse.F90`. This method provides a convenient way to define an experiment and could also be used for other models. The parser module is provided as  `templates/online_omi/parser_mpi.F90` and also used in the tutorials. Alternatively, one could implement an initialization of the variables with Fortran namelists or could just rely on hard-coded numbers in the source code. Generally we recommend to use a configuration strategy consistent with the model code used.
     39In 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`.
    4040
    41 == Required arguments for `PDAF_init` ==
    42 
    43 In `init_pdaf` the variables for the call to `PDAF_init` are set. The call to `PDAF_init` has the following structure:
     41The call to `PDAF_init` has the following structure:
    4442{{{
    4543CALL PDAF_init(filtertype, subtype, step_null, &
    … …  
    4846               COMM_model, COMM_filter, COMM_couple, &
    4947               task_id, n_modeltasks, filterpe, &
    50                U_init_ens, screen, status_pdaf)
     48               init_ens_offline, screen, status_pdaf)
    5149}}}
    5250
    53 The required variables are the following:
     51The required arguments are described below. In the list, we mark those variables bold, which one might like to change, like the type of the DA method. The other variables are required, but usually not changed by the user.
    5452
    55  * `filtertype`: An integer defining the type of filter algorithm. Available are
    56   * 0: SEEK
    57   * 1: SEIK
    58   * 2: EnKF
    59   * 3: LSEIK
    60   * 4: ETKF
    61   * 5: LETKF
    62   * 6: ESTKF
    63   * 7: LESTKF
    64   * 8: local EnKF
    65   * 9: NETF
    66   * 10: LNETF
    67   * 11: LKNETF (new in PDAF V2.1)
    68   * 12: PF
    69   * 13: ENSRF/EAKF
    70   * 100: GENOBS (generate synthetic observations, was filtertype=11 before PDAF V2.0)
    71   * 200: 3D-Var methods (new in PDAF V2.0)
    72  * `subtype`: An integer defining the sub-type of the filter algorithm (see the example code in `templates/online_omi/init_pdaf.F90` for choices).
    73   * If `PDAF_init` is called with `subtype=-1` the available options are shown for the selected filter algorithm.
     53 * **filtertype**:[[BR]] An integer defining the type of the DA method.  (See the [#Noteonavailableoptions Note on Available Options])
     54 * **subtype**:[[BR]] An integer defining the sub-type of the filter algorithm. (See the [#Noteonavailableoptions Note on Available Options])
    7455 * `step_null`: An integer defining the initial time step. For some cases it can use useful to set `step_null` larger to 0.
    75  * `filter_param_i`: Integer array collecting several variables for PDAF. The first two variables are mandatory and equal for all filters. Further variables are optional (see example code or use `subtype=-1` to display available options.). The mandatory variables are in the following order:
    76   * The size of the local state vector for the current process.
    77   * The ensemble size for all ensemble-based filters
    78  * `length_filter_param_i`: An integer defining the length of the array `filter_param_i`. The entries in the array are parsed up to this index.
    79  * `filter_param_r`: Array of reals collecting floating point variables for PDAF. The first variable is mandatory and equal for all filters.  Further variables are optional (see `templates/online_omi/init_pdaf.F90` or use `subtype=-1` to display available options.). The mandatory variable is:
    80   * The value of the forgetting factor controlling covariance inflation (required to be larger than zero; common are values between 0.9 and 1.0. For 1.0 the ensemble is not inflated.)
    81  * `length_filter_param_r`: An Integer defining the length of the array `filter_param_r`. The entries in the array are parsed up to this index.
    82  * `COMM_model`: The communicator variable `COMM_model` as initialized by `init_parallel_pdaf`. (Usually stored in the module `mod_assimilation`)
    83  * `COMM_filter`: The communicator variable `COMM_filter` as initialized by `init_parallel_pdaf`. (Usually stored in the module `mod_assimilation`)
    84  * `COMM_couple`: The communicator variable `COMM_couple` as initialized by `init_parallel_pdaf`. (Usually stored in the module `mod_assimilation`)
    85  * `task_id`: The model task index as initialized by `init_parallel_pdaf`. (Usually stored in the module `mod_assimilation`)
    86  * `n_modeltasks`: The number of model tasks as defined before the call to `init_parallel_pdaf`. (Usually stored in the module `mod_assimilation`)
    87  * `filterpe`: A logical flag showing whether a process belongs to `COMM_filter` as initialized by `init_parallel_pdaf`. (Usually stored in the module `mod_assimilation`)
    88  * `U_init_ens`: The name of the user-supplied routine that is called by `PDAF_init` to initialize the ensemble of model states. (See '[#User-suppliedroutineU_init_ensinit_ens_pdaf.F90 User-supplied routine U_init_ens]')
    89  * `screen`: An integer defining whether information output is written to the screen (i.e. standard output). The following choices are available:
    90   * 0: quiet mode - no information is displayed.
     56 * **filter_param_i**:[[BR]] Integer array collecting options for PDAF. The first two variables are mandatory and equal for all filters. Further variables are optional (See the [#Noteonavailableoptions Note on Available Options]). The mandatory variables are in the following order:
     57  1. The size of the local state vector for the current process.
     58  1. The ensemble size for all ensemble-based filters
     59 * **length_filter_param_i**:[[BR]] An integer defining the length of the array `filter_param_i`. The entries in the array are parsed up to this index.
     60 * **filter_param_r**:[[BR]] Array collecting real-valued options for PDAF. The first value is mandatory and equal for all filters.  Further variables are optional (See the [#Noteonavailableoptions Note on Available Options]). The mandatory variable is:
     61  1. The value of the forgetting factor controlling inflation (required to be larger than zero)
     62 * **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.
     63 * `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
     64 * `COMM_filter`:[[BR]] The communicator variable `COMM_filter` as initialized by `init_parallel_pdaf`.
     65 * `COMM_couple`:[[BR]] The communicator variable `COMM_couple` as initialized by `init_parallel_pdaf`.
     66 * `task_id`:[[BR]] The index of the model tasks  as initialized by `init_parallel_pdaf`. Always 1 for the offline mode
     67 * `n_modeltasks`:[[BR]] The number of model tasks as defined before the call to `init_parallel_pdaf`.
     68 * `filterpe`:[[BR]] The flag showing if a process belongs to `COMM_filter` as initialized by `init_parallel_pdaf`.
     69 * **init_ens_pdaf**:[[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_pdaf User-supplied routine init_ens_pdaf]'
     70 * `screen`:[[BR]] An integer defining whether information output is written to the screen (i.e. standard output). The following choices are available:
     71  * 0: quite mode - no information is displayed.
    9172  * 1: Display standard information (recommended)
    9273  * 2: as 1 plus display of timing information during the assimilation process
    93  * `status_pdaf`: 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`.)
     74 * `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.)
    9475
    95 An overview of available options for each filter an be found on the [wiki:AvailableOptionsforInitPDAF overview page on options].
     76PDAF 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.
    9677
    97 '''Notes:'''
    98  * It is recommended that the value of `status_pdaf` is checked in the program after PDAF_init is executed. Only if its value is 0 the initialization was successful.
    99  * PDAF also has a [PdafSimplifiedInterface Simplified Interface] providing the routine `PDAF_init_si`. In the simplified interface, the name of the user-supplied routine `U_init_ens` is predefined to `init_ens_pdaf` such that it does not appear in the call to `PDAF_init_si`.  More information on the pre-defined names is provided in the [PdafSimplifiedInterface documentation of PDAF's simplified interface].
     78We 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.
     79
     80=== Note on available options ===
     81
     82 A **list of available values of `filtertype`** as well as an **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].
     83
     84 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, but this might not be up-to-date in all cases.
     85
     86
    10087
    10188== Other variables for the assimilation ==