A Brief Guide to Using the MS-EVA Package

1. Download of the package

   Set up a directory. Let us call it $MS-EVA.
   Download the package into $MS-EVA.
   You will need the GNU "make" to install the package.


2. Preparation of the data set
	* Arakawa-B grid. (cf. liang's thesis on p. 171)
	* flat z-levels.  (cf. liang's thesis on p. 172)
	* prepare the file drho_dz.dat in $MS-EVA/profile. 
	  The data are stored as
		[z, dz, rho_bar, s, dlogsz].
	  The stationary density rho_bar is obtained by averaging 
	  all the available density profiles in the dataset (at all times).
	  See LR3, sec. 4, for an explanation of these parameters)
		
	* number of time steps of sequence should be 
	  a power of 2, i.e., nm = 2^{j2}, with j2 the
	  upper bound of the sub-mesoscale window.


3. Modification of the package to fit in your data format

Make the following modifications if you do not have a model output in 
netcdf format.
  * Enter $MS-EVA/work. In Makefile.mwt and  Makefile.eva,
    eliminate all the file extract.f and its dependencies

  * Enter $MS-EVA/MWT. 
    In file pre-process.f, replace all the xtr_mod calls with 
    another subroutine (also named xtr_mod.f) to input 
    rho, u, v, w, p from your own model results. Be sure to
    subtract the mean rho profile from rho.
    Note in saving computing resource, the MS-EVA package performs
    computations only for the designated level kp. So all these
    variables have an array shape (im, jm, nm), where im, jm, and
    nm are the sizes of dimension x, dimension y, and dimension time,
    respectively.
  

4. Customization

Enter $MS-EVA/work. You will find two header files:
	config.h,
	param_flt.h,
three makefiles:
	Makefile.mwt,
	Makefile.eva,
	Makefile.flt,
three input files:
	mwt.in
	mseva.in
	hflt.in
and a data file:
	instants.dat.

* Change these makefiles if necessary. 
  If you want to put the executables in $MS-EVA/work, 
  and keep the directory structure as it is, then you
  do not need to change anything.

* Customize config.h.
  - You will need to pick your own im, jm, km, according to 
    your configuration, and the number of time steps nm.

  - choose the window parameters
	j0, j1, and j2=log2(nm)
    see Liang and Robinson (DAO 1) for meanings of j0, j1, and j2.

  - set the number of time locations (nloc0) for your MS-EVA output.
    Currently the output is numbered day by day, but actually you
    can choose time interval as you like. The nloc0 time steps
    are stored in file instants.dat.
    In the current version, nloc0 should be smaller than 100.
    (This should be more than enough for diagnostic purposes.)

* Customize param_flt.h 
  (nx1, ny1, nz1) are the same as the (im,jm,km) in config.h.
  set jmax so that 2^{jmax/2} is closest to nx1 and ny1.

* Specify the nloc0 time steps and store it in instants.dat.
  Make sure there are nloc0 directories in 
	Data-eva
	Data-mwt
	Data-flt
  named in a way as t??, with ?? indicating the time steps.


5. Creating executables

Type:
	gmake -f Makefile.flt-mwt2d utility
	gmake -f Makefile.flt-mwt2d
	gmake -f Makefile.flt-mwt2d clean
	gmake -f Makefile.mwt
	gmake -f Makefile.mwt clean
	gmake -f Makefile.eva
	gmake -f Makefile.eva clean
to generate the executables mwt, mseva, and hflt.



6. Running the MS-EVA 

   Edit hflt.in, mwt.in, and mseva.in, and run the executables
   in the following order:
		a)   mwt > mwt.in
		b)   mseva > mseva.in
		c)   hflt_mwt2d > hflt_mwt2d.in	
		     (or hflt> hflt.in)

   The outputs will be stored in the subdirectories of 
   Data-mwt, Data-eva, and Data-flt, respectively. In general,
   hundreds of thousands of files could be generated. So be careful
   that you have enough space for the storage. If only the energetics
   are of concern, you will need only the data in Data-flt.
   The intermediate data files from mwt and mseva may be removed 
   after the experiment is completed.


7. Viewgraphs 
   There are some matlab scripts available in $MS-EVA/Matlab. 
   The plots are supposed to be re-directed into $MS-EVA/work/plots.
   But these scripts are not portable as yet. You may visualize the 
   results easily on your own. Basically a data file is named in a
   convention close to what it appears in the paper. A single 
   matlab "load" command will have it loaded in.

