Changes between Version 31 and Version 32 of SoftwarePackage


Ignore:
Timestamp:
Dec 9, 2021, 4:58:04 PM (12 months ago)
Author:
lnerger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • SoftwarePackage

    v31 v32  
    2424 * `models/`
    2525  * This directory contains fully implemented toy models for assimilation experiments with PDAF (added in PDAF 1.15)
    26  * `nullmpi/`
    27   * This directory contains the file `nullmpi.F90`. The file provides MPI functions for the single-process case. It replaces a real MPI library, if users want to compile PDAF without parallelization support.
    2826 * `src/`
    2927  * This directory contains the source code of the core routines of PDAF. In addition, a Makefile is included to compile the PDAF library file.
     
    3331  * This directory contains the test suite of PDAF including example implementations. For more details see the section on [#TheTestSuite the test suite]
    3432 * `tutorial/`
    35   * From version 1.9 of PDAF, this directory contains an example implementation of the analysis step in the offline mode of PDAF (i.e. an analysis step in a program separate from the forcasting model)
     33  * This directory contains example implementations of the analysis step in the online and offline modes of PDAF
     34 * `external/`
     35  * From PDAF V2.0, this directory contains external libraries, in particular solver methods used in 3D-Var
    3636
    3737== Compiling the PDAF library ==
    3838
    39 The library file of PDAF can be compiled on its own or in connection with an example implementation from `tutorial/`, `models/`, or `testsuite/`. Here, we describe the stand-alone compilation. In order to build the library file, you need a Fortran-2003 compatible compiler and 'make'. In addition, the libraries 'BLAS' and 'LAPACK' are required.
     39The library file of PDAF can be compiled on its own or in connection with an example implementation from `tutorial/`, `models/`, or `testsuite/`. Here, we describe the stand-alone compilation. In order to build the library file, you need a Fortran-2003 compatible compiler and 'make'. In addition, the libraries 'BLAS', 'LAPACK', and 'MPI' are required.
    4040
    4141Compiling the PDAF library is conduction in the following steps:
    42  1. Choose a suitable include file for the make process and/or edit one. In the directory `make.arch/` several include files are provided. There are include files for compilation with and without MPI. The name of the include files as well as the header comment in the file described the intended architecture. The choices `linux_gfortran.h` and `linux_gfortran_openmpi.h` are quite generic choices that should work on a wide range of computers.
     42 1. Choose a suitable include file for the make process and/or edit one. In the directory `make.arch/` several include files are provided. There are include files for compilation with and without MPI. The name of the include files as well as the header comment in the file described the intended architecture. The choice  `linux_gfortran_openmpi.h` is a quite generic choice that should work on a wide range of computers.
    4343
    4444 2. The environment variable PDAF_ARCH specifies for which architecture you compile PDAF according to your choice in step 1. You need to specify the file name without '.h'. You can specify PDAF_ARCH in the make command line like `make PDAF_ARCH=NAME`. Alternatively, you can set the environment variable $PDAF_ARCH in the shell to the name of the include file (without ending .h), e.g. by `setenv PDAF_ARCH NAME` in case of a (t)csh or `export PDAF_ARCH=NAME` in case of bash.
     
    4646 3. Execute `cd src` and type 'make' at the prompt. This will compile the sources. The library file is generated in the directory `lib/`.
    4747
    48  * '''Note on parallelization:''' PDAF is generally intended for parallel computing using MPI. However, it can be compiled for serial computing. To compile PDAF for this case a simplified MPI header file is included in `src/dummympi` and should be in the include path. In addition, a dummy implementation of MPI, which behaves like MPI in the single-process case, is provided in the directory `nullmpi/`. For the serial case, this file should also be compiled and linked when PDAF is linked to a program. The include files in `make.arch` without MPI-parallelization include the required settings.
     48 * '''Note on parallelization:''' PDAF is generally intended for parallel computing using MPI. Before PDAF V2.0 it was also possible to compile PDAF without MPI by using a stub library that simulated the behavior for MPI for a single process that we provided with PDAF. With PDADF V2.) we revised the MPI implementation and removed this option. Given that it is today extremely easy to install an MPI library (it is virtually always available as a package in any Linux distribution and standard on cluster computers) we prefer not to invest in maintaining and upgrading the MPI stub library.
    4949
    5050 * '''Note on precision of floating point variables:''' PDAF is designed to use floating point variables of double precision. However, for flexibility the variables are decared in the source code without a 'KIND' specification. Thus, for the compilation one has to specify that the compiler treats all 'real' variables with double precision accuracy. This is done, e.g. for gfortran by setting `-fdefault-real-8` or for ifort by setting `-r8`. In the provided include files in `make.arch/` these specifications are included. (Starting from version 1.8 of PDAF also single precision is supported. To enable it in PDAF, one has to use the preprocessor definition `-DSNGLPREC`.)
     
    5454== Tutorial Implementations ==
    5555
    56 The directory `tutorial/` contains four example implementations as well as inputs file used to run the examples (from Version 1.9 of PDAF):
     56The directory `tutorial/` contains different example implementations as well as inputs file used to run the examples (from Version 1.9 of PDAF). They are the recommended starting point to study the online and offline implementations of PDAF.
    5757 * `offline_2D_serial`
    5858  * This directory contains the example implementation of the offline mode without parallelization
     
    6161 * `online_2D_serialmodel`
    6262  * This directory contains an example implementation of the online mode with a serial model
     63 * `online_2D_serialmodel_2fields`
     64  * This directory contains an example implementation of the online mode with a serial model using multivariate assimilation
    6365 * `online_2D_parallelmodel`
    6466  * This directory contains an example implementation of the online model with a parallelized model
    65  * `inputs`
    66   * This directory contains inputs files used to run the examples
    6767
    6868Please see the [wiki:PdafTutorial tutorial page] for the tutorials describing these implementations.
     
    7676 * `lorenz96`
    7777  * This directory contains the Lorenz-96 model as well as a full data assimilation implementation of the model with PDAF. This model can be configured to have a sufficiently large state dimension to test low-rank filter algorithms like the SEIK filter. (We have using this model for example in the study: Janjić, T., Nerger, L., Albertella, A., Schröter, J., Skachko S. (2011). On domain localization in ensemble based Kalman filter algorithms. Monthly Weather Review, 139, 2046-2060 ( doi:10.1175/2011MWR3552.1).) Compiling and running this model is described in detail on the page on the [wiki:Lorenz_96_model Lorenz-96 model].
     78 * `lorenz2005b`
     79  * Added in PDAF V2.0, this directory contains the Lorenz-2005 model variant II as well as a full data assimilation implementation of the model with PDAF. It is considerd as an improved variant of the Lorenz-96 model.
     80 * `lorenz2005c`
     81  * Added in PDAF V2.0, this directory contains the two-scale model Lorenz-2005-III (introduced by Lorenz(2005), there called model variant III) as well as a full data assimilation implementation of the model with PDAF.
    7882
    7983
     
    8185== The Test Suite ==
    8286
    83 The test suite of PDAF is included in the directory `testsuite/`. It contains the following sub-directories:
     87The test suite of PDAF is included in the directory `testsuite/`. It is rather intended for our internal verification tests. It contains the following sub-directories:
    8488
    8589 * `bin/`
     
    9094   * This directory contains scripts to run a series of test runs with the example implementation from `testsuite/src/dummymodel_1D`. In addition example outputs are included in the sub-directories. These outputs can be used to compare your own test runs with existing outputs. (The example outputs in `out.linux_gfortran` are from test runs on a Linux PC using the gfortran compilers both with and without parallelization. The example outputs in `out.cray_xc_hlrn` have been produced using a Cray XC40 Supercomputer with parallelization.)
    9195
    92 == Example Implementations ==
     96== Implementations in the test suite ==
    9397
    9498The following example implementations are included in the directories in `testsuite/src/`:
    9599 * `dummymodel_1D`
    96    * This is the example implementation in which PDAF is fully connected to a model. The model is trivial: At each time step simply the time step size is added to the state vector. We recommend this example as the starting point to look into the online implementation of PDAF.
     100   * This is the example implementation in which PDAF is fully connected to a model. The model is trivial: At each time step simply the time step size is added to the state vector. This example can be used as the starting point for the 'flexible' online implementation variant of PDAF.
    97101 * `dummymodel_1D_si`
    98102   * This directory contains an analogous example implementation to `dummymodel_1D`. This variant, however, uses the simplified interface of PDAF. In this case, predefined names of the user-supplied subroutines are used such that there is no need to specify them in the call to the interface of PDAF. (The interface looks simpler in this case, but the subroutine names are fixed)
     
    100104   * This directory contains an analogous example implementation to `dummymodel_1D`. This variant, however, uses single precision (We recommend to use double precision for numerical computation. However, if a model is implemented in single precision PDAF can be used with this model (starting from Version 1.8 of PDAF))
    101105 * `offline_1D`
    102    * This example shows the usage of PDAF as an offline tool. In the offline configuration one computes manually the ensemble integrations and supplies this information to PDAF through files. For simplicity, this example does not use files, but generates dummy-information in the code itself. This example is the starting point to look into the offline implementation of PDAF.
     106   * This example shows the usage of PDAF as an offline tool. In the offline configuration one computes manually the ensemble integrations and supplies this information to PDAF through files. For simplicity, this example does not use files, but generates dummy-information in the code itself.
    103107
    104108== Compiling test cases and tutorial implementations ==
    105109
    106 To build an example follow the following steps:
    107  1. First, follow steps 1 and 2 described in [#CompilingthePDAFlibrary Compiling the PDAF library] above.
    108  2. Change into a directory of a tutorial example, e.g. `tutorial/online_2D_serialmodel` and execute `make`. This will show the possible targets than can be compiled. In the tutorial implementation for offline-coupled assimilation, `make` will directly start the compilation of the example program.
    109  3. Execute a make operation like `make model_pdaf` (This will build the tutorial model with assimilation).
     110To get started with PDAF we recommend to follow the instructions on [FirstSteps First Steps with PDAF].
    110111
    111  * '''Note''': There are make targets for the compilation of the model itself without data assimilation as well as those for the compilation of the assimilation program. In order to obtain a working assimilation program, one has to define `USE_PDAF` in the preprocessor definition variable `CPP_DEFS` has to be set in the include file from `make.arch`. For example, for most compilers one would use `CPP_DEFS = -DUSE_PDAF`. When `USE_PDAF` is not set, the calls to the PDAF routines is not included in the compiled program.
    112 
    113 For the tutorial implementations, the compilation procedure is also described in the [wiki:PdafTutorial tutorials].