= Porting from PDAF2 to PDAF3 =

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

PDAF V3.0 is not fully backward compatible with PDAF2. Modernizing the PDAF code motivated us to allow some changes which require code changes by the PDAF users. Thus, when upgrading from using PDAF2 to PDAF3, it is not possible to just compile the new PDAF library and link it with your code (in contrast to many previous releases). 

Here we explain the steps required to adapt your code to PDAF 3.

== Using PDAF3 with existing codes ==

To use existing assimilation code, we recommend the following steps. This relates to Fortran code.

* Include[[BR]] `USE PDAF`[[BR]] in all routines that call PDAF routines (e.g. in `init_pdaf` and `assimilate_pdaf`). 
* If you used `USE PDAF_interface_module` in your code, replace this with `USE PDAF`.
* You might need to adapt the Makefile of your program to include[[BR]]`-IPATH_TO_PDAF_INCLUDE`,[[BR]] where PATH_TO_PDAF_INCLUDE is the directory `include/` of your PDAF installation. The compiler needs to find the PDAF module files which are placed in `include/`. If you use the Makefile from the template or tutorials, you can use `-I{BASEDIR}/include`.
* **Particular cases**:
  *  If the compile process of your programm includes the compilation of PDAF using **src/Makefile**: With PDAF3 the Makefile is now only in the base-directory and there is no Makefile any more in src/. Thus, you would need adapt to use the Makefile in the base-directory (or alternatively you can copy this Makefile into src/ and adapt it according to the hints given inside the Makefile
  * If you used the offline mode by specifying **subtype=5**: change `subtype` to 0 and add a call to the routine [wiki:PDAF_set_offline_mode] in `init_pdaf`. Alternatively, switch from using the `put_state` routine to using the new `assim_offline` routine, e.g. the universal routine [wiki:PDAF3_assim_offline].
  * If your code calls **PDAF_assimilate_lnetf** or **PDAF_put_state_lnetf**: We had to add an argument for `init_obs_pdaf`, which is required internally for the revised observation initialization. The code has to be adapted for this additional argument. (see [wiki:PDAF_assimilate_lnetf] or [wiki:PDAF_put_state_lnetf])
  * If your code used the **SEEK filter**: This filter was deprecated for a longer time and is no longer available with PDAF V3. Any call to e.g. `PDAF_assimilate_seek` has to be removed.
  * If your code used the **'simplified interface'**, i.e. routines with ending `_si`: The `_si` routines are no longer present in PDAF V3. Instead use the full interface routine, i.e. the routine with the same name as the `_si`-routine, but without `_si`. Then, set the arguments to the names that you find inside the `_si` routine file from PDAF2.

With these adaptions, compiling the program should be possible.

**Two additional changes** relate to the specification of `subtype` and the integer and real parameters for `PDAF_init`:
* A few of the parameters used to configure PDAF in the call to `PDAF_init` have changed their index value. This only concerns the EnKF, LEnKF, LKNETF and PF. An overview of the parameters is shown in the tables on the [wiki:AvailableOptionsforInitPDAFinPDAF3 page 'Available options for the different DA methods'].
* The values of `subtype` have been renumbered as follows
||= old subtype[[BR]]PDAF2 =||= new subtype[[BR]]PDAF3 =||=  comment =||
|| 0 || 0 || no change ||
|| 1 || 1 || no change ||
|| 2 || 10 ||
|| 3 || 11 ||
|| 4 || 2 ||
|| 5 || 5 || no longer offline mode ||
|| 6 || 3 ||
|| 7 || 4 ||


== Porting to the PDAF3 interface ==

PDAF V3.0 also provides a set of new routines to call the analysis step. We refer to this as the PDAF3 interface, because the calls are of the format `PDAF3_assimilate_`, `PDAF3_assim_offline`, `PDAF3_put_state`. It is not required to switch to these new interface routines, but it is generally recommended. 

Details about the PDAF3 interface are provided on the [wiki:PDAF3_interface page on the PDAF3 interface].

== Using new features of PDAF V3.0 ==

PDAF V3.0 also introduces several new features. An overview of these is given on the [wiki:PDAF3_new_functionality page on new functionality on PDAF V3.0].