| 26 | | [wiki:PDAF3_new_functionality] - update new added features in V3.0final |
| 27 | | |
| 28 | | [wiki:PDAF3_interface] - add PDAF3_set_parallel and PDAF3_init |
| 29 | | |
| 30 | | [wiki:OMI_observation_operators_PDAF3] - add PDADFomi_obs_op_extern (no lin and adj) |
| 31 | | |
| 32 | | [wiki:ImplementationConceptOnline] - add note on PDAF3_set_parallel |
| 33 | | |
| 34 | | [wiki:ImplementationConceptOffline] - add note on PDAF3_set_parallel |
| 35 | | |
| 36 | | [wiki:OfflineAdaptParallelization_PDAF3] - note: call to init_parallel_pdaf not required for serial program |
| 37 | | |
| 38 | | [wiki:OfflineInitPdaf_PDAF3] - update for PDAF3_init |
| 39 | | |
| 40 | | [wiki:OnlineInitPdaf_PDAF3] - update for PDAF3_init |
| 41 | | |
| 42 | | |
| 43 | | |
| 44 | | |
| 45 | | == Version 3.0 - August XX, 2025 == |
| 46 | | |
| 47 | | This is a major release and completes Version 3.0 based on the pre-release 3.0beta. As this includes the changes of V3.0beta, we repeat here the full changes after pointing to the changes added in the final release of V3.0. |
| | 25 | This is a major release and completes Version 3.0 based on the pre-release 3.0beta. This includes all changes of V3.0beta, of which we list only new features below. |
| 72 | | The whole PDAF code was revised and modernized. Further, a new universal calling interface for the analysis step and other new functionality was added. |
| 73 | | |
| 74 | | Important: |
| 75 | | 1. We have marked this release as a beta-release mainly because of the large amount of changes in the code. While we have tested this release carefully with different applications, we cannot exclude that there are issues that we didn't find. We like to motivate all users to test PDAF V3.0 and to let us know possible issues (using the Issues-function in Github or by email to pdaf\@awi.de). This will help us to fix such issues so that the final release for PDAF V3.0 can be done in 2-3 months. During this time, we will also finalize the documentation to reflect all changes. |
| 76 | | |
| 77 | | 2. PDAF V3.0 is not fully backward compatible, due to the modernization of the code. Thus, with this release, it is not possible to just compile and link with existing implementations like in previous releases. The required adaptions are, however, small. Below the code changes affecting backward-compatibility are also described. |
| 78 | | |
| 79 | | 3. Information for using PDAF3 and about new features can be found at: |
| 80 | | * Porting to PDAF3: https://pdaf.awi.de/trac/wiki/PortingToPDAF3 |
| 81 | | * New features: https://pdaf.awi.de/trac/wiki/PDAF3_new_functionality |
| 82 | | |
| 83 | | Major changes with effect on backward-compatibility |
| 84 | | * New general module 'PDAF' replacing the optional module 'PDAF_interfaces_module'. In Fortran code, it is now required to include this module with 'USE PDAF'. |
| 85 | | * Change for offline mode: It is no longer possible to specify the offline mode as 'subtype=5'. We have introduced a new interface 'PDAF_assim_offline' for the offline mode, which simplified the implementation. |
| 86 | | * Renumbered subtypes: subtypes 0 and 1 are unchanged, the other dynamic subtypes are changed as 4=>2, 6=>3, 7=>4; the variant with fixed ensemble are changed as 2=>10, 3=>11. |
| 87 | | * Changes in the index value of some parameters: The index of some of the parameters set in PDAF_init has been changed for better overall consistency. (See https://pdaf.awi.de/trac/wiki/AvailableOptionsforInitPDAFinPDAF3 for an overview of the parameters) |
| 88 | | * The SEEK filter (filtertype=0) was finally removed after it was marked deprecated for a longer period. |
| 89 | | * Removed 'src/Makefile'. Now, only the new Makefile in the main directory exists. However, if one has a workflow based on src/Makefile one can copy the Makefile and adapt it according to the description within the file. |
| 90 | | * The 'simplified interface' (routine names ending with `_si`) has been removed. |
| 91 | | * For information on how to adapt a program for PDAF V3.0, see https://pdaf.awi.de/trac/wiki/PortingToPDAF3 |
| 92 | | |
| 93 | | Major changes and additions (see also https://pdaf.awi.de/trac/wiki/PDAF3_new_functionality): |
| 96 | | * Added more diagnostic routines, e.g., for computing ensemble mean (PDAF_diag_ensmean), ensemble mean standard deviation (PDAF_diag_stddev), variance state vector (PDAF_diag_variance), RMS difference between two vectors (PDAF_diag_rmsd), higher order moments (PDAF_diag_compute_moments), and reliability budget (PDAF_diag_reliability_budget). |
| | 54 | * Added more diagnostic routines, e.g., for computing ensemble mean (`PDAF_diag_ensmean`), ensemble mean standard deviation (PDAF_diag_stddev), variance state vector (`PDAF_diag_variance`), RMS difference between two vectors (`PDAF_diag_rmsd`), higher order moments (`PDAF_diag_compute_moments`), and reliability budget (`PDAF_diag_reliability_budget`). |
| 103 | | * Change for flexible parallelization variant: It is now possible to use PDAF3_assimilate (or any other 'assimilate' routine) for the flexible parallelization, while PDAF_put_state routines had to be called before. Since PDAF_assimilate is called at each time step during the forecast phase this allows easy use of the IAU functionality. This change also reduces teh required code changes for the flexible parallelization variant. |
| 104 | | * New routine `PDAF_get_fcst_info`: This routine allows to retrieve the return values of PDAF_get_state (nsteps, time, doexit) for the case that PDAF_assimilate routines, which do not return these values, are used. This is used in the revised flexible parallelization variant. |
| | 59 | * Change for flexible parallelization variant: It is now possible to use `PDAF3_assimilate` (or any other 'assimilate' routine) for the flexible parallelization, while `PDAF_put_state routines` had to be called before. Since PDAF_assimilate is called at each time step during the forecast phase this allows easy use of the IAU functionality. This change also reduces teh required code changes for the flexible parallelization variant. |
| 107 | | * New routine `PDAF_set_seedset`: This routine can be used to seed the random number seed for PDAF's random number generating routine. |
| 108 | | * Introduced named variables for choosing the filter type: The filter type can now also be specified by a named parameter of the form PDAF_DA_X, where 'X' is the DA method, thus, e.g., 'PDAF_DA_ESTKF'. With this, one does not need to look up the number of the filter type. |
| 109 | | * Added routine `PDAF_print_DA_types`: This routine writes a list of the available types of DA methods and named parameters PDAF_DA_X. |
| 110 | | * Added Fortran function `PDAF_localfilter` as an alternative to subroutine `PDAF_get_localfilter` to make the code more compact |
| 111 | | * Added Fortran function `PDAF_local_type` and subroutine `PDAF_get_local_type`. These return information which of the different localization variants is used by a DA method (no localization, local analysis, covariance localization, covariance localization with serial observation processing) |
| 112 | | * The screen output for the configuration overview of the DA method was revised and provides now a complete overview |
| 113 | | * The new module `PDAF` now also includes the routines from 'PDAFomi' and 'PDAFlocal'. Thus, one only needs to use-include 'PDAF' and no longer needs to distinguish the modules. |
| | 62 | * Mandatory module `PDAF`. Because PDAF V3 is fully modularized, rhe module `PDAF` has to be use-included by all routines that call PDAF routines. The new module `PDAF` now also includes the routines from 'PDAFomi' and 'PDAFlocal'. Thus, one only needs to use-include 'PDAF' and no longer needs to distinguish the modules. |
| 115 | | |
| 116 | | Other changes: |
| 117 | | * The tutorial input files have been regenerated using Python scripts instead of the previous Matlab scripts. This changed their values. |
| 118 | | * Changed statistics for locally omitted observations: Now, these are only counted for analysis domains with observations. |
| 119 | | * Added information output on allocated memory in PDAF-OMI |
| 120 | | * Revised timers inside the DA methods to account for the changed placement of observation-related routines. |
| 121 | | * The internal code structure of assimilation algorithms was revised and modularized. This yields a better approach to add further assimilation methods. We also added templates for implementing global or local ensemble filters in `templates/analysis/`. Information on how to add an assimilation algorithm to PDAF can be found at https://pdaf.awi.de/trac/wiki/AddFilterAlgorithm |
| 122 | | * Revision of PDAF file headers: It is now possible to use 'Doxygen' to generate a documentation and structure overview of PDAF. |
| 123 | | |
| 124 | | Bug corrections: |
| 125 | | * Corrected a parallel race condition in the LKNETF NHK variant (subtype=0) in case of OpenMP parallelization |
| 126 | | * Corrected convergence check for the CG+ solver in the 3D-Var methods in case of parallelized control vector. |
| 127 | | * Corrected computation of likelihood for the case that dim_obs_l=0 for some observation type, but overall dim_obs_l>0. This could lead to a segmentation fault in the LKNETF. |
| 128 | | * Correction of type_forget=2: For the case that the adaptive forgetting factor would compute a negative value, the forgetting factor of the previous domain was used. Now, the prescribed default value is used. Here, a possible race condition when using OpenMP was also fixed. |
| 129 | | * Corrected call to U_obs_op_adj. Inside PDAF, a rank-1 array was provided as argument, while it needed to be a rank-2 array with only one column. |
