Changes between Version 3 and Version 4 of InitPdaf


Ignore:
Timestamp:
Aug 23, 2010, 4:58:56 PM (14 years ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • InitPdaf

    v3 v4  
    55== Overview ==
    66
    7 After the adaption of the parallelization, the initialization of PDAF has to be implemented. PDAF_internally, 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/dummymodel_1D the routine in the file init_pdaf.F90 shows this strategy.
     7After the adaption of the parallelization, the initialization of PDAF has to be implemented. PDAF_internally, 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/dummymodel_1D` the routine in the file `init_pdaf.F90` shows this strategy.
    88
    99== Inserting `init_pdaf` ==
    1010
    11 The right place to insert a routine `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 '[#RequiredvariablesforPDAF_init Required variables 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]'
     11The 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]'
    1212
    1313The example implementation allows 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.
    1414
    15 == Required arguments of `PDAF_init` ==
     15== Required arguments for `PDAF_init` ==
    1616
    1717The call to `PDAF_init` has the following structure:
    … …  
    3737 * `step_null`: An integer defining the initial time step. For some cases it can use useful to set `step_null` larger to 0.
    3838 * `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:
    39   * The local state dimension for the current process.
    40   * The ensemble size.
     39  * The size of the local state vector for the current process.
     40  * The ensemble size for all ensemble-based filters (or the rank of the state covariance matrix for mode-based filters like SEEK)
    4141 * `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.
    4242 * `filter_param_r`: Array of reals collecting flowting point variables for PDAF. The first variable is mandatory and equal for all filters.  Further variables are optional (see example code). The mandatory variable is:
    … …  
    5858== Other variables for the assimilation ==
    5959
    60 The routine `init_pdaf` also initializes several variables that are not used to call `PDAF_init`.
    61 
    62 The are, for example the size of the ensemble and the type of filter algorithm. The example implementation explains the full set of variables. The example also initializes a few variables that are not handed over to PDAF_init, like delt_obs. This variable is the number of time steps between sucessive analysis steps. It is meaningful to define it at this central position. Of course, this definition has to be adapted to the particluar model used.
     60The 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:
     61 * `delt_obs`: An integer specifying the number of time steps between two analysis steps
     62 * `rms_obs`: Assumed observation error
     63 * `local_range`: Localization radius in grid points for the observation domain in LSEIK and LETKF
     64 * `locweight`: Type of localizing weight
     65It is useful to define variables like this at this central position. Of course, this definition has to be adapted to the particluar model used.
    6366
    6467== User-supplied routine `U_ensemble_init` ==
    6568
    66 The user-supplied routine for the ensemble initialization is called through a defined interface as is visible in the ensemble implementation. 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). For the ensemble based filter (that is, not for the SEEK filter), the routine has to initialize the ensemble of model states. If domain decomposition is used, the full ensemble for the local sub-domain of the MPI process has to be initialized. (In case of the SEEK filter, the initial state estimate as well as decomposed covariance matrix in form of the the array of EOF modes and the inverse of matrix U have to be initialized.) The ensemble initialization routine is only called if the internal error flag of PDAF_init is zero. The flag is provided to the ensemble initialization routine. The user can set its value depending on the success of the ensemble initialization. Preferably, values above 102 should be used for failures to avoid conflict with the error codes defined within PDAF_init.
     69The 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.
    6770
     71The interface is the following:
     72{{{
     73SUBROUTINE U_ensemble_init(filtertype, dim_p, dim_ens, &
     74                           state_p, Uinv, ens_p, flag)
     75}}}
     76with
     77 * `filtertype`: The integer defining the type of filter algorithm as given in the call to `PDAF_init`
     78 * `dim_p`: An integer holding the size of the state dimension for the calling process as specified in the call to `PDAF_init`
     79 * `dim_ens`: An integer holding the size of the ensemble (or the rank of the state covariance matrix for SEEK)
     80 * `state_p`: A real array of size (`dim_p`) for the local model state of the calling process (Only relevant for mode-based filters)
     81 * `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.)
     82 * `ens_p`: A real array of size (`dim_p`, `dim_ens`) the has to hold upon exit the ensemble of model states.
     83 * `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.
     84
     85In 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.
     86
     87=== Initialization for ensemble-based filters ===
     88
     89Generally, 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.
     90
     91The 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.
     92
     93
     94=== Initialization for mode-based filters ===
     95
     96The 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.
     97