Auxiliary Routines

PDAF provide a number of auxiliary routines. They provide access to PDAF-internal data, which is not available through the regular interface of PDAF.

Interface specifications

Module PDAF

Starting with PDAF V3.0 the module PDAF is provided. It has to be included with

  USE PDAF

in all routines that call PDAF routines (i.e PDAF_*, PDAFomi_*, PDAFlocal*).

The module PDAF replaces the former module PDAF_interfaces_module of PDAF2. In PDAF releases V2.3.1 and earlier, this module provides interface definitions for the routines of PDAF. Its use was optional. It can be included with use PDAF_interfaces_module.

Set or reset PDAF parameters

PDAF_set_iparam

This routine is used to set integer parameters for PDAF. It was introduced with PDAF V3.0.

The integer parameters specific to a DA method can be set in the array filter_param_i that is an argument of PDAF_init (see the page on initializing PDAF). PDAF_set_iparam provides an alternative way. Instead of providing all parameters in the call to PDAF_init, one can provide only the required minimum for this call. Afterwards, one can then call PDAF_set_iparam for each integer parameter that one intends to specify differently from the default value. An advantage of using PDAF_set_iparam is that one only needs to call it for parameters that one intends to change, while in the call to PDAF_init all parameters up to the index one intends to change have to be specified, even if one does not want to change a parameter value. The tutorials and templates show the use of PDAF_set_iparam.

Full documentation: PDAF_set_iparam

PDAF_set_rparam

This routine is used to set real-valued (floating-point) parameters for PDAF. It was introduced with PDAF V3.0.

The real-value parameters specific to a DA method can be set in the array filter_param_r that is an argument of PDAF_init (see the page on initializing PDAF). PDAF_set_rparam provides an alternative way. Instead of providing all parameters in the call to PDAF_init, one can provide only the required minimum for this call. Afterwards, one can then call PDAF_set_rparam for each integer parameter that one intends to specify differently from the default value. An advantage of using PDAF_set_rparam is that one only needs to call it for parameters that one intends to change, while in the call to PDAF_init, all parameters up to the index one intends to change have to be specified, even if one does not want to change a parameter value. The tutorials and templates show the use of PDAF_set_rparam.

Full documentation: PDAF_set_rparam

Get information for forecast phase

PDAF_get_fcst_info

This routine was introduced with PDAF V3.0.

This routine returns the number of time steps to be computed int he current forecast phase. It also returns an exit flag to control the termination of ensemble forecasting and a value of the model time at the beginning of the forecast.

This routine is required in the setup of the flexible parallelization variant in the form introduced with PDAF V3.0. However it can balso be useful for the fully parallel case.

Full documentation: PDAF_get_fcst_info

Access to PDAF-internal arrays

PDAF_get_smootherens

A smoother is available for several filters (ESTKF/LESTKF/ETKF/LETKF/EnKF/NETF/LNETF).

This routine is called to set a Fortran pointer to the array in PDAF that stores the ensembles for smoothing. In addition, the routine returns the available lag of the smoothing. Using this routine is required to aassess the smoother array, e.g. to write the smoother ensemble or its mean into a file.

Full documentation: PDAF_get_smootherens

PDAF_set_smootherens

A smoother is available for several filters (ESTKF/LESTKF/ETKF/LETKF/EnKF/NETF/LNETF).

This routine is called to set a Fortran pointer to the array in PDAF that stores the ensembles for smoothing. In addition, it sets the available lag of the smoothing. This routine is called in the offline mode of PDAF. While in the online mode, the smoother ensemble array is filled automatically by PDAF, one has to fill it manually in the offline mode. PDAF_set_smootherens gives access to the smoother array to fill it.

Full documentation: PDAF_set_smootherens

PDAF_set_ens_pointer

This routine allows a program to get a Fortran pointer to the internal ensemble array of PDAF. This provides direct access to the ensemble array.

PDAF_set_ens_pointer is a special routine that is never needed when the standard online or offline modes of the implementation are used. However, the routine allows to build a code that uses each column of the ensemble array to store the model fields. Thus, one can avoid allocating additional memory for the model fields.

Full documentation: PDAF_set_ens_pointer

Access to index information

PDAF_get_memberid

The routine returns the value of the ensemble member ID. It can be called during the ensemble integration, if a program needs this information, e.g. if ensemble-specific forcing is applied. Also it can be used in the routines collect_state_pdaf and distribute_state_pdaf.

Full documentation: PDAF_get_memberid

PDAF_get_obsmemberid

The routine returns the value of the ensemble member ID for the application of the observation operator. The routine can be called in the observation-operator routine obs_op_OBSTYPE in an PDAF_OMI observation module or in the user-supplied routine obs_op_pdaf if PDAF-OMI is not used.

The routine an be useful if the observation operator does not actually operate on the state vector that is provided by PDAF. For the special situation where one, e.g., reads the observed state vector from a file (because it might be initialized separately). There might also be cases in which one likes to read model state information from a file (e.g. if the observation operator performs an averaging over time, while the state vector for the analysis step only contains a single time instance). Inthese cases one need to member index as provided by PDAF_get_obsmemberid.

Full documentation: PDAF_get_obsmemberid

Incremental analysis updates

See page on Incremental Analysis Updates in PDAF3.

Controlling the MPI communicator for PDAF

PDAF_set_comm_pdaf

This routime allows to specify the MPI communicator on which the overall PDAF communication bases.

By default, PDAF bases on MPI_COMM_WORLD, thus all processes in a program. This routine allows to set a different communicator. This can be useful if a model is e.g. run with an OI-server so that the world communicator is split into processes for the file (I/O) operations and other processes for the actual model run. In this case, the model would run using a communicator distinct from MPI_COMM_WORLD and PDAF should operate only with this communicator. PDAF_set_comm_pdaf allows the user to specify this communicator for PDAF.

Full documentation: PDAF_set_comm_pdaf

Debugging

PDAF_set_debug_flag

This routine was introduced with PDAF V2.1.

The routine allows to activate debugging output.

Full documentation: PDAF debuggging.

Information on localization

PDAF_localfilter

This is a Fortran function that was introduced with PDAF V3.0

The function is an alternative to the subroutine PDAF_get_localfilter. In PDAF_localfilter the return value of the function is directly used, while for PDAF_get_localfilter the return value is an argument of the routine.

The function returns the information whether the chosen filter is a domain-localized filter (LESTKF, LETKF, LSEIK, LNETF). It also indicates the ENSRF since these filters use the same observation handling of the domain-localized filters.

Full documentation: PDAF_localfilter

There is also a variant in the form of a subroutine: PDAF_get_localfilter

PDAF_local_type

This is a Fortran function that was introduced with PDAF V3.0

The function returns the information on the localization type of the filter set in the call to PDAF_init. With this one can distinguish filters using domain localization (LESTKF, LETKF, LSEIK, LNETF), covariance localization (LEnKF), or covariance localization with observation handling like domain localization (ENSRF/EAKF). This information is more detailed than what is returned by PDAF_localfilter.

Full documentation: PDAF_local_type

There is also a variant in the form of a subroutine: PDAF_get_local_type

Additional (advanced) functionality

PDAF_print_DA_types

This routine was introduced with PDAF V3.0.

PDAF_print_DA_types can be called to show a list of IDs of the DA methods in PDAF. It will list the integer values of filtertype that can be specified in the call to PDAF_init. In addition, it will list the pre-defined parameter values PDAF_DA_X which are set to these values. These pre-define parameter values allow the user to specify e.g. the LESTKF with PDAF_DA_LESTKF as filtertype argument in the call to PDAF_init.

Full documentation: PDAF_print_DA_types

PDAF_set_seedset

This routine was introduced with PDAF V2.1.

This routine can be called to choose a seedset for the random number generator used in PDAF. With this one can perform experiments using different random numbers.

Full documentation: PDAF_set_seedset

PDAF_reset_forget

This routine was introduced with PDAF V2.0

The routine allows a user to reset the forgetting factor manually during the assimilation process.

Full documentation: PDAF_reset_forget

Note: Starting from PDAF V.30 one can also use PDAF_set_rparam to reset the value of the forgetting factor.

PDAF_force_analysis

This routine was introduced with PDAF 2.0.

The routine allows a user to enforce the execution of the analysis step at the next call to PDAF*_put_state or PDAF*_assimilate.

In particular for PDAF*_assimilate, the number of time steps is set before the forecast phase is entered. However, one might not know the actual length of the forecast phase, e.g. the time when new observations arrive. In this case, one can set for number of time steps to a large value and then check for new observations during the time stepping and call PDAF_force_analysis just before PDAF*_assimilate is called to enforce that the analysis step is executed.

Full documentation: PDAF_force_analysis

PDAF_set_memberid

This routine was introduced with PDAF 2.0.

The routine allows a user to reset the ensemble member counter inside PDAF. This routine should only be used in the flexible parallelization mode. Resetting the member counter, allows e.g. to enforce the execution of the analysis step in the case, when according to the PDAF-internal counter, the ensemble integration is not yet complete. For this, one has to specify the member-ID to be the ensemble size.

To just enforce an analysis step, we recommend to use the routine PDAF_force_analysis. This routine is also compatible with PDAF_assimilate_X.

Full documentation: PDAF_set_memberid