===========
README FILE
===========

----------------------------------------------------------------------------------------------------------------------------------
------------------------------------------------------- CONTENTS -----------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------

programs                                                           --> source, examples and templates
README                                                             --> this file
results                                                            --> output files with results
texts                                                              --> latex files

----------------------------------------------------------------------------------------------------------------------------------
------------------------------------------------------- FOR PROGRAMS -------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------

(1) CONTENTS

	example0d --> example in 0D
	example2d --> example in 2D
	src       --> Kalman filter modules and several tools
	templates --> templates to apply the package to a model

(2) COMPILE THE CODE

Go to an example directory ( example0d or example2d ) and type:

	make clean --> remove everything
	make       --> compile everything

(3) EXECUTE

The item (2) will generate the object files and the executables. Execute:

	mpirun -np 1 ./example0d.exe         

or

	mpirun -np <number of processors> ./example2d_ekf.exe
	mpirun -np <number of processors> ./example2d_enkf.exe
	mpirun -np <number of processors> ./example2d_rrsqrtkf.exe
	mpirun -np <number of processors> ./example2d_rrsqrtenkf.exe


(4) OUTPUT ( case example0d / case example2d )

truth.txt       --> exact solution
model.txt       --> model solution
obser.txt       --> observations
ekf.txt         --> solution from the extended Kalman filter
rrsqrtkf.txt    --> solution from the reduce rank square root Kalman filter
enkf.txt        --> solution from the ensemble Kalman filter
rrsqrtenkf.txt  --> solution from the reduce rank square root ensemble Kalman filter

(5) PLOTTING ( Matlab required )

Executing the script "graphics.m" in Matlab, we get the following output

	(a) example0d 

	    example0d_values.eps --> comparison between truth, model, observations and assimilation methods

	(b) example2d

	    movie_model_truth.avi      --> movie: relative error (%) of the model with respect to truth 
	    movie_ekf_truth.avi        --> movie: relative error (%) of the extended Kalman filter with respect to truth
	    movie_rrsqrtkf_truth.avi   --> movie: relative error (%) of the reduce rank square root Kalman filter with respect to truth
	    movie_enkf_truth.avi       --> movie: relative error (%) of the ensemble Kalman filter with respect to truth
	    movie_rrsqrtenkf_truth.avi --> movie: relative error (%) of the reduce rank square root ensemble Kalman filter with respect to truth
 	     	    	    
	    example2d_model_truth.eps      --> figure: last frame of movie_model_truth.avi
	    example2d_ekf_truth.eps        --> figure: last frame of movie_ekf_truth.avi
            example2d_rrsqrtkf_truth.eps   --> figure: last frame of movie_rrsqrtkf_truth.avi
	    example2d_enkf_truth.eps       --> figure: last frame of movie_enkf_truth.avi
            example2d_rrsqrtenkf_truth.eps --> figure: last frame of movie_rrsqrtenkf_truth.avi

IMPORTANT: The command movie2avi ( Matlab ) used in "graphics.m" can generate very big AVI files using LINUX, because there are no codecs available in LINUX. At most you will need 2 gb of disk space

----------------------------------------------------------------------------------------------------------------------------------
------------------------------------------------------- FOR TEXTS ----------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------

(1) Go to the "texts" directory and type

        make       --> generates a DVI and PDF of the article and the manual
	make latex --> generates a DVI file of the article and the manual
	make pdf   --> generates a PDF file of the article and the manual
	make clean --> clean everything

----------------------------------------------------------------------------------------------------------------------------------
------------------------------------------------------- CONTACT ------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------

Germán Ariel Torres
Grupo de Análisis Numérico y Computación
Facultad de Matemática, Astronomía y Física
Universidad Nacional de Córdoba
E-mail: torres@famaf.unc.edu.ar

----------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------
