Contents of /MITgcm/doc/README

$Header: /u/gcmpack/models/MITgcmUV/doc/README,v 1.11 1998/07/10 18:48:48 cnh Exp $


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 checkpoint12.tar 

  2. Create platform specific make file
     For example on a Digital UNIX machine the script "genmake.dec" 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. Copy input files
     cp ../verification/exp2/[a-z]* ../verification/exp2/*bin .
  
  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

  - 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. 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
              SGI
              Sun
              Linux threads
              CRAY multitasking
              PPT notes
1	$Header: /u/gcmpack/models/MITgcmUV/doc/README,v 1.11 1998/07/10 18:48:48 cnh Exp $
2
3
4
5	MITgcmUV Getting Started
6	========================
7
8	o Introduction
9
10	This note is a guide to using the MIT General Circulation Model Ultra Verstaile
11	implementation, MITgmcUV. MITgcmUV is a Fortran code that implements the
12	algorithm described in Marshall et. al. 1997, Hill, Adcroft, ...
13	The MITgcmUV implementation is designed to work efficiently on all classes
14	of computer platforms. It can be used in both a single processor mode
15	and a parallel processor mode. Parallel processing can be either multi-threaded
16	shared memory such as that found on CRAY T90 machines or it can be multi-process
17	distributed memory. A set of "execution enviroment" support routines are
18	used to allow the same numerical code to run on top of a single-process, multi-threaded
19	or distributed multi-process configuration.
20
21	o Installing
22	To setup the model on a particular computer the code tree must be created
23	and appropriate compile and run scripts set up. For some platforms
24	the necessary scripts are included in the release - in this case follow
25	the steps below:
26
27	1. Extract MITgcmUV from the downloadable archive
28	tar -xvf checkpoint12.tar
29
30	2. Create platform specific make file
31	For example on a Digital UNIX machine the script "genmake.dec" can
32	be used as shown below
33
34	cd bin
35	../tools/genmake
36	cp Makefile.alpha Makefile ( On Alpha machine)
37
38	3. Now create header file dependency entries
39	make depend
40
41	4. Compile code
42	make
43
44	5. Copy input files
45	cp ../verification/exp2/[a-z]* ../verification/exp2/*bin .
46
47	6. Run baseline test case
48	setenv PARALLEL 1
49	dmpirun -np 2 ../exe/mitgcmuv ( Under Digital UNIX )
50	mpirun.p4shmem ../exe/mitgcmuv -np 2 ( Under Solaris + mpich)
51
52
53	This runs a 4 degree global ocean climatological simulation.
54	By default this code is set to use two porcessors splitting
55	the model domain along the equator. Textual output is written
56	to files STDOUT.* and STDERR.* with one file for each process.
57	Model fileds are written to files suffixed .data and .meta
58	These files are written on a per process basis. The .meta
59	file indicates the location and shape of the subdomain in
60	each .data file.
61
62	o Running
63
64	- Input and output files
65
66	Required files
67	==============
68	The model is configured to look for two files with fixed names.
69	These files are called
70	"eedata" and "data".
71	The file eedata contains "execution environment" data. At present
72	this consists of a specification of the number of threads to
73	use in X and Y under multithreaded execution.
74
75	- Serial execution
76
77	- Parallel execution. Threads
78	nSx, nSy
79	setenv PARALLEL n
80	nTx=2, nTy=2
81
82	- Parallel execution. MPI
83	mPx, nPy
84	dmpirun
85
86	- Parallel execution. Hybrid
87
88	o Cutomising the code
89
90	Model structure
91	===============
92	The "numerical" model is contained within a execution
93	environment support wrapper. This wrapper is designed
94	to provide a general framework for grid-point models.
95	MITgcmUV is a specific numerical model that uses the
96	framework.
97	Under this structure the model is split into
98	execution environment support code and conventional
99	numerical model code. The execution environment
100	support code is held under the "eesupp" directory.
101	The grid point model code is held under the
102	"model" directory.
103	Code execution actually starts in the eesupp
104	routines and not in the model routines. For this
105	reason the top level main.F is in the eesupp/src
106	directory. End-users should not need to worry about
107	this level. The top-level routine for the numerical
108	part of the code is in model/src/the_model_main.F.
109
110
111	o References
112	Web sites - HP
113	for doc Digital
114	SGI
115	Sun
116	Linux threads
117	CRAY multitasking
118	PPT notes