Changes between Version 2 and Version 3 of OfflineInitPdaf


Ignore:
Timestamp:
Apr 12, 2012, 11:44:02 AM (12 years ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • OfflineInitPdaf

    v2 v3  
    1818== Overview ==
    1919
    20 After the initialization of the parallelization for the assimilation program, the initialization of PDAF has to be implemented. Internally to PDAF, the initialization is performed by the routine `PDAF_init`. Typically, the initializations of all variables required for the call to `PDAF_init` can be collected into a single subroutine. This implementation strategy is useful, as only a single addition subroutine call has to be added to the model source code. In the example in `testsuite/src/offline_1D` the routine in the file `init_pdaf_offline_D.F90` shows this strategy. The file `init_pdaf.F90` in `templates/` provides a commented template for this routine, which can be used as the basis of the implementation.
     20After the initialization of the parallelization for the assimilation program, the initialization of PDAF has to be implemented. Internally to PDAF, the initialization is performed by the routine `PDAF_init`. Typically, the initialization of all variables required for the call to `PDAF_init` can be collected into a single subroutine. This implementation strategy is useful, as only a single additional subroutine call has to be added to the model source code. In the example in `testsuite/src/offline_1D` the routine in the file `init_pdaf_offline_D.F90` shows this strategy. The file `init_pdaf.F90` in `templates/` provides a commented template for this routine, which can be used as the basis of the implementation.
    2121
    22 `PDAF_init` itself calls a user-supplied routine to initialize the ensemble of model states through its interface. In the example there are separate routines for the different filters. They are in the files `init_seik_offline_D.F90` (for SEIK, LSEIK, ETKF, LETKF), `init_enkf_offline_D.F90` (for EnKF), and `init_seek_offline_D.F90` (for SEEK).
     22`PDAF_init` itself calls a user-supplied routine to initialize the ensemble of model states through its interface. In the example there are separate routines for the different filters. They are in the files `init_seik_offline_D.F90` (for SEIK, LSEIK, ETKF, LETKF, ESTKF, LESTKF), `init_enkf_offline_D.F90` (for EnKF), and `init_seek_offline_D.F90` (for SEEK).
    2323
    2424== Using `init_pdaf` ==
     
    2626In the offline mode, the routine `init_pdaf` is executed after the initialization of the parallelization. (Note: In the main program of example implementation (`main/main_offine.F90`) we added a call to a routine `initialize` in between for clarity of the implementation. As no real model initialization is conducted, this routine simply initializes the size of the model state. This initialization could also be performed in `init_pdaf`.)
    2727
    28 In the routine `init_pdaf` a number of variables are defined that are used in the call to `PDAF_init` as described in '[#RequiredargumentsforPDAF_init Required arguments for `PDAF_init`]'. (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 in '[#Othervariablesfortheassimilation Other variables for the assimilation]'
     28In the routine `init_pdaf` a number of variables are defined that are used in the call to `PDAF_init` as described below in '[#RequiredargumentsforPDAF_init Required arguments for `PDAF_init`]'. (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 call-back 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 the section '[#Othervariablesfortheassimilation Other variables for the assimilation]'
    2929
    30 The example implementation and the template version allow to parse all variables through a command line parser. 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/parser_mpi.F90`
     30The example implementation and the template version allow to parse all variables through a command line parser. This method provides a convenient way to define an experiment and could also be used for other models. The parser module is provided as `testsuite/src/main/parser_mpi.F90`
    3131
    3232== Required arguments for `PDAF_init` ==
     
    3939               COMM_model, COMM_filter, COMM_couple, &
    4040               task_id, n_modeltasks, filterpe, &
    41                U_ensemble_init, screen, status_pdaf)
     41               U_init_ens, screen, status_pdaf)
    4242}}}
    4343
     
    5151  * 4: ETKF
    5252  * 5: LETKF
     53  * 6: ESTKF
     54  * 7: LESTKF
    5355 * `subtype`: An integer defining the sub-type of the filter algorithm (always 5 for the offline mode)
    5456 * `step_null`: Always 0 for the offline mode.
     
    6668 * `n_modeltasks`: The number of model tasks as defined before the call to `init_parallel_pdaf`.
    6769 * `filterpe`: The flag showing if a process belongs to `COMM_filter` as initialized by `init_parallel_pdaf`.
    68  * `U_ensemble_init`: The name of the user-supplied routine that is called by `PDAF_init` to initialize the ensemble of model states. (See '[#User-suppliedroutineU_ensemble_init User-supplied routine U_ensemble_init]'
     70 * `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_ens User-supplied routine U_init_ens]'
    6971 * `screen`: An integer defining whether information output is written to the screen (i.e. standard output). The following choices are available:
    7072  * 0: quite mode - no information is displayed.
     
    8789It is useful to define variables lke these at this central position. Of course, this definition has to be adapted to the particular model used.
    8890
    89 == User-supplied routine `U_ensemble_init` ==
     91== User-supplied routine `U_init_ens` ==
    9092
    91 The user-supplied routine the we named `U_ensemble_init` here, is called by PDAF through the defined interface described below. The routine is called by all MPI processes that compute the filter analysis step (i.e. those for which 'filterpe' is set to true. In the standard configuration of init_parallel_pdaf these are all processes of the first model task, i.e. task_id=1.) `U_ensemble_init` is only called by `PDAF_init` if no error occurred before; thus the status flag is zero.
     93The user-supplied routine the we named `U_init_ens` here, is called by PDAF through the defined interface described below. The routine is called by all MPI processes that compute the filter analysis step (i.e. those for which 'filterpe' is set to true. In the standard configuration of `init_parallel_pdaf` these are all processes of the first model task, i.e. task_id=1.) `U_init_ens_pdaf` is only called by `PDAF_init` if no error occurred before; thus the status flag is zero.
    9294
    9395The interface is the following:
    9496{{{
    95 SUBROUTINE U_ensemble_init(filtertype, dim_p, dim_ens, &
     97SUBROUTINE U_init_ens(filtertype, dim_p, dim_ens, &
    9698                           state_p, Uinv, ens_p, flag)
    9799}}}
     
    105107 * `flag`: 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.
    106108
    107 In the initialization routine `U_ensemble_init` one has to distinguish between ensemble-based and mode-based filters. The only mode based filter supplied with PDAF is SEEK, while all other methods are ensemble-based.
     109In the initialization routine `U_init_ens_pdaf` one has to distinguish between ensemble-based and mode-based filters. The only mode based filter supplied with PDAF is SEEK, while all other methods are ensemble-based.
    108110
    109111=== Initialization for ensemble-based filters ===
    110112
    111 Generally, the filters SEIK, LSEIK, EnKF, ETKF, and LETKF are ensemble-based filters. For these filters only the array `ens_p` needs to be initialized by the ensemble of model states. If a model with domain decomposition is used, the full ensemble for the local sub-domain of the MPI process has to be initialized.
     113Generally, the filters SEIK, LSEIK, EnKF, ETKF, LETKF, ESTKF, and LESTKF are ensemble-based filters. For these filters only the array `ens_p` needs to be initialized by the ensemble of model states. If a model with domain decomposition is used, the full ensemble for the local sub-domain of the MPI process has to be initialized.
    112114
    113115The arrays `state_p` and `Uinv` are allocated to their correct sizes because they are used during the assimilation cycles. They are not yet initialized and it is allowed to use these arrays in the initialization. An exception from this is EnKF for which `Uinv` is allocated only with size (`1`,`1`), because `Uinv` is not using for EnKF.
     
    127129Standard output from PDAF_init should look like the following:
    128130{{{
    129   PDAF: Initialize SEIK Filter
     131        ++++++++++++++++++++++++++++++++++++++++++++++++++++++
     132        +++                      PDAF                      +++
     133        +++      Parallel Data Assimilation Framework      +++
     134        +++                                                +++
     135        +++                  Version 1.8                   +++
     136        ++++++++++++++++++++++++++++++++++++++++++++++++++++++
    130137
    131          SEIK configuration
    132                filter sub-type = 0
    133                  --> Standard SEIK
    134                  --> Transform ensemble with deterministic Omega
     138
     139  PDAF: Initialize filter
     140
     141        ++++++++++++++++++++++++++++++++++++++++++++++++++++++
     142        +++                  SEEK Filter                   +++
     143        +++                                                +++
     144        +++    Pham et al., J. Mar. Syst. 16 (1998) 323    +++
     145        +++          This implementation follows           +++
     146        +++      Nerger et al., Tellus 57A (2005) 715      +++
     147        ++++++++++++++++++++++++++++++++++++++++++++++++++++++
     148
     149         SEEK configuration
     150               filter sub-type = 5
     151                 --> offline mode
    135152                 --> Use fixed forgetting factor: 1.00
     153                 --> number of EOFs:   49
     154          Perform re-diagonalization
     155
     156  PDAF: Initialize Parallelization
    136157
    137158         Parallelization - Filter on model PEs:
    138                       Total number of PEs:   4
    139           Number of parallel model tasks:   1
    140                            PEs for Filter:   4
     159                      Total number of PEs:    1
     160           Number of parallel model tasks:    1
     161                           PEs for Filter:    1
    141162     # PEs per ensemble task and local ensemble sizes:
    142163           Task   1
    143            #PEs   4
    144               N 300
     164           #PEs   1
     165              N  49
     166          Evolve central state on task:   1
    145167}}}
    146168
    147 The correctness of the ensemble initialization in `U_ensemble_init` should be checked by the user.
     169The correctness of the ensemble initialization in `U_init_ens` should be checked by the user.