U_prepoststep

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

The routine U_prepoststep is a call-back routine that has to be provided by the user. In the simplified interface the predefined name of the routine is prepoststep_pdaf, but in the full interface, the user can choose the name of the routine. U_prepoststep is called by PDAF_get_state, PDAF_put_state_X, and PDAF_assimilate_X with 'X' being the name of a filter method. The routine is called at the initial time and after a forecast (directly before computing the filter analysis step) and after the analysis step. The purpose of the routine is to give the user full access to the forecast and the analysis ensembles. Typically operations that are performed in U_prepoststep are to compute the estimated RMS errors form the ensemble and to write e.g. the state estimate (i.e. the ensemble mean state). In case of the offline mode, one will also write the model restart files in U_prepoststep when the routine is called after the filter analysis update.

The interface is the following:

SUBROUTINE U_prepoststep(step, dim_p, dim_ens, dim_ens_p, dim_obs_p, &
                       state_p, Uinv, ens_p, flag)

with

• step : integer, intent(in)
  Current time step (When the routine is called before the analysis -step is provided.)
• dim_p : integer, intent(in)
  Size of state vector (local part of process if decomposed)
• dim_ens : integer, intent(in)
  Size of ensemble
• dim_ens_p : integer, intent(in)
  Process-local size of ensemble
• dim_obs_p : integer, intent(in)
  Size of observation vector (local part of process if decomposed)
• state_p : real, intent(inout), dimension(dim_p)
  State vector (forecast or analysis). The vector is generally not initialized in the case of ESTKF/ETKF/EnKF/SEIK. IT can be used freely in this routine
• Uinv : real, intent(inout), dimension(dim_ens-1, dim_ens-1)
  Inverse of the error-subspace matrix matrix A in ETKF and ESKTF; inverse of matrix U in SEIK and SEEK; not used in EnKF.
• ens_p : real, intent(inout), dimension(dim_p, dim_ens)
  State ensemble (process-local part of process if decomposed)
• flag : integer, intent(in)
  PDAF status flag (0 if no error)

Notes:

• The routine is called by all filter processes.
• If parallelization with domain decomposition is used, the variables state_p and ens_p will only contain the state information for the process-local domain. Accordingly, also dim_p and dim_obs_p only contain the state vector size for the local domain.
• For the local filters (LESTKF, LETKF, LSEIK) dim_obs_p is the observation dimension for the full observations.
• The array Uinv is only needed for SEEK filter. Also one needs its values for the ESTKF, ETKF, and SEIK filter to compute the analysis error covariance matrix when these filters used with a fixed-covariance matrix (subtype=3). In all other cases the ensemble array ens_p contains all required information.
• The interface has a difference for ETKF and ESTKF: For the ETKF, the array Uinv has size dim_ens x dim_ens. In contrast it has size dim_ens-1 x dim_ens-1 for the ESTKF. (For most cases, this will be irrelevant, because most usually the ensemble array ens_p is used for computations, rather than Uinv. Only for the SEIK filter with fixed covariance matrix, Uinv is required to compute the estimate analysis error. The fixed covariance matrix mode is not available for the ETKF or ESTKF.)
• For the local filters (LESTKF, LETKF, LSEIK) the matrix Uinv does not contain useful information, because its values are from the last processed local analysis domain only.

Hints:

• If a user considers to perform adjustments to the estimates (e.g. for balances), this routine is the right place for it.
• Only for the SEEK filter the state vector (state_p) is initialized. For all other filters, the array is allocated, but it can be used freely during the execution of U_prepoststep. FOr example one can use the array to store the ensemble mean without allocating a new array.
• The interface through which U_prepoststep is called does not include the array of smoothed ensembles. In order to access the smoother ensemble array one has to set a pointer to it using a call to the routine PDAF_get_smootherens (see page on auxiliary routines)