Changes between Version 293 and Version 294 of LnDevel


Ignore:
Timestamp:
May 29, 2025, 3:39:45 PM (3 days ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • LnDevel

    v293 v294  
    159159
    160160Important:
    161 1. PDAF V3.0 is not fully backward compatible, due to changes in the code. Thus, with this release, it is not possible to just compile and link with existing implementations. The required adaptions are not large. (Please see https://pdaf.awi.de/trac/wiki/PortingToPDAF3 for a description of how to adapt your existing code for PDAF V3.0). Below the code changes affecting backward-compatibility are also described.
    162 
    163 2. We have marked this release as a beta-release. While we have tested this release with different applications, we cannot exclude that there might be some hidden issues due to the extensive changes in the code. 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 hopefully be released in 2-3 months. During this time, we will also finalize the documentation to reflect all changes.
     1611. We have marked this release as a beta-release mainly because of the large 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 hopefully be released in 2-3 months. During this time, we will also finalize the documentation to reflect all changes.
     162
     1632. 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. (Please see https://pdaf.awi.de/trac/wiki/PortingToPDAF3 for a description of how to adapt your existing code for PDAF V3.0). Below the code changes affecting backward-compatibility are also described.
     164
     1653. Information for porting and about new features can be found at:
     166* https://pdaf.awi.de/trac/wiki/PortingToPDAF3
     167* https://pdaf.awi.de/trac/wiki/PDAF3_new_functionality
    164168
    165169Major changes with effect on backward-compatibility
    166170* 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'.
    167 * Change for offline mode: It is no longer possible to specify the offline mode as 'subtype=5'. The offline mode can now only be activated with a call to 'PDAF_set_offline_mode'.
    168 * 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 ensemble are changed as 2=>10, 3=>11.
     171* 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.
     172* 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.
    169173* 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)
    170174* The SEEK filter (filtertype=0) was finally removed after it was marked deprecated for a longer period.
    … …  
    176180* Incremental Analysis Updates (IAU): The previous IAU of PDAF was recoded. Now there is a fully featured IAU implementation.
    177181* Added ENSRF/EAKF: The ensemble square-root filter (ENSRF, Whitaker & Hamill, 2002) and ensemble adjustment filter with local linear regression (EAKF, Anderson, 2003) were added. These filters perform the analysis step through serial processing of individual observations.
    178 * 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), and higher order moments (PDAF_diag_compute_moments).
     182* 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).
    179183* Added observation diagnostics module for OMI: This is a set of routines that give the user access to the observation information, including the observed ensemble and the observed ensemble mean. In addition, there are routines computing statistics for the difference between the observations and the observed ensemble mean.
    180184* New routines to set parameters for PDAF: Before, the parameters were all set in the call to PDAF_init. Now, there are the new routines PDAF_set_iparam and PDAF_set_rparam to set selected parameters, without the need to specify all parameters. These routines make the specification of parameters for PDAF more flexible and can also be used during a run to change parameter values.
    181 * New interface for offline coupled assimilation: With the new routines PDAF_assim_offline_X the offline mode is now clearly separated from the online coupling.
    182 * Revision of the initialization of observations: Observations are now initialized before the actual analysis step is computed. Also, the observation operator is called before the actual analysis step. This change allows for the option to initialize observations before prepoststep_pdaf is called for the forecast ensemble. Related to this, the screen output for the observations was revised and is now displayed in a different location.
    183 * New PDAF3 interface: The selection of possible calls to PDAF*_put_state and PDAF*_assimilate has grown over the years because new functionality, particularly PDAF-OMI and PDAFlocal, has required a new interfaces. We defined a new standard interface in which a single routine (PDAF3_assimilate) can execute all available filter methods for the case of a diagonal observation error covariance matrix. The routine leverages the latest features that were introduced in previous PDAF releases to allow for a minimum number of arguments. There is also the routine PDAF3_put_state, which is now mainly recommended when the offline mode is used.
    184 * 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.
    185 * Change for flexible parallelization variant: It is now possible to use PDAF_assimilate 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.
    186 * New routine PDAFomi_set_localize_covar: This routine is called in the OMI observation module in init_dim_obs_pdafomi. It sets the information for localization in the LEnKF and ENSRF/EAKF methods. (optional for LEnKF)
    187 * Calling LEnKF with the universal routine PDAF3_assimilate: In PDAF 2.3 and before, the LEnKF had its own interface due to the additional call-back routine localize_covar_pdafomi required by this filter. With the new routine PDAFomi_set_localize_covar that is called in the OMI observation module in init_dim_obs_pdafomi, the additional user-supplied subroutine localize_covar_pdafomi is no longer required, lowering the implementation work for the user.
     185* New interface for offline coupled assimilation: With the new routines `PDAF_assim_offline_X` the offline mode is now clearly separated from the online coupling. (see tutorial or implementation guide)
     186* Simplification for initializing the ensemble forecasting using the new routine `PDAF_init_forecast` as simpler alternative to `PDAF_get_state`.
     187* Revision for initializing of observations inside PDAF: Observations are now initialized before the actual analysis step is computed. Also, the observation operator is called before the actual analysis step. This change allows for the option to initialize observations before prepoststep_pdaf is called for the forecast ensemble. Related to this, the screen output for the observations was revised and is now displayed in a different location.
     188* New PDAF3 interface: The selection of possible calls to PDAF*_put_state and PDAF*_assimilate has grown over the years because new functionality, particularly PDAF-OMI and PDAFlocal, has required a new interfaces. We defined a new standard interface in which a single routine (`PDAF3_assimilate`) can execute all available ensemble filter methods for the case of a diagonal observation error covariance matrix. The routine leverages the latest features that were introduced in previous PDAF releases to allow for a minimum number of arguments. There is also the routine PDAF3_assim_offline for the offline mode.
     189* 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.
     190* 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.
     191* New routine `PDAFomi_set_localize_covar`: This routine can be called in the OMI observation module in init_dim_obs_pdafomi. It sets the information for localization in the LEnKF and ENSRF/EAKF methods and simplifies the code compared to using localize_covar_pdafomi in PDAF2. (Using localize_covar_pdafomi is still possible)
     192* Calling LEnKF with the universal routine PDAF3_assimilate: In PDAF 2.3.1 and before, the LEnKF had its own interface due to the additional call-back routine localize_covar_pdafomi required by this filter. With the new routine `PDAFomi_set_localize_covar`, the additional routine is no longer required and the LEnKF can be used with the unversal interface routine.
    188193* New routine `PDAF_set_seedset`: This routine can be used to seed the random number seed for PDAF's random number generating routine.
    189194* 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.
    190 * Added routine 'PDAF_print_DA_types': This routine writes a list of the available types of DA methods and named parameters PDAF_DA_X.
    191 * Added Fortran function PDAF_localfilter as an alternative to subroutine PDAF_get_localfilter to make the code more compact
    192 * Added subroutine PDAF_get_local_type and Fortran function PDAF_local_type. These return information which of the different localization variants is used by the active assimilation method (no localization, local analysis, covariance localization, covariance localization with serial observation processing)
     195* Added routine `PDAF_print_DA_types`: This routine writes a list of the available types of DA methods and named parameters PDAF_DA_X.
     196* Added Fortran function `PDAF_localfilter` as an alternative to subroutine `PDAF_get_localfilter` to make the code more compact
     197* 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)
    193198* The screen output for the configration overview of the DA method was revised and provides now a complete overview
    194 * 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.
    195 * New routine 'PDAF_init_forecast'. This is an alias to 'PDAF_get_state'. The new naming should indicate its purpose better.
     199* 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.
    196200
    197201
    198202Other changes:
    199 * The tutoral input files have been regenerated using Python scripts instead of the previous Matlab scripts. This changed their numbers.
     203* The tutoral input files have been regenerated using Python scripts instead of the previous Matlab scripts. This changed their values.
    200204* Changed statistics for locally omitted observations: Now, these are only counted for analysis domains with observations.
    201205* Added information output on allocated memory in PDAF-OMI
    202 * Revised the internal structure of the code for DA method using modularization
    203206* Revised timers inside the DA methods to account for the changed placement of observation-related routines.
    204 * 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
     207* 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
    205208* Revision of PDAF file headers: It is now possible to use 'Doxygen' to generate a documentation and structure overview of PDAF.
    206209