Offline Mode: Initializing PDAF

Overview

The PDAF release provides example code for the offline mode in tutorial/offline_2D_parallel. We refer to this code to use it as a basis.

The routine PDAF_init is called to initialize PDAF. This call sets parameters for the data assimilation, chooses the data assimilation method and initializes the ensemble. In the tutorial and template codes we collect the initialization of all variables required for the call to PDAF_init into the single subroutine init_pdaf_offline, which yields a clean code. The file templates/offline/init_pdaf_offline.F90 provides a commented template for this routine, which can be used as the basis of the implementation.

PDAF_init itself calls a user-supplied call-back routine to initialize the ensemble of model states. In the example, this is the routine in the file init_ens_offline.F90.

Using init_pdaf_offline

In the offline mode, the routine init_pdaf_offline is executed after the initialization of the parallelization.

In init_pdaf_offline a number of variables are defined that are used in the call to PDAF_init as described below. There are also a few variables that are initialized in init_pdaf_offline 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 tutorial example, these variables are described below in the section 'Other variables for the assimilation'.

The example implementation and the template code allow to specify all options at run time using a command line parser. These options are specified as the combination -VARIABLE VALUE. This method provides a convenient way to define an experiment and could also be used for other models. The parser module is provided by the file tutorial/offline_2D_serial/parser_mpi.F90

Arguments of PDAF_init

In the tutorial codes and the template, the call to PDAF_init is fully implemented. Here, we provide an overview of the arguments that are set in the call to 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, &
               init_ens_offline, screen, status_pdaf)

The required arguments are described below. In the list, we mark those variables bold, which one might like to change, like the type of the DA method. The other variables are required, but usually not changed by the user.

• filtertype:
  An integer defining the type of the DA method. Available values are listed on the page on available options and can also be displayed running the assimilation program with the option -subtype -1.
• subtype:
  An integer defining the sub-type of the filter algorithm. Available values are listed on the page on available options and can also be displayed runnign the assimialtion program with the option -subtype -1.
• step_null:
  Always 0 for the offline mode.
• filter_param_i:
  Integer array collecting options 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:
  1. The size of the local state vector for the current process.
  2. The ensemble size for all ensemble-based filters
• 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 collecting real-valued options for PDAF. The first value is mandatory and equal for all filters. Further variables are optional (see example code). The mandatory variable is:
  1. The value of the forgetting factor controlling inflation (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. Always 1 for the offline mode
• 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.
• init_ens_offline:
  The name of the user-supplied routine that is called by PDAF_init to initialize the ensemble of model states. (See below: 'User-supplied routine init_ens_offline'
• 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: as 1 plus display of timing information during the assimilation process
• 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.)

PDAF uses two arrays filter_param_i and filter_param_r to respectively specify integer and real-valued options for PDAF. As described above, 2 integer values (state vector size, ensemble size) and 1 real option (forgetting factor for inflation) are mandatory. Additional options can be set by specifying a larger array and setting the corresponding size value (length_filter_param_i, length_filter_param_r). However, with PDAF V3.0 it can be more convenient to use the subroutines PDAF_set_iparam and PDAF_set_rparam`, which are explained further below.

An overview of available integer and real-valued options for each DA method can be found on the page Available options for the different DA methods. The available options for a specific DA method can also be displayed by running the assimilation program for the selected DA method setting subtype = -1. (In the tutorial and template codes one can set -subtype -1 on the command line). Generally, available options and valid settings are also listed in mod_assimilation.F90 of the tutorials and template codes.

We recommended to check the value of status_pdaf in the program after PDAF_init (and potentially PDAF_set_iparam and PDAF_set_rparam`) are executed. Only if its value is 0, the initialization was successful.

Other variables for the assimilation

The routine init_pdaf_offline 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:

• cradius: Localization cut-off radius (here in grid points) for the local observation domain
• sradius: support radius, if the observation errors are weighted with distance (for locweight>0)
• locweight: Type of localizing weight

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.

Apart from the generic variables for localization, we also specify variables that are specific for each obseration type, for example

• assim_A: Flag whether to assimialtion observations of type A
• rms_obs_A: Assumed observation error standard deviation of observation type A

User-supplied routine init_ens_offline

The user-supplied routine that we named init_ens_ofline here, is the call-back routine that 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.) init_ens_pdaf is only called by PDAF_init if no error occurred before; thus the status flag is zero.

The interface can be looked up in the template and tutorial codes. It is the following:

SUBROUTINE init_ens_offline(filtertype, dim_p, dim_ens, &
                           state_p, Uinv, ens_p, flag)

with

• filtertype:
  The integer defining the type of filter algorithm as given in the call to PDAF_init
• dim_p:
  An integer holding the size of the state dimension for the calling process as specified in the call to PDAF_init
• dim_ens:
  An integer holding the size of the ensemble
• state_p:
  A real array of size (dim_p) for the local model state of the calling process (can be used freely for ensemble-based methods)
• 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 (Not relevant for ensemble-based methods)
• ens_p:
  A real array of size (dim_p, dim_ens), which has to be filled with the ensemble of model states.
• 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.

Initialization for ensemble-based filters

Most data assimilation methods are based on ensembles (an exception is only the parameterized 3D-Var). For the ensemble-based methods 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.

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 the EnKF for which Uinv is allocated only with size (1,1), because Uinv is not using for EnKF.

For the offline mode, one will usually read the ensemble states from output files of the model used to perform the ensemble integrations separately (i.e. 'offline'). Thus, one has to implement a reading routine for the model files.

Setting additional options

In PDAF V3.0 we added the possibility to set options for PDAF after the call to PDAF_init. For these there are the subroutines

   PDAF_set_iparam(id, value, status_pdaf)

to set interger parameters and

   PDAF_set_rparam(id, value, status_pdaf)

to set REAL (floating point) parameters. The arguments are

• id:
  The index value of a parameter
• value:
  The value of the parameter with index id
• status_pdaf:
  Status flag for PDAF. Both routines increment in the input value. The increment is 0 for no error (this allows to check flag once after all calls to PDAF_init, PDAF_set_iparam, and PDAF_set_rparam.)

The tutorial code uses these routines for a few settings while the template code include an extended set of calls specific for different DA methods.

An overview of available integer and real-valued options for each DA method can be found on the pageAvailable options for the different DA methods. The available options for a specific DA method can also be displayed by running the assimilation program for the selected DA method setting subtype = -1. (In the tutorial and template codes one can set -subtype -1 on the command line).

Testing the PDAF initialization

The PDAF initialization can be tested by compiling the assimilation program (one can out-comment the call to PDAF3_assim_offline if one likes to focus on the initialization) and executing it.

Standard output from PDAF_init looks like the following:

PDAF    ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
PDAF    +++                       PDAF                         +++
PDAF    +++       Parallel Data Assimilation Framework         +++
PDAF    +++                                                    +++
PDAF    +++                 Version 3.0beta                    +++
PDAF    +++                                                    +++
PDAF    +++                   Please cite                      +++
PDAF    +++ L. Nerger and W. Hiller, Computers and Geosciences +++
PDAF    +++ 2013, 55, 110-118, doi:10.1016/j.cageo.2012.03.026 +++
PDAF    +++   when publishing work resulting from using PDAF   +++
PDAF    +++                                                    +++
PDAF    +++          PDAF itself can also be cited as          +++
PDAF    +++  L. Nerger. Parallel Data Assimilation Framework   +++
PDAF    +++  (PDAF). Zenodo. 2024. doi:10.5281/zenodo.7861812  +++
PDAF    ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


PDAF: Initialize filter

PDAF    ++++++++++++++++++++++++++++++++++++++++++++++++++++++
PDAF    +++ Error Subspace Transform Kalman Filter (ESTKF) +++
PDAF    +++                                                +++
PDAF    +++  Nerger et al., Mon. Wea. Rev. 140 (2012) 2335 +++
PDAF    +++           doi:10.1175/MWR-D-11-00102.1         +++
PDAF    ++++++++++++++++++++++++++++++++++++++++++++++++++++++

PDAF: Initialize Parallelization
PDAF     Parallelization - Filter on model PEs:
PDAF                 Total number of PEs:      1
PDAF      Number of parallel model tasks:      1
PDAF                      PEs for Filter:      1
PDAF     # PEs per ensemble task and local ensemble sizes: 
PDAF     Task     1
PDAF     #PEs     1
PDAF        N     9

PDAF: Call ensemble initialization

         Initialize state ensemble
         --- read ensemble from files
         --- Ensemble size:      9

PDAF: Initialization completed

The correctness of the ensemble initialization in init_ens_offline should be checked by the user.