Changes between Version 4 and Version 5 of InitPdafuntilOnePointSeven


Ignore:
Timestamp:
Feb 6, 2012, 9:25:01 AM (7 years ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • InitPdafuntilOnePointSeven

    v4 v5  
    11= Initialization of PDAF and the ensemble by PDAF_init =
    22
    3 '''This version of the documentation is valid for PDAF until and including V1.7. For the most recent version see [InitPdaf here].'''
     3'''This version of the documentation is valid for PDAF until and including V1.7.'''
    44
    55{{{
     
    1919[[PageOutline(2-3,Contents of this page)]]
    2020
    21 == Overview ==
     21The implementation of the initialization has not been changed between version 1.7 and 1.8. Thus, please see the [InitPdaf current documentation] for the details.
    2222
    23 After the adaption of the parallelization, the initialization of PDAF has to be implemented. The PDAF-interval 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/dummymodel_1D` the routine in the file `init_pdaf.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.
    24 
    25 `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 ensemble based and mode based filters. They are in the files `init_seik_pdaf.F90` (for SEIK, LSEIK, ETKF, LETKF), `init_enkf_pdaf.F90` (for EnKF), and `init_seek_pdaf.F90` (for SEEK).
    26 
    27 == Inserting `init_pdaf` ==
    28 
    29 The right place to insert a routine like `init_pdaf` to the model code is in between the initialization part of the model and its time stepping loop. In the routine a number of variables have to be 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]'
    30 
    31 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`
    32 
    33 == Required arguments for `PDAF_init` ==
    34 
    35 The call to `PDAF_init` has the following structure:
    36 {{{
    37 CALL PDAF_init(filtertype, subtype, step_null, &
    38                filter_param_i, length_filter_param_i, &
    39                filter_param_r, length_filter_param_r, &
    40                COMM_model, COMM_filter, COMM_couple, &
    41                task_id, n_modeltasks, filterpe, &
    42                U_init_ens, screen, status_pdaf)
    43 }}}
    44 
    45 The required variables are the following:
    46 
    47  * `filtertype`: An integer defining the type of filter algorithm. Available are
    48   * 0: SEEK
    49   * 1: SEIK
    50   * 2: EnKF
    51   * 3: LSEIK
    52   * 4: ETKF
    53   * 5: LETKF
    54  * `subtype`: An integer defining the sub-type of the filter algorithm (see the example code in `testsuite/src/dummymodel_1D` for choices)
    55  * `step_null`: An integer defining the initial time step. For some cases it can use useful to set `step_null` larger to 0.
    56  * `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). The mandatory variables are in the following order:
    57   * The size of the local state vector for the current process.
    58   * The ensemble size for all ensemble-based filters (or the rank of the state covariance matrix for mode-based filters like SEEK)
    59  * `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.
    60  * `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 example code in `testsuite/src/dummymodel_1D`). The mandatory variable is:
    61   * The value of the forgetting factor (required to be larger than zero)
    62  * `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.
    63  * `COMM_model`: 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`: The communicator variable `COMM_filter` as initialized by `init_parallel_pdaf`.
    65  * `COMM_couple`: The communicator variable `COMM_couple` as initialized by `init_parallel_pdaf`.
    66  * `task_id`: The index of the model tasks  as initialized by `init_parallel_pdaf`.
    67  * `n_modeltasks`: The number of model tasks as defined before the call to `init_parallel_pdaf`.
    68  * `filterpe`: A logical flag showing if a process belongs to `COMM_filter` as initialized by `init_parallel_pdaf`.
    69  * `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]'
    70  * `screen`: An integer defining whether information output is written to the screen (i.e. standard output). The following choices are available:
    71   * 0: quiet mode - no information is displayed.
    72   * 1: Display standard information (recommended)
    73   * 2: as 1 plus display of timing information during the assimilation process
    74   * 3: Display detailed information for debugging
    75  * `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.)
    76 
    77 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.
    78 
    79 PDAF also has a [PdafSimplifiedInterface Simplified Interface] providing the routine `PDAF_init_si`. In the simplified interface, the names of the user-supplied routine `U_init_ens` is predefined 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].
    80 
    81 == Other variables for the assimilation ==
    82 
    83 The routine `init_pdaf` 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:
    84  * `delt_obs`: An integer specifying the number of time steps between two analysis steps
    85  * `rms_obs`: Assumed observation error
    86  * `local_range`: Localization radius in grid points for the observation domain in LSEIK and LETKF
    87  * `srange`: support radius, if a 5th order polynomial is used to weigh the observation errors
    88  * `locweight`: Type of localizing weight
    89 It is useful to define variables like these at this central position. Of course, this definition has to be adapted to the particular model used.
    90 
    91 == User-supplied routine `U_init_ens` (init_ens_pdaf.F90) ==
    92 
    93 The 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.
    94 
    95 The interface is the following:
    96 {{{
    97 SUBROUTINE U_init_ens(filtertype, dim_p, dim_ens, &
    98                            state_p, Uinv, ens_p, flag)
    99 }}}
    100 with
    101  * `filtertype`: The integer defining the type of filter algorithm as given in the call to `PDAF_init`
    102  * `dim_p`: An integer holding the size of the state dimension for the calling process as specified in the call to `PDAF_init`
    103  * `dim_ens`: An integer holding the size of the ensemble (or the rank of the state covariance matrix for SEEK)
    104  * `state_p`: A real array of size (`dim_p`) for the local model state of the calling process (Only relevant for mode-based filters)
    105  * `Uinv`: A real array of size (`dim_ens-1`, `dim_ens-1`) for the inverse of matrix '''U''' from the decomposition of the state error covariance matrix '''P''' = '''VUV^T^''' (Only relevant for mode-based filters like SEEK.)
    106  * `ens_p`: A real array of size (`dim_p`, `dim_ens`) the has to hold upon exit the ensemble of model states.
    107  * `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.
    108 
    109 In 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.
    110 
    111 === Initialization for ensemble-based filters ===
    112 
    113 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.
    114 
    115 The 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.
    116 
    117 
    118 === Initialization for mode-based filters ===
    119 
    120 The only mode-based filter supplied with PDAF is currenly the SEEK filter. For this filter the initialization bases on the decomposition of the state error covariance matrix in the form '''P''' = '''VUV^T^'''. According to this decomposition, the array `ens_p` has to be initialized to hold the modes from matrix '''V''' and `Uinv` holds the inverse of matrix '''U'''. In addition `state_p` has to be initialized with the initial state estimate.  If a model with domain decomposition is used, the part of all modes for the local sub-domain of the MPI process and the corresponding part of the state vector has to be initialized.
     23The only change between V1.7 and 1.8 is the screen output from the initialization routine of PDAF. For V1.7 it is displayed below.
    12124
    12225== Testing the PDAF initialization ==