--- MITgcm_contrib/osse/README	2004/05/19 14:42:44	1.2
+++ MITgcm_contrib/osse/README	2004/08/22 18:47:41	1.6
@@ -1,14 +1,94 @@
-May 19, 2004
+last changed June 8, 2004
+
+OBSERVATION SYSTEM SIMULATION EXPERIMENT
+
+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
+
+EnKF: empty
+
+build: handy place to compile MITgcm
+
+code: modifications to MITgcm to run in cyclindrical coordinates.  At
+the time of this writing, it requires checkpoint48 to compile and run.
+
+codemod: modification to MITgcm to run with checkpoint 54.  Not quite
+ready for prime time.
+
+da: location for ensemble members and initialization and input files 
+
+input: initialization and input files for running MITgcm
+
+filter: source and data files to run the data assimilation and Kalman
+filter.
+
+run: empty
+
+utils: assorted Matlab m-files 
+
+
+COMPILING AND TESTING THE MODEL
+
+The following series of commands creates the MITgcm executable.  
+
+From the MITgcm root:
+
+cd verification/osse/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.  Assuming that you compiled the 
+MITgcm executable in the build/ directory, you would run 
+``../build/mitgcmuv >& output.txt''  It is recommended that you copy the
+contents of the directory input/ 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, which creates an executable named ``osse''.  
+
+Before running osse, the initial ensemble needs to be set up by
+running the mkens script in verification/osse/da.  mkens creates the
+directories, symbolically links files necessary to run the model, and
+copies in the initial ensemble files.  osse should be run from the
+directory verification/osse/da/inits since it expects the ensemble
+members to be one directory above.  It also expects to have in its
+working directory the file iobsloc-003.txt, which contains the
+locations of the observations.  This file is located in
+verification/osse/da/inits.
+
 
-Observation System Simulation Experiment
 
-OSSE is a configuration to simulate running an deterministic 
-ensemble Kalman filter on a rotating tank with an ice bucket 
-at the center.  
 
-code/ contains the modifications to MITgcm to run in cyclindrical
-coordinates.  At the time of this writing, it requires 
-checkpoint48 to compile and run.
 
-EnKF/ contains the source and data files to run the Kalman filter.