Changes between Version 2 and Version 3 of InitPdaf

Timestamp:

Aug 23, 2010, 4:06:03 PM (14 years ago)

Author:

lnerger

Comment:

--

InitPdaf

@@ -3 +3 @@
 [[PageOutline(2-3,Contents)]]
 
-After the adaption of the parallelization, the initialization of PDAF has to be implemented. Typically, all initializations of variables required before the call to the initialization routine PDAF_init can be colledted into a single subroutine. The example implementation uses the routine init_pdaf. The right place to insert this routine 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. 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.
+== Overview ==
+
+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. 
+
+== Inserting `init_pdaf` ==
+
+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]'
+
 The 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.
 
-In the call to PDAF_init several variables have to be provided. These are the type index of the filter algorithm, its subtype, and the initial time step. Then follows an integer array and an integer defining the size of the array. This integer array holds parameters that define filter-specific quantities, but also the ensemble size and the size of the state vector (for the current MPI process in case of parallelization with domain decomposition). The next argument is an array of reals followed by its size. This array contains floating point variables for the filter algorithm, like the forgetting factor. Apart from the first two variable of the integer array (state dimension and ensemble size) and the first variable of the real array (forgetting factor) all further variables are optional. For example, if the size parameter for the integer array is set to 2, only the first two variables are parsed by PDAF_init. This also allows to define both arrays to be of minimum size in combination with defining the size accordingly in the call to PDAF_init. In this case the default values of the optional parameters are used.
-After the arrays and their sizes, the communicator variables COMM_model, COMM_filter, and COMM_couple have to be provided by PDAF_init. This is followed by task_id, n_modeltasks, and the flag filterpe, all of which are initialized by init_parallel_pdaf.
-The following argument is the name of the user-provided routine for the initialization of the ensemble states. Defining the name of this routine in the call to PDAF_init allows to use different ensemble initialization routines in a single compiled executable. Internally to PDAF_init the routine is called generically U_ens_init.
-Finally, the integer variables 'screen' and 'status_pdaf' have to be provided. The former variable defines how much output is written to 'standard out' by PDAF. The latter variable is the error flag of PDAF. The initialization was successful if 'status_pdaf' is zero, otherwise a problem occured. For error codes are described in the routine PDAF_init.
+== Required arguments of `PDAF_init` ==
+
+The call to `PDAF_init` has the following structure:
+{{{
+CALL PDAF_init(filtertype, subtype, step_null, &
+               filter_param_i, length_filter_param_i, &
+               filter_param_r, length_filter_param_r, &
+               COMM_model, COMM_filter, COMM_couple, &
+               task_id, n_modeltasks, filterpe, &
+               U_ensemble_init, screen, status_pdaf)
+}}}
+
+The required variables are the following:
+
+ * `filtertype`: An integer defining the type of filter algorithm. Available are
+  * 0: SEEK 
+  * 1: SEIK 
+  * 2: EnKF 
+  * 3: LSEIK 
+  * 4: ETKF 
+  * 5: LETKF 
+ * `subtype`: An integer defining the sub-type of the filter algorithm (see example code for choices)
+ * `step_null`: An integer defining the initial time step. For some cases it can use useful to set `step_null` larger to 0. 
+ * `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:
+  * The local state dimension for the current process.
+  * The ensemble size.
+ * `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.
+ * `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:
+  * The value of the forgetting factor (required to be larger than zero)
+ * `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.
+ * `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
+ * `COMM_filter`: The communicator variable `COMM_filter` as initialized by `init_parallel_pdaf`.
+ * `COMM_couple`: The communicator variable `COMM_couple` as initialized by `init_parallel_pdaf`.
+ * `task_id`: The index of the model tasks  as initialized by `init_parallel_pdaf`.
+ * `n_modeltasks`: The number of model tasks as defined before the call to `init_parallel_pdaf`.
+ * `filterpe`: The flag showing if a process belongs to `COMM_filter` as initialized by `init_parallel_pdaf`.
+ * `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`]'
+ * `screen`: An integer defining whether information output is written to the screen (i.e. standard output). The following choices are available:
+  * 0: quite mode - no information is displayed. 
+  * 1: Display standard information (recommended)
+  * 2: Display detailed information for debugging
+ * `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.) 
+
+== Other variables for the assimilation ==
+
+The routine `init_pdaf` also initializes several variables that are not used to call `PDAF_init`. 
+
+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.
+
+== User-supplied routine `U_ensemble_init` ==
 
 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.