Here is a simple user guide to setting up a coupled model using the current tool set. The current example sets up a cube-sphere atmosphere, a lat-lon land, a tripolar ocean, and creates all the exchange grids necessary between these.

• Unpack the tarball. The directory where the output arrives is the $rootdir which is set in the various setup scripts. In future, this will be distributed under CVS on our GForge site.
• The script compile_and_save_to_tools compiles all the tools and saves them in $rootdir/bin. The environment variable NPES is used to decide whether or not to compile the MPI-enabled versions of the some of the tools. setenv NPES 0 (or any number less than 2) if you want to disable these. The Makefiles will attempt to link with -lnetcdf assuming some "standard location": you may need to edit the Makefiles in each $rootdir/tools/* directory if the location of libnetcdf.a is "non-standard".
• The script test_all.csh runs all of the tests. Again, you can disable the parallel tests by setting NPES to a number less than 2; if NPES is 2 or more, the parallel tools will be invoked under mpirun -np $NPES. Output will be written to $outdir set in the script, normally $rootdir/data/output. The output can be checked against the reference results in $rootdir/data/output-ref. (For an intelligent comparison of netCDF files, use the tool nccmp).

test_all.csh runs the following grid creation sequence, currently in use at GFDL.

• make a vertical grid. (The make_vgrid isn't really used below, is it?)

make_vgrid --nbnds 3 --bnds 10,200,1000 --nz 10,20

• make the atmosphere grid: this is a 48x48x6 cube-sphere grid. The first step, make_hgrid makes 6 individual grid tiles horizontal_grid.tile[1-6].nc using the gnomonic projection, then make_solo_mosaic writes the mosaic linkages in C48_mosaic.nc.

make_hgrid --grid_type gnomonic_ed --nlon 96
make_solo_mosaic --num_tiles 6 --dir $PWD --mosaic C48_mosaic

• make the land grid: this is a regular lat-lon grid, 144x90 (288x180 supergrid), known as N45. Even though this is a single tile, we still make a mosaic file N45_mosaic.nc: the mosaic is where the periodicity in X (i.e a boundary of the tile with itself) is recorded.

make_hgrid --grid_type regular_lonlat_grid --nxbnd 2 --nybnd 2 \
  --xbnd 0,360 --ybnd -90,90 --nlon 288 --nlat 180 --output N45_grid

make_solo_mosaic --num_tiles 1 --dir $PWD --mosaic N45_mosaic \
  --tile_file N45_grid.nc --periodx 360

• make the ocean grid: this is a tripolar grid, 360x180. Even though this is a single tile, we still make a mosaic file tripolar_mosaic.nc. (Balaji: where is the join_lat? where is the periodicity and fold information in the make_solo_mosaic call?)

make_hgrid --grid_type tripolar_grid --nxbnd 2 --nybnd 2 --xbnd -280,80 \
  --ybnd -90,90 --nlon 360 --nlat 180 --output tripolar_grid

make_solo_mosaic --num_tiles 1 --dir $PWD \
  --mosaic tripolar_mosaic--tile_file tripolar_grid

• Interpolate the topography file $rootdir/data/input/OCCAM_p5degree.nc onto the ocean grid tripolar_mosaic.nc. The resulting topography file tripolar_topog.nc will be used to generate a consistent land-sea mask across all model grids. (Note that the atmosphere interpolates its topography by independent means, not shown here).

make_topog --mosaic $outdir/tripolar_mosaic.nc \
  --topog_file $indir/OCCAM_p5degree.nc --topog_field TOPO \
  --scale_factor -1 --output tripolar_topog.nc

• Make the top-level mosaic that links all the model grid mosaics by generating exchange grids between pairs of grid tiles, including area fractions where the land-sea mask intersects model grid cells. The output includes a top-level mosaic file mosaic.nc and a number of exchange grid files, such as C48_mosaic_tile2Xtripolar_mosaic_tile1.nc.

make_coupler_mosaic --atmos_mosaic $outdir/C48_mosaic.nc \
 --land_mosaic  $outdir/N45_mosaic.nc \
 --ocean_mosaic $outdir/tripolar_mosaic.nc \
 --ocean_topog  $outdir/tripolar_topog.nc