This is a brief guide to a set of command-line tools related to the Gridspec. The tools cover two sets of operations related to the gridspec: first, a set of tools that cover all steps of creation of a gridspec, and second, a tool for regridding from one mosaic to another using gridspec representations of the source and target grids.

The tools include:

• make_hgrid: specify a horizontal grid.
• make_vgrid: specify a vertical grid.
• make_solo_mosaic: make a mosaic file out of a list of grid tile files.
• make_topog: specify topography and a land-sea mask.
• make_coupler_mosaic: create exchange grids between input mosaics.
• fregrid: interpolate input data fields from source to target gridspec.

For each of these files, simply typing the command name will generate a more-or-less complete documentation of command-line options. The documentation below merely lists a few illustrative examples for each of the tools.

Please check back for updates to this page, which will include parallel versions of all the tools, as well as visual examples. See the complete grid creation example for downloads and a walkthrough of the current package.

A typical grid creation sequence for FMS-based models would involve creating individual gridspecs for atmosphere, land and ocean (the tools make_hgrid, make_vgrid, make_solo_mosaic); generate a topography and land-sea mask for the ocean grid (make_topog); and finally, generate exchange grids for interpolation between atmosphere, land and ocean grids.

make_hgrid

make_hgrid make horizontal grid tiles for various grid types. The grid_type can be one of a controlled vocabulary of grid tyoes that includes spectral_grid, regular_lonlat_grid, tripolar_grid, conformal_cubic_grid, etc. Alternatively a text file or netCDF specifying vertices of a supergrid can be supplied. For simple cartesian grids, locations and spacings can be directly input on the command line.

make_hgrid --grid_type regular_lonlat_grid --nxbnd 2 --nybnd 2
        --xbnd 0,30 --ybnd 50,60  --nlon 60 --nlat 2

generates a 60x20 supergrid covering the region in lon-lat space specified in xbnd,ybnd.

make_hgrid --grid_type conformal_cubic_grid --nlon 60 --nratio 2

generates a 60x60x6 cubed-sphere grid using the conformal projection. The nratio argument is specific to this grid type and specifies the intended refinement of the grid. (For ths grid type, one cannot specify the supergrid without knowing the target refinement and resolution). 5 grid tile files will be generated.

make_vgrid

make_vgrid is a tool that is called for each column to define a vertical supergrid, User specifies nbnds vertical regions, in each of which the grid has constant spacing. User specifies cell boundaries bnds for each region, which is equally divided into nz cells. (Thus nz has count one less than bnds. Since the specification is a supergrid, the total cell count is twice the sum of the nz array.

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

creates 20 supergrid cells evenly spanning the range 10--200 metres, and 40 supergrid cells spanning 200--1000 metres.

(Balaji: might be more intuitive if the user directly specified the supergrid cell count --nx 20,40 and allowed the user to decide which cells of the supergrid are used by the model grid, as is done in the horizontal?)

make_solo_mosaic

make_solo_mosaic creates a mosaic file out of a directory containing a set of grid tiles files.

make_solo_mosaic --num_tiles ntiles --dir directory --tile_file gridtile

will look for a set of ntiles tile gridspec netCDF files named gridtile#.nc in directory and make a mosaic file mosaic.nc that specifies their linkages following the mosaic specification.

make_topog

make_topog generates topography for the mosaic. This can include both idealized and realistic topographies. Various filtering options and land-sea mask specification options are provided.

make_topog --mosaic mosaic.nc --topog_type realistic \
   --topog_file /archive/fms/mom4/input_data/OCCAM_p5degree.nc
   --topog_field TOPO --scale_factor -1

generates topography for the gridspec in mosaic.nc using the variable TOPO in the specified topog_file. The scale factor in the examples flips the sign in the topography field to convert heights to depths.

make_coupler_mosaic

Given mosaic specifications for mosaics representing atmosphere, ocean and land, as well as a land-sea mask and topography specification, make_coupler_mosaic generates all the required exchange grids needed for conservative interpolation between them.

make_coupler_mosaic --atmos_mosaic atm_mosaic.nc --ocean_mosaic ocean_mosaic.nc
      --ocean_topog ocean_topog.nc [--land_mosaic land_mosaic.nc]
      [--sea_level sea_level]  [--interp_method 1] [--mosaic_name mosaic_name]

This computes a top-level mosaic between the specified atmosphere, land and ocean grids. The file ocean_topog.nc is used as a source for topography information with the land-sea mask defined at sea_level metre isopleth in the topography. interp_method is used to specify first- or second-order conservative interpolation. The result is written to mosaic_name.nc.

fregrid

fregrid was a tool written to be used by the FRE runtime environment for offline regridding of model output onto a set of standard grids used by post-processing and analysis software. A dataset is translated from an input gridspec to an output gridspec using a variety of interpolation methods, including bilinear and first- and second-order conservative methods. The underlying regridding engine is shared between online tools such as horiz_interp and offline tools such as fregrid.

fregrid --input_mosaic input_mosaic.nc --output_mosaic output_mosaic.nc
   --input_file input_file --field_name temp,salt

interpolates the temp and salt fields in input_file to the grid specified by output_mosaic.nc.

fregrid --input_mosaic input_mosaic.nc -- nlon M --nlat N
   --input_file input_file --field_name temp,salt

is an even simpler example: the output grid is a simple uniform lon-lat grid of resolution MxN.

For downloads and a complete example, visit the grid creation page.