PUBLIC INTERFACE ~ PUBLIC DATA ~ PUBLIC ROUTINES ~ NAMELIST ~ DIAGNOSTIC FIELDS ~ ERROR MESSAGES ~ REFERENCES ~ NOTES

Module hgrid_mod

Contact: Z. Liang
Reviewers: S. M. Griffies
Change History: WebCVS Log


OVERVIEW

hgrid_mod Generate horizontal grid. The horizontal grid can be conventional lon-lat spherical grid or a reprojected rotated tripolar grid (R. Murray, "Explicit generation of orthogonal grids for ocean models", 1996, J.Comp.Phys., v. 126, p. 251-273.).

There are four subgrids, labeled T (for tracer), C (corner of T), N (north of T) and E (east of T). The following schematic describes the grid cell notation.

                          Ni,j
               +----------+-----------+Ci,j
               |                      |     
               |                      |
               |                      |
               +          +Ti,j       +Ei,j
               |                      |
               |                      |
               +----------+-----------+
The grid_spec file would contains all of the following information on each subgrid. The following example is for T subgrid. Repeated for E, C, and N subgrids.

   x_T, y_T           = Geographic location of T-cell center
   x_vert_T, y_vert_T = Geographic location of T-cell vertices(each cell has 4 vertices)
   area_T             = area of T-cell
   angle_T            = Angle clockwise between logical and geographic east of T-cell
   ds_00_02_T         = Length of western face of T-cell
   ds_20_22_T         = Length of eastern face of T-cell
   ds_02_22_T         = Length of northern face of T-cell
   ds_00_20_T         = Length of southern face of T-cell
   ds_00_01_T         = Distance from southwest corner to western face center of T-cell
   ds_01_02_T         = Distance from northwest corner to western face center of T-cell
   ds_02_12_T         = Distance from northwest corner to northern face center of T-cell
   ds_12_22_T         = Distance from northeast corner to northern face center of T-cell
   ds_21_22_T         = Distance from northeast corner to eastern face center of T-cell
   ds_20_21_T         = Distance from southeast corner to eastern face center of T-cell
   ds_10_20_T         = Distance from southeast corner to southern face center of T-cell
   ds_00_10_T         = Distance from southwest corner to southern face center of T-cell
   ds_01_11_T         = Distance from center to western face of T-cell
   ds_11_12_T         = Distance from center to northern face of T-cell
   ds_11_21_T         = Distance from center to eastern face of T-cell
   ds_10_11_T         = Distance from center to southern face of T-cell
   ds_01_21_T         = width of T-cell
   ds_10_12_T         = height of T-cell

  Distances between points are described in the following schematics (for T-cell).
   


               +<----ds_02_12_T---->+<----ds_12_22_T---->+
               ^                    ^                    ^
               |                    |                    |
               |                    |                    |
          ds_01_02_T           ds_11_12_T           ds_21_22_T
               |                    |                    |
               |                    |                    |
               v                    v                    v
               +<----ds_01_11_T---->+<----ds_11_21_T---->+
               ^                    ^                    ^
               |                    |                    |
               |                    |                    |
          ds_00_01_T           ds_10_11_T           ds_20_21_T
               |                    |                    |
               |                    |                    |
               v                    v                    v
               +<----ds_00_10_T---->+<----ds_10_20_T---->+



               <-------------- ds_02_22_T---------------->
             ^ +--------------------+--------------------+ ^
             | |                    ^                    | |
             | |                    |                    | |
             | |                    |                    | |
             | |                    |                    | |
             | |                    |                    | |
     ds_00_02_T|<-------------------+--ds_01_21_T------->| ds_20_22_T              
             | |                    |                    | |
             | |               ds_10_12_T                | |
             | |                    |                    | |
             | |                    |                    | |
             | |                    |                    | | 
             | |                    v                    | |
             v +--------------------+--------------------+ v
               <-------------- ds_00_20_T---------------->


   The other three subgrids (E, N, C subgrids) have similiar name but replacing T.

 Axis specifications involve specifying the number of regions for varying
 resolution, the bondaries of said regions and the nominal resolution in 
 the respective regions.  

 For instance, for longitude axis specification:

        dx_lon(1) = 4                         dx_lon(2) = 6
 |<----|----|----|----|----|----|------|------|------|------|------|------>|
 |                              |                                          |
 x_lon(1)                    x_lon(2)                                   x_lon(3)

 Grid cells are constructed such that
 
 dxt(i) = 0.5*(dxu(i-1)+dxu(i))


OTHER MODULES USED

        mpp_mod
mpp_io_mod
mpp_domains_mod
fms_mod
constants_mod
axis_utils_mod
grids_type_mod
grids_util_mod

PUBLIC INTERFACE

hgrid_init:
Initialization routine.
generate_hgrid:
Generate horizontal grid.
write_hgrid_data:
write the Hgrid data to netcdf file
write_hgrid_meta:
Write out horizontal grid meta data.
hgrid_end:
Destruction routine.


PUBLIC DATA

None.


PUBLIC ROUTINES

  1. hgrid_init

    call hgrid_init ( )
    DESCRIPTION
    Read namelist, write out version and namelist informaiton, generate longitude and latitude resolution.


  2. generate_hgrid

    call generate_hgrid (Hgrid)
    DESCRIPTION
    Define geographical locations of center and vertices of T, C, E, N-cell and also calculate the area, orientation, cell size, face lengths, half face lengths and center to face size of each T, E, C, N cell.


    INPUT/OUTPUT
    Hgrid    A derived-type variable that contains horizontal grid information.
       [hgrid_data_type]

  3. write_hgrid_data

    call write_hgrid_data (unit,Hgrid)
    DESCRIPTION


    INPUT
    unit    The unit corresponding the output netcdf file. Always is returned by mpp_open.
       [integer]
    Hgrid    A derived-type variable that contains horizontal grid information.
       [hgrid_data_type]

  4. write_hgrid_meta

    call write_hgrid_meta (unit, Hgrid, axis_x, axis_y)
    DESCRIPTION


    INPUT
    unit    The unit corresponding the output netcdf file. Always is returned by mpp_open.
       [integer]
    Hgrid    A derived-type variable that contains horizontal grid information.
       [hgrid_data_type]

    OUTPUT
    axis_x, axis_y    axis of T-cell center
       [type(axistype), optional]

  5. hgrid_end

    call hgrid_end ( Hgrid )
    DESCRIPTION
    Deallocates memory used by "hgrid_data_type" variables.


    INPUT/OUTPUT
    Hgrid    A derived-type variable that contains horizontal grid information.
       [hgrid_data_type]


NAMELIST

&hgrid_nml

nxlons
number of zonal regions for varying resolution
[integer]
nylats
number of latitude regions for varying resolution
[integer]
x_lon
boundaries for defining zonal regions of varying resolution. When tripolar_grid is .true., x_lon also defines the longitude of the two new poles. lon_start = x_lon(1) and lon_end = x_lon(nxlons) are longitude of the two new poles. In this case, the program will ignore the value x_lon(2:nxlons-1) and set grid resolution to dx_lon(1). When tripolar_grid is true, you need to be careful about your choice of x_lon, because there might be ocean at the grid singularity. The recommended choice of x_lon is x_lon = -280,80, this will put the singularity over land.
[real, dimension(nxlons), units: degrees]
dx_lon
nominal resolution of zonal regions
[real, dimension(nxlons), units: degrees]
cyclic
True if grid is connected in i-direction
[logical]
y_lat
boundaries for defining meridional regions of varying resolution
[real, dimension(nylats), units: degrees]
dy_lat
nominal resolution of meridional regions
[real, dimension(nxlons), units: degrees]
tripolar_grid
convert portion of spherical grid north of lat_join to a bipolar rotated grid
[logical]
channel_grid
When true, it will generate channel grid. Default value is false. When channel_grid is true, tripolar_grid should be false.
[logical]
square_grid
latitudinal grid spacing matches convergence of meridians
[logical]
extend_square_grid
extend square grid to poles
[logical]
lat_join
requested latitude for joining spherical and rotated bipolar grid
[real]
read_my_grid
read ASCII grid information for supplying user-defined grids.
[logical]
my_grid_file
Name of ASCII user grid file
[character(len=128)]
debug
control standard output.
[logical]


DATA SETS

None.


ERROR MESSAGES

None.


top