EMPIRE DA  v1.9.1
Data assimilation codes using EMPIRE communication
 All Classes Files Functions Variables Pages
EMPIRE Data Assimilation Documentation
empire_diagram.svg
Author
Philip A. Browne p.browne@reading.ac.uk
Date
Time-stamp: <2016-12-08 11:28:35 pbrowne>

Contributors

EMPIRE Methods

For a list of methods implemented in EMPIRE, please click here: methods

Downloading

For standalone downloads of the code, please visit https://bitbucket.org/pbrowne/empire-data-assimilation/downloads#tag-downloads, click on "Tags" and download the version of your choosing.

For the most up-to-date versions of the code, they are hosted on www.bitbucket.org and can be obtained with the following commands:

1 git clone https://pbrowne@bitbucket.org/pbrowne/empire-data-assimilation.git

To upgrade to the latest versions of the codes, use the following command:

1 git pull https://pbrowne@bitbucket.org/pbrowne/empire-data-assimilation.git
Copyright
These codes are distributed under the GNU GPL v3 License. See LICENSE.txt.

Compiling

Compilation of the source code

The Makefile must be edited for the specific compiler setup. In the main directory you will find the file Makefile.in.

Edit the variables as follows:

  • FC The fortran compiler

This has been tested with gfortran 4.8.2, crayftn 8.2.6 and ifort 14.0.1.106

  • FCOPTS The options for the fortran compiler
  • LIB_LIST The libraries to be called. Note this must include BLAS and LAPACK
  • MODFLAG The flag to specify where module files should be placed by the fortran complier. Examples are
    • gfortran: -J
    • ifort: -module
    • crayftn: -em -J
    • pgfortran: -module

To compile the source code, simply then type the command

1 make

If successful, the following executables are created in the bin/ folder:

To remove the object and executable files if compilation fails for some reason, run the following:

1 make clean

Compilation of the documentation

Documentation of the code is automatically generated using Doxygen, dot and pdflatex.

All of these packages must be installed for the following to work.

1 make docs

This will make an html webpage for the code, the mainpage for which is located in doc/html/index.html.

A latex version of the documentation will be built to the file doc/latex/refman.pdf.

To simply make the html version of the documentation (if pdflatex is not available) then use the command

1 make doc_html

Customising for specific models

This is where the science and all the effort should happen!!

First, the communication version that one wishes to use should be selected. This is done by setting the parameter comm_version in comm_version.f90 . This will define how the state vector is passed between empire and the model and how it is distributed over MPI processes. See Communication Methods for more details.

The file model_specific.f90 should be editted for the specific model which you wish to use. This contains a number of subroutines which need to be adapted for the model and the observation network. We list these subsequently.

  • configure_model This is called early in the code and can be used to read in any data from files before subsequently using them in the below operations.
  • reconfigure_model This is called after each observation timestep. If the observation dimension changes it should be updated here, along with the number of model timesteps until the next observation
  • h This is the observation operator
  • ht This is the transpose of the observation operator
  • r This is the observation error covariance matrix \(R\)
  • rhalf This is the square root of the observation error covariance matrix \(R^{\frac{1}{2}}\)
  • solve_r This is a linear solve with the observation error covariance matrix, i.e. given \(b\), find \(x\) such that \(Rx=b\) or indeed, \(x = R^{-1}b\)
  • solve_rhalf This is a linear solve with the square root of the observation error covariance matrix, i.e. given \(b\), find \(x\) such that \(R^{\frac{1}{2}}x=b\) or indeed, \(x = R^{-\frac{1}{2}}b\)
  • q This is the model error covariance matrix \(Q\)
  • qhalf This is the square root model error covariance matrix \(Q^{\frac{1}{2}}\)
  • solve_hqht_plus_r This is a linear solve with the matrix \((HQH^T+R)\)
  • dist_st_ob This specifies the distance between a an element of the state vector and an element of the observation vector
  • bhalf This is the square root of the background error covariance matrix \(B^{\frac{1}{2}}\)
  • get_observation_data This subroutine must return the observation data at, or subsequently to, the given timestep. This routine only needs to be editted if you wish to use your own observations. It is set up to work automatically with pseudo-observations for running twin experiments.

Not all of these subroutines will be required for each filtering method you wish to use, so it may be advantageous to only implement the necessary ones.

Testing

You can test your user supplied routines by running the test codes found in the folder bin/.

These are by no means full-proof ways of ensuring that you have implemented things correctly, but should at least check what you have done for logical consistency.

For example, they will test if \( R^{-1} Ry = y\), and if \( Q^{\frac{1}{2}}Q^{\frac{1}{2}}x = Qx\) for various different vectors \(x, y\).

Linking to your model using EMPIRE

Full instructions on how to put the EMPIRE MPI commands into a new model can be found at www.met.reading.ac.uk/~darc/empire.

Running

For example, to run N_MDL copies of the model with N_DA copies of empire, then the following are possible:

1 mpirun -np N_MDL model_executable : -np N_DA empire
1 aprun -n N_MDL -N N_MDL model_executable : -n N_DA -N N_DA empire

The empire executable is controlled by the namelist data file empire.nml. As such, this file should be put in the directory where empire is executed.

Examples

In the directory examples there is currently one example of how to use EMPIRE, specifically with the Lorenz 1996 model. In the directory you will find an example model_specific.f90 file setup for that model, along with a file instructions.txt which will lead you step by step through how to run a twin experiment.

Bug Reports and Functionality Requests

While the code is not too large, you may email me the issue or request here.

However there is a webpage set up for this:

https://bitbucket.org/pbrowne/empire-data-assimilation/issues