U_init_dim_l

The page document the user-supplied call-back routine U_init_dim_l.

The routine U_init_dim_l is a call-back routine that has to be provided by the user. In the simplified interface the predefined name of the routine is init_dim_l_pdaf, but in the full interface, the user can choose the name of the routine. The routine is used with all filter algorithms using domain-localization (LSEIK, LETKF, LESTKF) and is independent of the particular algorithm. The routine is called during the loop over the local analysis domains in the analysis step. It has to provide the dimension of the sub-state vector for the specified local analysis domain.

For PDAF it has to provide in dim_l the dimension of the state vector for the local analysis domain with index domain_p.

In addition, for PDAFlocal the routine has to provide the index array containing the indices of the elements of the local state vector in the global (or domain-decomposed) state vector to PDAFlocal by calling PDAFlocal_set_indices. (in the template files, this array is called id_lstate_in_pstate)

The interface for this routine is:

SUBROUTINE U_init_dim_l(step, domain_p, dim_l)

  INTEGER, INTENT(in)  :: step        ! Current time step
  INTEGER, INTENT(in)  :: domain_p    ! Current local analysis domain
  INTEGER, INTENT(out) :: dim_l       ! Local state dimension

Hints:

• For sharing through the module mod_assimilation, we further initialize an array coords_l containing the coordinates that describe the local domain.
  • These coordinates have to describe one location in space that is used in the OMI observation modules to compute the distance from observations.
  • The coordinates in coords_l have the same units as those used for the observations
  • For geographic distance computations, the unit of the coordinates needs to be radian, thus (0, 2*pi) or (-pi,pi) for longitude and (-pi/2, pi/2) for latitude.
• Any form of local domain is possible as long as it can be describe as a single location.
  • If the local domain is a single grid point, dim_l will be the number of model variables at this grid point.
  • The local analysis domain can also be a single vertical column of the model grid if observations are only horizontally distributed (a common situation with satellite data in the ocean).
    • In this case, dim_l will be the number of vertical grid points at this location times the number of model fields that exist in the vertical, plus possible variables at e.g. the surface.
    • In this case only the horizontal coordinates are used in coords_l.

The index array id_lstate_in_pstate is an integer array in form of a one-dimensional vector. One initializes this vector by determining the indices of the elements of the local state vector in the global, or domain decomposed, state vector. For using PDAFlocal one has to provide id_lstate_in_pstate to PDAFlocal by calling `PDAFlocal_set_indices'. The interface is:

SUBROUTINE PDAFlocal_set_indices(dim_l, id_lstate_in_pstate)

  INTEGER, INTENT(in) :: dim_l                          ! Dimension of local state vector
  INTEGER, INTENT(in) :: id_lstate_in_pstate(dim_l)     ! Index array for mapping

Hint for id_lstate_in_pstate:

• The initialization of the index vector id_lstate_to_pstate is analogous to a loop that directly performs the initialization of a local state vector. However, here only the indices are stored.
• See the PDAFlocal overview page for more information on the functionality of PDAFlocal.