Annotation of /MITgcm/doc/README

$Header$

================
===  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
========================

o Introduction

  This note is a guide to using the MIT General Circulation Model Ultra Verstaile
  implementation, MITgmcUV. MITgcmUV is a Fortran code that implements the 
  algorithm described in Marshall et. al. 1997, Hill, Adcroft, ...
   The MITgcmUV implementation is designed to work efficiently on all classes
  of computer platforms. It can be used in both a single processor mode
  and a parallel processor mode. Parallel processing can be either multi-threaded
  shared memory such as that found on CRAY T90 machines or it can be multi-process
  distributed memory. A set of "execution enviroment" support routines are 
  used to allow the same numerical code to run on top of a single-process, multi-threaded
  or distributed multi-process configuration.

o Installing
  To setup the model on a particular computer the code tree must be created
  and appropriate compile and run scripts set up. For some platforms
  the necessary scripts are included in the release - in this case follow
  the steps below:

  1. Extract MITgcmUV from the downloadable archive
     tar -xvf cNN.tar 

  2. Create platform specific make file
     For example on a Digital UNIX machine the script "genmake" can
     be used as shown below

     cd bin
     ../tools/genmake 
     cp Makefile.alpha Makefile                  ( On Alpha machine)

  3. Now create header file dependency entries
     make depend

  4. Compile code
     make

  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
  

o Running

  - Input and output files

    Required files
    ==============
    The model is configured to look for two files with fixed names.
    These files are called
     "eedata" and "data".
    The file eedata contains "execution environment" data. At present
    this consists of a specification of the number of threads to
    use in X and Y under multithreaded execution.

  - Serial execution

  - Parallel execution. MPI
    mPx, nPy
    dmpirun

  - Parallel execution. Threads
    nSx, nSy
    setenv PARALLEL n
    nTx=2, nTy=2

  - 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
              SGI
              Sun
              Linux threads
              CRAY multitasking
              PPT notes
1	edhill	1.16	$Header$
2
3			================
4			=== WARNING ===
5			================
6
7
8			For MITgcm Users :
9
10			This directory (MITgcm/doc) does NOT contain the primary user
11			documentation for the MITgcm code. We strongly suggest that you forgo
12			the effort of downloading and "building" the documentation in the
13			different formats (pdf, html, etc.) and instead read and/or download
14			the documentation which is conveniently referenced from the main web
15			site at:
16
17			http://mitgcm.org
18
19
20
21			For MITgcm Developers:
22
23			If you wish to customize or extend the MITgcm code, this directory
24			contains a "HOWTO" document that tries to explain:
25
26			+ where the code, documentation, and test/verification
27			data sets are arranged within the CVS repository;
28
29			+ how to run the verification tests;
30
31			+ how to get help from the core developers; and
32
33			+ how to best integrate your work with the overall project.
34
35
36			The document is available in SGML source within this directory:
37
38			devel_HOWTO.sgml
39
40			and in various formats on our web site:
41
42			http://mitgcm.org/dev_docs/devel_HOWTO/
43
44
45
46
47			======================================================================
48			=== WARNING : The following has been superseeded by the on-line ===
49			=== documentation at: http://mitgcm.org ===
50			======================================================================
51	adcroft	1.8
52	cnh	1.2
53	cnh	1.1	MITgcmUV Getting Started
54			========================
55	cnh	1.3
56			o Introduction
57	cnh	1.4
58	cnh	1.7	This note is a guide to using the MIT General Circulation Model Ultra Verstaile
59			implementation, MITgmcUV. MITgcmUV is a Fortran code that implements the
60			algorithm described in Marshall et. al. 1997, Hill, Adcroft, ...
61			The MITgcmUV implementation is designed to work efficiently on all classes
62			of computer platforms. It can be used in both a single processor mode
63			and a parallel processor mode. Parallel processing can be either multi-threaded
64			shared memory such as that found on CRAY T90 machines or it can be multi-process
65			distributed memory. A set of "execution enviroment" support routines are
66			used to allow the same numerical code to run on top of a single-process, multi-threaded
67			or distributed multi-process configuration.
68
69			o Installing
70			To setup the model on a particular computer the code tree must be created
71			and appropriate compile and run scripts set up. For some platforms
72			the necessary scripts are included in the release - in this case follow
73			the steps below:
74
75			1. Extract MITgcmUV from the downloadable archive
76	cnh	1.14	tar -xvf cNN.tar
77	cnh	1.7
78			2. Create platform specific make file
79	adcroft	1.15	For example on a Digital UNIX machine the script "genmake" can
80	cnh	1.7	be used as shown below
81
82	cnh	1.9	cd bin
83			../tools/genmake
84	cnh	1.10	cp Makefile.alpha Makefile ( On Alpha machine)
85	cnh	1.7
86			3. Now create header file dependency entries
87			make depend
88
89			4. Compile code
90			make
91	adcroft	1.8
92	adcroft	1.15	5. To run the model with example data see the "README" in each of
93			the example experiments in ../verification/exp*/
94			e.g. ../verification/exp2/README
95	cnh	1.7
96	cnh	1.5
97			o Running
98	cnh	1.7
99			- Input and output files
100
101			Required files
102			==============
103			The model is configured to look for two files with fixed names.
104			These files are called
105			"eedata" and "data".
106			The file eedata contains "execution environment" data. At present
107			this consists of a specification of the number of threads to
108			use in X and Y under multithreaded execution.
109	cnh	1.5
110			- Serial execution
111
112	adcroft	1.15	- Parallel execution. MPI
113			mPx, nPy
114			dmpirun
115
116	cnh	1.5	- Parallel execution. Threads
117			nSx, nSy
118			setenv PARALLEL n
119			nTx=2, nTy=2
120
121			- Parallel execution. Hybrid
122	cnh	1.11
123			o Cutomising the code
124
125			Model structure
126			===============
127			The "numerical" model is contained within a execution
128			environment support wrapper. This wrapper is designed
129			to provide a general framework for grid-point models.
130			MITgcmUV is a specific numerical model that uses the
131			framework.
132			Under this structure the model is split into
133			execution environment support code and conventional
134			numerical model code. The execution environment
135			support code is held under the "eesupp" directory.
136			The grid point model code is held under the
137			"model" directory.
138			Code execution actually starts in the eesupp
139			routines and not in the model routines. For this
140			reason the top level main.F is in the eesupp/src
141			directory. End-users should not need to worry about
142			this level. The top-level routine for the numerical
143			part of the code is in model/src/the_model_main.F.
144
145	cnh	1.3
146			o References
147	cnh	1.6	Web sites - HP
148			for doc Digital
149			SGI
150			Sun
151			Linux threads
152			CRAY multitasking
153	cnh	1.7	PPT notes