Changes between Version 2 and Version 3 of PortingToPDAF3


Ignore:
Timestamp:
Apr 2, 2025, 1:41:25 PM (24 hours ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • PortingToPDAF3

    v2 v3  
    11= Porting from PDAF2 to PDAF3 =
     2
     3[[PageOutline(2-3,Contents of this page)]]
    24
    35PDAF 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 switching 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).
    46
    5 Here we explain the steps required to adapt your code to PDAF 3. This relates to Fortran code.
     7Here we explain the steps required to adapt your code to PDAF 3.
     8
     9== Using PDAF3 with existing codes ==
     10
     11To use existing assimilation code, we recommend the following steps. This relates for Fortran code.
    612
    713* Include[[BR]] `USE PDAF`[[BR]] in all routines that call PDAF routines (e.g. in init_pdaf and assimilate_pdaf).
    814* If you used `USE PDAF_interface_module` in your code, replace this by `USE PDAF`.
    9 * You might need to adapt your Makefile 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 places in `include/`
     15* 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 places in `include/`
    1016* particular cases:
    11   * If you used the offline mode by specifying **subtype=5**: change `subtype` to 0 and add a call to the routine `PDAF_set_offline_mode` in `init_pdaf`. (see, e.g. the file `tutorial/offline_2D_serial/init_pdaf_offline.F90` where the call to `PDAF_set_offline_mode` is at the very end of the routine; see also [wiki:OfflineInitPdaf]).
     17  *  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, addapt to use the Makefile in the base-directory (alternatively you can copy this Makefile into src/ and adapt it according to the hints given inside the Makefile
     18  * If you used the offline mode by specifying **subtype=5**: change `subtype` to 0 and add a call to the routine `PDAF_set_offline_mode` in `init_pdaf`. (see, the example in the file `tutorial/offline_2D_serial/init_pdaf_offline.F90` where the call to `PDAF_set_offline_mode` is at the very end of the routine; see also [wiki:OfflineInitPdaf]).
    1219  * If your code calls **PDAF_assimilate_lnetf** or **PDAF_put_state_lnetf**: There was an argument added for `init_obs_pdaf`. the code has to be adapted for this additional arguments. (see [wiki:PDAF_assimilate_lnetf] or [wiki:PDAF_put_state_lnetf])
    13   * Of your code used the **SEEK filter**: This filter was deprecated for a longer time and is no longer available with PDAF V3.0. Any call to e.g. PDAF_assimilate_seek has to be removed.
     20  * If your code used the **SEEK filter**: This filter was deprecated for a longer time and is no longer available with PDAF V30. Any call to e.g. PDAF_assimilate_seek has to be removed.
     21  * If your code used the **'simplified interface'**, i.e. routines with ending `_si`: The `_si` routine are no longer present in PDAF V3.0. 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.
    1422
    1523With these adaptions, the compiling the program should be possible.
    1624
     25Two additional changes relate to the specification of `subtype` and the integer and real parameters for `PDAF_init`:
     26* A few of the parameters used to configure PDAF in the call to `PDAF_init` have changed their index. This only concerns the EnKF, LEnKF, LKNETF and PF. An overview of the parameters is show in the tables on the [wiki:AvailableOptionsforInitPDAFinPDAF3 page 'Available options for the different DA methods'].
     27* The values of `subtype` have been renumbered as follows
     28||= old subtype[[BR]]PDAF2 =||= new subtype[[BR]]PDAF3 =||
     29|| 0 || 0 (no change) ||
     30|| 1 || 1 (no change) ||
     31|| 2 || 10 ||
     32|| 3 || 11 ||
     33|| 4 || 2 ||
     34|| 5 || 5 (no longer offline mode) ||
     35|| 6 || 3 ||
     36|| 7 || 4 ||
    1737
    1838
     39== Porting to the PDAF3 interface ==
    1940
    20 * New general module 'PDAF' replacing the optional module 'PDAF_interface
    21 * The subtypes have been renumbered: subtypes 0 and 1 are unchanged, the other dynamic subtypes are changed as 4=>2, 6=>3, 7=>4; the variant with fixed ensmeble are changed as 2=>10, 3=>11.
    22 * Changes in the index value a some parameters: The index of some of the parameters set in PDAF_init has changed for better overall consistency. (See .... for an overview of the parameters)
    23 * The SEEK filter (filtertype=0) was finally removed after it was marked deprecated for a longer period.
    24 * Removed 'src/Makefile'. Now only the new Makefile in the main directory exists. However, if one has a workflow basing on src/Makefile and can copy the Makefile and adapt it according to the description within the file.
    25 * The 'simplified interface' (routine names ending with `_si`) has been removed.
     41PDAF V3.0 also provides a set of new routines to call the analysis step, which we call the PDAF3 interface, because the calls are of the format `PDAF3_assimilate_` or `PDAF3_put_state_`. It is not required to switch to these new interface routines, but generally recommended.
    2642
    27 - additional parameter in PDAF_assimilate_lnetf and PDAF_put_state_lnetf
    28 - porting from PDAFomi to PDAF3 for global filters: Just change the name of the routine
    29 - porting from PDAFlocalomi to PDAF3 for local filters: Just change the name of the routine
    30 - porting from PDAFomi to PDAF3 for local filters: The PDAF3 interface uses PDAFlocal so that the routines g2l_state_pdaf and l2g_state_pdaf are not present. Follow the implementation guide for init_dim_l to initialize the information for PDAFlocal
    31 - porting from classical PDAF interface with fully specification of all call-back routines: See implementation guide (PDAF3 uses both PDAF-OMI and PDAF-local to provide compact interfaces)
    32 - porting from PDAFomi or PDAFlocalomi for 3D-Var: Change the name of the routine
    33 - check subtype: 0 and 1 are unchanged; for others: 2=>10, 3=>11, 4=>2, 6=>3, 7=>4
    34 - the option to run the offline mode as 'subtype=5' was removed. It is now require to call "PDAF_set_offline_mode"
     43Details about the PDAF3 interface are provided on the [wiki:PDAF3_interface Page on the PDAF3 interface].
     44
     45== Using new features of PDAF V3.0 ==
     46
     47PDAF 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].