= Adding a Filter Algorithm to PDAF =

[[PageOutline(2-3,Contents of this page)]]

This text describes the implementation strategy and internal structure of PDAF valid for version 1.7.0 and later. If you use an earlier version of PDAF, we recommend to update to the most recent version. In this text, we assume that the reader is already familiar with PDAF to the extend of experience with the implementation of a model with PDAF that is described in the [ImplementationGuide implementation guide].

The internal structure of PDAF is organized into a generic part providing the infrastructure to perform ensemble forecasts and filter analysis steps. The generic part is independent of the particular filter algorithm and only distinguishes between ensemble based filters (all filters except SEEK) and mode based filters (currently only SEEK). The filter-specific routines are called through an internal interface.

Each filter algorithm consists of 6 routines that are described below. All routines are called trough the internal interface of PDAF, except for the "put state" routine (`PDAF_put_state_X` where X is the name of the selected filter). 

== PDAF's Internal Interface ==

Before explaining the filter-specific routines and the calling interface of each routine, we provide an overview of the internal interface routines of PDAF. The internal interface of PDAF is structured as follows ('X' is the name of the filter algorithm):

The routine `PDAF_init` calls
 * `PDAF_init_filters` - interface routine to `PDAF_X_init`[[BR]]
   * `PDAF_X_init` performs the filter-specific initialization of parameters and calls the user-supplied routine that initializes the initial ensemble of model states.
 * `PDAF_alloc_filters` - interface routine to `PDAF_X_alloc`[[BR]]
   * `PDAF_X_alloc` allocates the filter-specific arrays.
 * `PDAF_options_filters` - interface routine to `PDAF_X_options`
   * `PDAF_X_options` is an optional routine. Its purpose is to display an overview of available options for the filter algorithm.


The routine `PDAF_get_state` calls
 * `PDAF_initinfo_filters` - interface routine to `PDAF_X_initinfo`
   * `PDAF_X_initinfo` displays information on the current configuration of the filter algorithm.


The routine `PDAF_print_info` only includes the interface to `PDAF_X_memtime`
 * `PDAF_X_memtime` displays information on the execution duration of the different parts of the assimilation process as well as information on the amount of allocated memory. This functionality is optional.


The routine `PDAF_put_state_X` is called directly from the model code. There is a separate routine for each filter. The standard implementation  calls
 * `PDAF_X_initinfo`
   * This is the same routine that is called by `PDAF_get_state`. Here, it is only called, if the offline mode of PDAF is used.
 * `PDAF_X_update`
   * This routine contains the actual assimilation or analysis step of the filter algorithm.


When `PDAF_init` is called, the filter algorithm is chosen by its ID number. Internally to PDAF, each filter is identified by a string that is defined in `PDAF_init_filters`. The interface routines have a very simple structure. In general, they select the filter-specific routine based on the string identifying the filters. When a filter algorithm is added a line for the corresponding filter-specific routine has to be inserted to each of the interface routines. 

== Filter-specific routines ==

When a filter algorithm is added, the following filter routines have to be implemented and inserted to each interface routines described above.

 * `PDAF_X_init`
 * `PDAF_X_alloc`
 * `PDAF_X_options`
 * `PDAF_X_initinfo`
 * `PDAF_X_memtime`

In addition, the routine
 * `PDAF_put_state_X`
has to be implemented.

=== `PDAF_X_init` ===

The routine `PDAF_X_init` performs the initialization of filter-specific parameters. In addition, it calls the user-supplied routine that initializes the initial model state ensemble.

The interface is as follows: