= The Software Release = 


[[PageOutline(2-3,Contents of this page)]]


== Getting the code package ==

see the [https://pdaf.awi.de/register/index.php Download page] for information on downloading PDAF and for registering to PDAF's maillist. 

== 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.
 * `modelbindings/`
  * This directory contains links to the PDAF model coupling codes for real simulation models 
 * `models/`
  * This directory contains fully implemented toy models for assimilation experiments with PDAF 
 * `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 tutorial implementations in `tutorial/`.)
 * `tests/`
  * This directory contains implementations of PDAF for detailed tests. For more details see the section on [#TheTestSuite the test suite] 
 * `tutorial/`
  * This directory contains example implementations of the analysis step in the online and offline modes of PDAF
 * `external/`
  * From PDAF V2.0, this directory contains external libraries, in particular solver methods used in 3D-Var

== Compiling the PDAF library ==

The library file of PDAF can be compiled on its own or in connection with an example implementations from `tutorial/` or `models/`. 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.

The compilation itself is described on the [wiki:CompilingPdaf page on compiling PDAF].


== Tutorial Implementations ==

The directory `tutorial/` contains different example implementations as well as inputs file used to run the examples. They are the recommended starting point to study the online and offline implementations of PDAF.
 * `offline_2D_serial`
  * This directory contains the example implementation of the offline mode without parallelization
 * `offline_2D_parallel`
  * This directory contains a parallel example implementation of the offline mode
 * `online_2D_serialmodel`
  * This directory contains an example implementation of the online mode with a serial model
 * `online_2D_serialmodel_2fields`
  * This directory contains an example implementation of the online mode with a serial model showing the implementation for 2 model fields
 * `online_2D_parallelmodel`
  * This directory contains an example implementation of the online model with a parallelized model

Please see the [wiki:PdafTutorial Tutorial Page] for the tutorials describing these implementations.


== Models ==

The following example implementations are included in the sub-directories in `models/`:
 * **lorenz63**
  * This directory contains the Lorenz-63 model with a full data assimilation implementation with PDAF. Because of its small size, this model an be, e.g., used with the Particle Filter. Compiling and running this model is described in detail on the page on the [wiki:Lorenz_63_model Lorenz-63 model].
 * **lorenz96**
  * This directory contains the Lorenz-96 model with a full data assimilation implementation with PDAF. This model can be configured to have a sufficiently large state dimension to test ensemble filter algorithms like the ESTKF filter with localization. (We have used this model in different published studies.) Compiling and running this model is described in detail on the page on the [wiki:Lorenz_96_model Lorenz-96 model].
 * **lorenz2005b**
  * This directory contains the Lorenz-2005 model variant II (introduced by Lorenz, 2005) with a full data assimilation implementation with PDAF. The model is considered as an improved variant of the Lorenz-96 model. 
 * **lorenz2005c**
  * This directory contains the two-scale model Lorenz-2005-III (introduced by Lorenz, 2005), there called model variant III) with a full data assimilation implementation of the model with PDAF.



== The Test Suite ==

The directory `tests/` contains implemenations for detailed testing of PDAF. The implmentations base on the tutorial cases, but include the full set of options. It is rather intended for our internal verification tests. One can run tests by executing `runtests_online.sh` or `runtests_offline.sh`. For checking with reference outputs, Python scripts are used.

There is also a script `runtests.sh` in the directory `tutorial/`, which runs analogously.

== Compiling test cases and tutorial implementations ==

To get started with PDAF we recommend to follow the instructions on [FirstSteps First Steps with PDAF].