This directory contains a tar file of sources for the MITgcm JMC l_c
ocean code (mitgcm_interop_sources.tgz) and a summary of code that was 
added, deleted or changed to fit JMC l_c within ESMF (code-changes.txt).

The tar file in this directory contains sources for a standalone run
of the MITgcm JMC l_c ocean code used in the GFLD B-grid Atmosphere
with MITgcm and NCAR CAM with MITgcm interoperability experiments.
The preconfigured build and run scripts are set to use the MITgcm cluster
compute nodes by default. Alternate builds can be selected from build.sh
(see step 3 below) by modifying the COMP_PROF setting.

An account on the MITgcm cluster can be requested from

 http://mitgcm.org/projects/MITGCM_CLUSTER/get_an_account.htm

Full details of how to use the MITgcm cluster can be found at
 
 http://mitgcm.org/projects/MITGCM_CLUSTER

a quick start summary is given below

To compile and run code on the MITgcm cluster

 1 - Log in to the cluster front-end (cg01.csail.mit.edu)
 2 - request a set of compute nodes e.g.
     $ qsub -I -l nodes=4
 3 - change to a scratch directory e.g.
     $ cd /s01/USER_NAME/mile-i-testing
 4 - download the code e.g.
     $ wget http://mitgcm.org/projects/ESMF/mile-I/mitgcm_interop/mitgcm_interop_sources.tgz
 5 - untar e.g
     tar -xzvf mitgcm_interop_sources.tgz
 6 - cd verification/global_ocean.128x60x15
 7 - ./build.sh
 8 - ./build.sh
 9 - ./run_mitgcm_cluster.sh

 This will compile and run the example on two processes. To use a different 
number of processes options are changed in "build.sh" and 
"run_mitgcm_cluster.sh".

Source layout
=============

The source tree in "mitgcm_interop_sources.tgz" contains sudirectories for the
numerical MITgcm code. These are called model/, pkg/, eesupp/. These sources 
are built into a library as part of the ./build.sh process in steps 7 and 8
above. This library is then linked with ESMF interface code (as part of steps
7 and 8 above) and with the ESMF library. The default setup in the download
links with ESMF 1_0_4. 
The ESMF interface code can be found in sub-directories under the directory 
 verification/global_ocean.128x60x15/esmf_top.
The sub-directory utils/ contains convenience functions for interfacing with 
ESMF. The file mitgcm_org_ocn_esmf_driver.F in the ocn_driver/ sub-directory 
contains ESMF initialize, run and finalize driver routines that call 
MITgcm numerical code. The file mitgcm_org_ocn_esmf_driver.F includes code
that maps MITgcm internal fields to and from ESMF import and export
states. The import and export state id strings used are defined in
ocn_driver/ in the files mitgcm_org_ocn_esmf_exports.F and
mitgcm_org_ocn_esmf_imports.F Several top-level ESMF application drivers are 
included in sub-directories under verification/global_ocean.128x60x15/esmf_top/.
The file main.F in the sub-directory ocn_only_app/ holds the application driver
for a stand-alonce run of MITgcm l_c ocean.

Inputs
======

 The input parameters for MITgcm are described in detail under the documentation
at http://mitgcm.org. The inputs for this experiment are in the sub-directory
verification/global_ocean.128x60x15/input. The parameters "nTimeSteps",
"startTime", "deltaTClock" and "endTime" control the time integration.
Other parameters control a range of numerical and I/O options.

Outputs
=======

 The example executed with "run_mitgcm_cluster.sh" runs in the subdirectory
verification/global_ocean.128x60x15/testrun/ocn.1. On completion it writes
binary fileds called cplFldtave.* that contain time averages of the
export state fields. These can be examined using Matlab. The script
utils/matlab/rdmds can be used to load these files into Matlab. Plotting
MITgcm output files with Matlab is described in the documentation at
http://mitgcm.org.