--- MITgcm_contrib/osse/README	2004/05/19 14:08:37	1.1
+++ MITgcm_contrib/osse/README	2004/06/08 17:37:45	1.4
@@ -1,12 +1,73 @@
-May 19, 2004
+last changed June 8, 2004
 
-OSSE is a configuration to simulate running an deterministic 
-ensemble Kalman filter on a rotating tank with an ice bucket 
-at the center.  
+OBSERVATION SYSTEM SIMULATION EXPERIMENT
 
-code/ contains the modifications to MITgcm to run in cyclindrical
-coordinates.  At the time of this writing, it requires 
-checkpoint48 to compile and run.
+OSSE is an MITgcm configuration to simulate data assimilation with a
+deterministic ensemble Kalman filter and a model of a rotating tank of
+water with an ice bucket at the center.
+
+INSTALLATION 
+
+At the time of this writing, the OSSE requires MITgcm checkpoint48 to
+compile and run.  MITgcm can be obtained from
+<http://mitgcm.org/source_code.html>.  If downloading from the CVS
+server, use the command
+
+cvs co -r 'checkpoint48' MITgcm
+
+in order to specify the correct version.  Read the instructions on the
+the webpage before trying to use the CVS server.
+
+The OSSE directory tree can be obtained from the MITgcm CVS repository
+with the command
+
+cvs co MITgcm_contrib/osse
+
+The code and its revision history can be browsed at 
+
+<http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/osse/>
+
+A good place to put the osse directory tree is in MITgcm/verification,
+where examples and test examples of MITgcm configurations are kept.
+
+CONTENTS
+
+code: modifications to MITgcm to run in cyclindrical coordinates.  At
+the time of this writing, it requires checkpoint48 to compile and run.
+
+input: initialization and input files for MITgcm
+
+filter: source and data files to run the data assimilation and Kalman
+filter.
+
+utils: assorted Matlab m-files 
+
+EnKF: empty
+
+run: empty
+
+
+COMPILING AND RUNNING THE MODEL
+
+The following series of commands creates the MITgcm executable.  
+
+From the MITgcm root:
+
+cd verification/osse
+mkdir build   # directory name is arbitrary  
+cd build
+../../../tools/genmake -mods=../code  # creates makefile
+make depend       # contructs Fortran code from model codebase
+make              # makes executable mitgcmuv
+
+Try a test run, while redirecting the standard output to a file.  The
+input directory contains files that should be present in the working
+directory when you run mitgcmuv.  It is recommended that you copy the
+input contents to a different directory for running -- mitgcmuv does
+not change them, but they can be lost in the multitudes of output
+files.
+
+The data assimilation code is made by typing ``make'' in the filter
+directory.
 
-EnKF/ contains the source and data files to run the Kalman filter.