= Lorenz-96 model with PDAF = 

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

The implementation of the Loren-96 model coupled to PDAF is in the directory `testsuite/src/lorenz96` of the PDAF package.
Provided is a full implementation of PDAF with the nonlinear Lorenz96 model (E. N. Lorenz (1996) Predictability - a problem partly 
solved. Proceedings Seminar on Predictability, ECMWF, READING, UK) providing various filter and smoother methods. We used this implementation for the different publications in which we studies the behavior of different data assimilation methods.

Next to the implementation of Lorenz-96 with PDAF, the test case provides tool programs and scripts that
allow to run a test case and to display the outputs.


== Running the test case  ==

Runnning a data assimilation experimnet with the Lorenz-96 model is a two step process: First one runs the model without PDAF to generate a file holding the trajectory of a forward run. Then one generates files with observations and a covariance matrix for the initialization of the initial ensemble. In the second step, one compiles the Lorenz-96 with activated coupling to PDAF and runs the experiments. 

=== 1. Compile and run the forward model without assimilation ===

First change in the file `make.arch/linux_gfortran.h` the line
{{{
CPP_DEFS = -DUSE_PDAF
}}}
to 
{{{
CPP_DEFS = #-DUSE_PDAF
}}}
to deactivate the coupling to PDAF in the model code. Now build the forward model program with
{{{
  cd testsuite/src
  make lorenz_96 PDAF_ARCH=linux_gfortran
}}}
in the directory `testsuite/src/` of the PDAF package. You have to ensure
that in the machine-specific make include file `linux_gfortran.h` `-DUSE_PDAF` is not defined
for CPP_DEFS (such that calls to PDAF are not active). The executable
is generated in `testsuite/bin/`.

'''Note''': The implementation uses the NetCDF library for file outputs. If the compilation above fails, please ensure the netcdf-library ist installed. On computers running Linux, it is usually available as a package of the operating system. 

To run the forward model use
{{{
  cd ../bin
  ./lorenz_96 -total_steps 10000
}}}
This runs Lorenz-96 model for 10000 time steps and the trajectory is written into a file `state.nc`. 

=== 2. Generate observations and a covariance matrix ===

To build the executables for the tool programs use
{{{
  cd ../src/lorenz96/tools
  make all PDAF_ARCH=linux_gfortran
}}}

Now run
{{{
  ./generate_obs
}}}
and
{{{
  ./generate_covar
}}}
to generate a file holding observations (`obs.nc` in testsuite/bin/) and
a file holding the covariance matrix information (`covar.nc` in
testsuite/bin/), which is used to generate an initial ensemble for
the data assimilation experiments.


=== 3. Build and run the assimilation program ===

Change in the `make.arch/linux_gfortran.h` the line
{{{
CPP_DEFS = #-DUSE_PDAF
}}}
back to 
{{{
CPP_DEFS = -DUSE_PDAF
}}}
to activate the coupling to PDAF in the model code. 

Now compile the Lorenz96 model with activated
PDAF. First clean the directories for the main driver and the lorenz96
 model using
{{{
  cd ../../
  make cleandriver PDAF_ARCH=linux_gfortran
  make cleanlorenz_96 PDAF_ARCH=linux_gfortran
}}}
(This removes object files that were compiled without support for PDAF)
Then build the executable using
{{{
  make pdaf_lorenz_96 PDAF_ARCH=linux_gfortran
}}} 
The program `pdaf_lorenz_96` is generated in testsuite/bin.


To run the assimilation program, do
{{{
  cd ../bin
  ../src/lorenz96/tools/runasml.sh 
}}}
The script runsasml.sh runs 11 experiments with a fixed ensemble size, but
different covariance inflations (forgetting factors). The execution can 
take about 2 minutes.

=== 4. Plot output from the assimilation experiments ===

To display the output of the assimilation experiments we provide several plotting scripts for Matlab and Octave. To use them do
{{{
cd ../src/lorenz96/plotting/
}}}
and see the file README there for a description of the available plotting scripts. 

For example,
  plot_example.m 
plots the true and estimated mean RMS errors as a function of the
forgetting factor. For the usage of the other functions, use 'help'
in Matlab.