--- MITgcm/doc/README	1998/07/08 15:29:22	1.10
+++ MITgcm/doc/README	2005/04/05 20:48:20	1.17
@@ -1,4 +1,52 @@
-$Header: /home/ubuntu/mnt/e9_copy/MITgcm/doc/README,v 1.10 1998/07/08 15:29:22 cnh Exp $
+$Header: /home/ubuntu/mnt/e9_copy/MITgcm/doc/README,v 1.17 2005/04/05 20:48:20 gforget Exp $
+
+================
+===  WARNING ===
+================
+
+
+For MITgcm Users :
+
+This directory (MITgcm/doc) does *NOT* contain the primary user
+documentation for the MITgcm code.  We strongly suggest that you forgo
+the effort of downloading and "building" the documentation in the
+different formats (pdf, html, etc.) and instead read and/or download
+the documentation which is conveniently referenced from the main web
+site at:
+
+  http://mitgcm.org
+
+
+
+For MITgcm Developers:
+
+If you wish to customize or extend the MITgcm code, this directory
+contains a "HOWTO" document that tries to explain:
+
+  + where the code, documentation, and test/verification
+    data sets are arranged within the CVS repository;
+
+  + how to run the verification tests;
+
+  + how to get help from the core developers; and
+
+  + how to best integrate your work with the overall project.
+
+
+The document is available in SGML source within this directory:
+
+  devel_HOWTO.sgml
+
+and in various formats on our web site:
+
+  http://mitgcm.org/dev_docs/devel_HOWTO/
+
+
+
+======================================================================
+===  WARNING :  The following has been superseeded by the on-line  ===
+===             documentation at:  http://mitgcm.org               ===
+======================================================================
 
 
 MITgcmUV Getting Started
@@ -24,10 +72,10 @@
   the steps below:
 
   1. Extract MITgcmUV from the downloadable archive
-     tar -xvf checkpoint12.tar 
+     tar -xvf cNN.tar 
 
   2. Create platform specific make file
-     For example on a Digital UNIX machine the script "genmake.dec" can
+     For example on a Digital UNIX machine the script "genmake" can
      be used as shown below
 
      cd bin
@@ -40,23 +88,10 @@
   4. Compile code
      make
 
-  5. Copy input files
-     cp ../verification/exp2/[a-z]* ../verification/exp2/*bin .
+  5. To run the model with example data see the "README" in each of
+     the example experiments in ../verification/exp*/
+     e.g.  ../verification/exp2/README
   
-  6. Run baseline test case
-     setenv PARALLEL 1
-     dmpirun -np 2 ../exe/mitgcmuv        ( Under Digital UNIX   )
-     mpirun.p4shmem ../exe/mitgcmuv -np 2 ( Under Solaris + mpich)
-                                                      
-
-     This runs a 4 degree global ocean climatological simulation.
-     By default this code is set to use two porcessors splitting
-     the model domain along the equator. Textual output is written
-     to files STDOUT.* and STDERR.* with one file for each process.
-     Model fileds are written to files suffixed .data and .meta
-     These files are written on a per process basis. The .meta
-     file indicates the location and shape of the subdomain in
-     each .data file.
 
 o Running
 
@@ -73,17 +108,40 @@
 
   - Serial execution
 
+  - Parallel execution. MPI
+    mPx, nPy
+    dmpirun
+
   - Parallel execution. Threads
     nSx, nSy
     setenv PARALLEL n
     nTx=2, nTy=2
 
-  - Parallel execution. MPI
-    mPx, nPy
-    dmpirun
-
   - Parallel execution. Hybrid
 
+o Cutomising the code
+
+  Model structure
+  ===============
+  The "numerical" model is contained within a execution 
+  environment support wrapper. This wrapper is designed 
+  to provide a general framework for grid-point models.
+  MITgcmUV is a specific numerical model that uses the
+  framework.
+   Under this structure the model is split into 
+  execution environment support code and conventional
+  numerical model code. The execution environment
+  support code is held under the "eesupp" directory.
+  The grid point model code is held under the 
+  "model" directory. 
+   Code execution actually starts in the eesupp 
+  routines and not in the model routines. For this
+  reason the top level main.F is in the eesupp/src
+  directory. End-users should not need to worry about
+  this level. The top-level routine for the numerical
+  part of the code is in model/src/the_model_main.F.
+
+
 o References
   Web sites - HP
   for doc     Digital