Changes between Initial Version and Version 1 of SoftwarePackage

Timestamp:

Aug 10, 2011, 5:24:20 PM (13 years ago)

Author:

lnerger

Comment:

--

SoftwarePackage

@@ +1 @@
+= The Software package = 
+
+
+[[PageOutline(2-3,Contents of this page)]]
+
+
+== Getting the code package ==
+
+{{{ 
+#!html 
+A package archive with the source code of PDAF and its test suite can be downloaded after registration from the <a class="wiki" href="/register/index.php">download page</a>.
+}}}
+
+== Structure of the package ==
+
+The software package contains the following directories:
+
+ * `lib/`
+  * This is the directory in which the library object file of PDAF is created upon compilation.
+ * `make.arch/`
+  * This directory contains machine-specific include files for the Makefile.
+ * `nullmpi/`
+  * 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.
+ * `src/`
+  * This directory contains the source code of the core routines of PDAF. In addition, a Makefile is included to compile the PDAF library file.
+ * `templates/`
+  * This directory contains stubs for all user-supplied routines required by the different filters. These files can be used for the own implementation (alternatively one can base on the routines of the example implementations in `testsuite/`.)
+ * `testsuite/`
+  * This directory contains the test suite of PDAF including example implementations. For more details see the section on [#TheTestSuite the test suite] 
+
+== Compiling the PDAF library ==
+
+The library file of PDAF can be compiled on its own or in connection with an example implementation from `testsuite/'. Here, we describe the stand-alone compilation. In order to build the library file, you need a Fortran90 compiler and 'make'. In addition, the libraries 'BLAS' and 'LAPACK' are required.
+
+Compiling the PDAF library is conduction in the following steps:
+ 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.
+
+ * '''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.
+
+
+ 2. Set the environment variable $PDAF_ARCH 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.
+
+ 3. Execute `cd src` and type 'make' at the prompt. This will compile the sources. The library file is generated in the directory `lib/`.
+
+
+== The Test Suite ==
+
+The test suite of PDAF is included in the directory `testsuite/`. It contains the following sub-directories:
+
+ * `bin/`
+   * This directory will contain the executable program when an example case is compiled
+ * `src/`
+   * This directory contains the [#ExampleImplementations example implementations]. In addition the Makefile to compile the examples is included.
+ * `tests_dummy1D/`
+   * 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_ifort` are from test runs on a Linux PC using Intel compilers without parallelization. The example outputs in `out.ibm_xlf_power6` have been produced using an IBM Blade Center with Power6 processors. These examples are with and without parallelization.)
+
+== Example Implementations ==
+
+The following example implementations are included in the directories in `testsuite/src/`:
+ * dummymodel_1D
+   * This is here 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.
+ * offline_1D
+   * 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.
+ * lorenz63
+  * This directory currently only contains the forward Lorenz-63 model. It can be used as a training test case for an implementation using PDAF.
+ * lorenz96
+  * This directory currently only contains the forward Lorenz-96 model. 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 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 test cases ==
+
+To build an example follow the following steps:
+ 1. First, follow steps 1 and 2 described in [#CompilingthePDAFlibraryCompilingthePDAFlibrary] above.
+ 2. In `testsuite/src` execute `make`. This will show the possible targets than can be compiled.
+ 3. Execute a make operation like `make dummymodel` (This will build the forward model of the case `dummymodel_1D`).
+
+ * '''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 gfortran 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.