Changes between Version 37 and Version 38 of InitPdaf


Ignore:
Timestamp:
Apr 28, 2014, 9:39:43 AM (11 years ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • InitPdaf

    v37 v38  
    1919== Overview ==
    2020
    21 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.
     21After the adaption of the parallelization, the initialization of PDAF has to be implemented. It is performed by the routine `PDAF_init`. This subroutine has several arguments. 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 additional subroutine call has to be inserted to the model source code. In the example in `testsuite/src/dummymodel_1D` the routine in the file `init_pdaf.F90` collects all initializations for PDAF. Likewise the tutorial implementations use a routine `init_pdaf.F90`. The file `init_pdaf.F90` in `templates/` provides a commented template for this routine, which can be used as the basis of the implementation.
    2222
    23 `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).
     23`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).
    2424
    2525== Inserting `init_pdaf` ==
    2626
    27 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]'
     27The 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. I.e. the regular model initialization should be completed, which allows PDAF to initialize the ensemble of model states.
    2828
    29 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`
     29In 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`]' 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 in '[#Othervariablesfortheassimilation Other variables for the assimilation]'
     30
     31The example and tutorial implementations, as well as the template routines allow to parse all variables through a command line parser by call 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/parser_mpi.F90`. Alternatively, one could implement an initialization of the variables with Fortran namelists or could just rely on hard-coded numbers in the source code.
    3032
    3133== Required arguments for `PDAF_init` ==
    3234
    33 The call to `PDAF_init` has the following structure:
     35In `init_pdaf` the variables for the call to `PDAF_init` are set. The call to `PDAF_init` has the following structure:
    3436{{{
    3537CALL PDAF_init(filtertype, subtype, step_null, &
    … …  
    5961 * `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.
    6062 * `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` or use `subtype=-1` to display available options.). The mandatory variable is:
    61   * The value of the forgetting factor (required to be larger than zero)
     63  * 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.)
    6264 * `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`.
     65 * `COMM_model`: The communicator variable `COMM_model` as initialized by `init_parallel_pdaf`. (Usually stored in the module `mod_assimilation`)
     66 * `COMM_filter`: The communicator variable `COMM_filter` as initialized by `init_parallel_pdaf`. (Usually stored in the module `mod_assimilation`)
     67 * `COMM_couple`: The communicator variable `COMM_couple` as initialized by `init_parallel_pdaf`. (Usually stored in the module `mod_assimilation`)
     68 * `task_id`: The index of the model tasks  as initialized by `init_parallel_pdaf`. (Usually stored in the module `mod_assimilation`)
     69 * `n_modeltasks`: The number of model tasks as defined before the call to `init_parallel_pdaf`. (Usually stored in the module `mod_assimilation`)
     70 * `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`)
    6971 * `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]'
    7072 * `screen`: An integer defining whether information output is written to the screen (i.e. standard output). The following choices are available:
    … …  
    7375  * 2: as 1 plus display of timing information during the assimilation process
    7476  * 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.)
     77 * `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`.)
    7678
    7779An overview of available options for each filter an be found on the [wiki:AvailableOptionsforInitPDAF overview page on options].
    … …  
    7981It 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.
    8082
    81 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].
     83PDAF 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].
    8284
    8385== Other variables for the assimilation ==
    8486
    85 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:
     87The 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 the Fortran module `mod_assimilation`. These variables are for example:
    8688 * `delt_obs`: An integer specifying the number of time steps between two analysis steps
    8789 * `rms_obs`: Assumed observation error
    … …  
    8991 * `srange`: support radius, if a 5th order polynomial is used to weigh the observation errors
    9092 * `locweight`: Type of localizing weight
    91 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.
     93It is useful to define variables like these at this central position. Of course, their definition has to be adapted to the particular model used.
    9294
    9395== User-supplied routine `U_init_ens` (init_ens_pdaf.F90) ==
    … …  
    109111 * `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.
    110112
    111 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.
     113In the initialization routine `U_init_ens_pdaf` one has to distinguish between ensemble-based and mode-based filters as will be described below. The only mode based filter supplied with PDAF is SEEK, while all other methods are ensemble-based.
     114
     115=== Defining the state vector ===
     116
     117The ensemble initialization routine is the first location at which the user has to fill a state vector (or array of state vectors). A state vector is the collection of all models fields that are handled in the analysis step of the assimilation procedure into a single vector. Usually one concatenates the different model fields as complete fields. Thus, the vector could contain a full 3-dimensional temperature field, followed by the salinity field (in case of an ocean model), and then followed by the 3 fields of the velocity components.
     118
     119The logical definition of the state vector will also be utilized in several other user-supplied routines. E.g. in routines that fill model fields from a state vector or in the routine providing the observation operator.
     120
    112121
    113122=== Initialization for ensemble-based filters ===
    114123
    115 Generally, 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.
     124Generally, 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 parallel model with domain decomposition is used, the full ensemble for the local sub-domain of the MPI process has to be initialized.
    116125
    117 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.
     126The 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 used for EnKF.
    118127
    119128
    120129=== Initialization for mode-based filters ===
    121130
    122 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.
     131The 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 parallel 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. ```Uinv``` will be identical for all MPI processes.
    123132
    124133== Testing the PDAF initialization ==
    … …  
    128137'''Remark:''' For the compilation with a real MPI library, one has to ensure that the header file (`mpif.h`) of the MPI-library is used for both the model and PDAF. (Thus in the include file for make in `make.arch`, one might have set `MPI_INC` to the directory holding the header file.) The include directory `dummympi` specified in some of the include files for compiling a serial program, will not be compatible with all MPI implementations.
    129138
    130 At this stage it will not be meaningful to perform an actual integration. However, one can test if the initialization in PDAF_init is successful and if the ensemble array is correctly initialized.
     139At this stage it will not be meaningful to perform an actual model time stepping. However, one can test whether the initialization in PDAF_init is successful and whether the ensemble array is correctly initialized.
    131140
    132141Standard output from PDAF_init should look like the following: