Version 45 (modified by lnerger, 7 weeks ago) (diff)


Lorenz-96 model with PDAF

The implementation of the Lorenz-96 model coupled to PDAF is in the directory models/lorenz96/ of the PDAF package (from PDAF 1.15, before it was located in estsuite/src/lorenz96). 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 different publications in which we studied the behavior of different data assimilation methods.

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

This description focuses on PDAF version 1.15 and later as we have moved the Lorenz-96 model case in version 1.15 to the directory models.

Running the test case

Runnning a data assimilation experiment 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 model with activated coupling to PDAF and runs the data assimilation experiments.

1. Compile and run the forward model without assimilation

First change in the file make.arch/linux_gfortran_openmpi.h the line




to deactivate the coupling to PDAF in the model code. Now build the forward model program with

  cd models/lorenz96
  make lorenz_96 PDAF_ARCH=linux_gfortran_openmpi

You have to ensure that in the machine-specific make include file linux_gfortran_openmpi.h -DUSE_PDAF is not defined for CPP_DEFS (such that calls to PDAF are not active). You can replace linux_gfortran_openmpi by any other make include file from make.arch/, e.g. specify macos_gfortran for compiling on MacOS. The executable is generated in this directory.

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. On MacOS one can install the netcdf library e.g. using Fink or MacPorts. NetCDF is a self-describing binary output format, but here it is not required that you know details about it. Anyway, if you like to look 'into' a NetCDF file, please try to use ncdump FILENAME | less.

To run the forward model use

  ./lorenz_96 -total_steps 10000

This runs the Lorenz-96 model for 10000 time steps and the trajectory is written into a file

2. Generate observations and a covariance matrix

To build the executables for the tool programs use

  cd tools
  make all PDAF_ARCH=linux_gfortran_openmpi

Now run




to generate a file holding observations ( in models/lorenz96/) and a file holding the covariance matrix information ( in models/lorenz96/), which is used to generate an initial ensemble for the data assimilation experiments.

3. Build and run the assimilation program

Now do

  cd ../../../make.arch

and change in the file linux_gfortran_openmpi.h the line


back to


to activate the coupling to PDAF in the model code.

Now compile the Lorenz-96 model with activated coupling to PDAF. First clean the directories for the main driver and the Lorenz-96 model using

  cd ../models/lorenz96
  make clean PDAF_ARCH=linux_gfortran_openmpi

(This removes object files that were compiled without support for PDAF) Then build the executable using

  make pdaf_lorenz_96 PDAF_ARCH=linux_gfortran_openmpi

The program pdaf_lorenz_96 is generated.

To run the assimilation program, do


The script runs 11 experiments with a fixed ensemble size, but different covariance inflations (forgetting factors). The execution can take a few minutes.

4. Plot output from the assimilation experiments

To display the output of the assimilation experiments we provide plotting scripts for Matlab, Octave and (from PDAF 1.13.2) Python. To use them do

cd plotting

The following plot functions are available:

Script Description
plot_example Plot the mean true and estimated RMS errors for the example output files generated with the script tools/ as a function of the forgetting factor
plot_eofs Plot the mean state and the eigenvectors (EOFs) from the file holdig the covariance matrix that is generated with tools/generate_covar.F90.
plot_obs Plot the observations for a specified time step. The observation file is generated using tools/generate_obs.F90.
plot_rms Plot the true and estimated RMS errors over time from an assimilation experiment.
plot_sigma Plot the singular values from the file holdig the covariance matrix that is generated with tools/generate_covar.F90.
plot_state Plot the state from the file holding a true state trajectory ( or the estimated forecast or analysis states from an assimilation experiment.

Except for plot_example all scripts require the specification of the directory and name of the file to be read. Sometimes, there are additional arguments like the time step index. The syntax of the functions is identical for Matlab and Python (except for plot_rms):

Matlab Python Comment
plot_example() plot_example()
plot_eofs(filename, index) plot_eofs(filename, index) index=0 for mean state, index>1 for EOFs
plot_obs(filename, timestep) plot_obs(filename, timestep)
plot_rms(filename [, plot_forecast=1, plot_analysis=1]) plot_rms(filename [, plot_forecast=True, plot_analysis=True]) plot_forecast/plot_analysis are optional and switch on/off a plot
plot_sigma(filename) plot_sigma(filename)
plot_state(filename, timestep [, choice='t']) plot_state(filename, timestep [, choice='t']) choice is optional; options for choice: 't' true (use with truth file; for use with assimilation experiment output files: 'f' forecast, 'a' analysis, 'i' initial

Here filename is the name of the file including its path. In Matlab use 'help' to display the information about required input.

Matlab/Octave plotting examples:
plot_obs('../',100) plots the observation at time step 100
plot_state('../',100,'f') plots the forecast state estimate at the 100th analysis step
plot_rms('../') plots the true and estimated RMS errors over time for the chosen experiment
plot_state('../',1101) plots the true state at model time step 1101 (= analysis step 100)

Python plotting
For Python the scripts are provided by

The module can either be imported, e.g. to use its functions interactively:
>>> import plot_l96
>>> plot_l96.plot_obs('../', 4)

Alternatively the script can be run from the command line, providing the function name and its argument as command line parameters:
./ plot_obs ../ 4
(If this fails you can also try to run the script as python plot_obs ../ 4). To plot only the Analysis RMS error one can use
plot_rms ../ False True

Run options

The implementation for the Lorenz-96 model has a wide range of options. For the full set, we recommend to check the list in the file init_pdaf.F90 in the directory lorenz96. Essentially all of the options can be specified on the command line in the format '-VARIABLE VALUE', where VARIABLE is the name of the variable in the program and VALUE is its value. The experiments in are executed like

./pdaf_lorenz_96 -total_steps 5000 -step_null 1000 -dim_ens 30 \
     -filtertype 6 -forget 0.99 -file_asml

The meaning of the different options is the following:

Variable Description Default value
dim_ens ensemble size 30
file_asml the name of the output file
filtertype Specifies the filter to use; 6 sets the filter ESTKF 1
forget value of the forgetting factor for multiplicative variance inflation 1.0
step_null initial time step of experiment. This specifies the offset of the observations which are generated from a model forward run. A value 1000 avoids the spin-up phase of the model 0
total_steps number of time step in the experiment 5000

Some further options:

Variable Description Default value
delt_obs time interval between observations, i.e. the forecast length 1
dim_lag set the time lag for the smoother (the smoother is active for dim_lag>0) 0
dim_state set state dimension (if changed, the true state trajectory, observations, and covariance matrix file need to be re-generated) 40
dx_obs distance between observations on the grid; let's you specify an incompletely observated state (only used when use_obs_mask=.true.) 1
cradius localization cut-off radius in grid points 5
locweight choose localization weight function, e.g. 4 is the 5th-order polynomial mimicking a Gaussian (see Gaspari and Cohn 1999) 0
model_error a logical variable activating model error noise .false.
model_err_amp amplitude of the model error 0.1
numobs number of observed grid points; the points 1 to numobs are observed (can be combined with dx_obs; only used when use_obs_mask=.true.) dim_state
use_obs_mask whether to use incomplete observations (need to be .true. for any other settings on the observation density to be used) .false.
type_ensinit Choose whether the initial ensemble is sampled using 2nd-order exact smapling ('eof') or using random draws from the foreward trajectory ('rnd'). Note that 'eof' can only be used up to dim_ens=41 (state dimension + 1). 'eof'

The localization is controlled by the variables locweight, cradius, and sradius:

locweight 0 1 2 3 4
function unit weight exponential 5-th order
5-th order
5-th order
regulation - - - regulation using
mean variance
regulation using variance
of single observation point
cradius weight=0 if distance > cradius
sradius no impact weight = exp(-d / sradius) weight = 0 if d >= sradius
weight = f(sradius, distance)

Here, 'regulation' refers to the regulated localization introduced in Nerger, L., Janjić, T., Schröter, J., Hiller, W. (2012). A regulated localization scheme for ensemble-based Kalman filters. Quarterly Journal of the Royal Meteorological Society, 138, 802-812. ​doi:10.1002/qj.945.

For the full set of options, please see init_pdaf.F90 in the lorenz96 directory. There, also the possible settings e.g. for filtertype are described.