PUBLIC INTERFACE ~ PUBLIC ROUTINES

## Module diag_grid_mod

Contact: Seth Underwood
Reviewers:
Change History: WebCVS Log

#### OVERVIEW

`diag_grid_mod` is a set of procedures to work with the model's global grid to allow regional output.

`diag_grid_mod` contains useful utilities for dealing with, mostly, regional output for grids other than the standard lat/lon grid. This module contains three public procedures `diag_grid_init`, which is shared globably in the `diag_manager_mod`, `diag_grid_end` which will free up memory used during the register field calls, and `get_local_indexes`. The `send_global_grid` procedure is called by the model that creates the global grid. `send_global_grid` needs to be called before any fields are registered that will output only regions. `get_local_indexes` is to be called by the `diag_manager_mod` to discover the global indexes defining a subregion on the tile.
Change Log

September 2009
  - Single point region in Cubed Sphere
  - Single tile regions in the cubed sphere

#### OTHER MODULES USED

      constants_mod
            fms_mod
            mpp_mod
    mpp_domains_mod

#### PUBLIC INTERFACE

diag_grid_init:
  Send the global grid to the `diag_manager_mod` for regional output.
diag_grid_end:
  Unallocate the diag_global_grid variable.
get_local_indexes:
  Find the local start and local end indexes on the local PE for regional output.
get_local_indexes2:
  Find the indices of the nearest grid point of the a-grid to the specified (lon,lat) location on the local PE. if desired point not within domain of local PE, return (0,0) as the indices.
gCirDistance:
  Find the distance, along the geodesic, between two points.

#### PUBLIC ROUTINES

1. #### diag_grid_init

       SUBROUTINE diag_grid_init (domain, glo_lat, glo_lon, aglo_lat, aglo_lon)

   DESCRIPTION
     In order for the diag_manager to do regional output for grids other than the standard lat/lon grid, the `diag_manager_mod` needs to know the the latitude and longitude values for the entire global grid. This procedure is the mechanism the models will use to share their grid with the diagnostic manager.
     This procedure needs to be called after the grid is created, and before the first call to register the fields.
   INPUT

     `domain` | The domain to which the grid data corresponds. [INTEGER]
     `glo_lat` | The latitude information for the grid tile. [REAL, DIMENSION(:,:)]
     `glo_lon` | The longitude information for the grid tile. [REAL, DIMENSION(:,:)]
     `aglo_lat` | The latitude information for the a-grid tile. [REAL, DIMENSION(:,:)]
     `aglo_lon` | The longitude information for the a-grid tile. [REAL, DIMENSION(:,:)]

2. #### diag_grid_end

       SUBROUTINE diag_grid_end ()

   DESCRIPTION
     The `diag_global_grid` variable is only needed during the register field calls, and then only if there are fields requestion regional output. Once all the register fields calls are complete (before the first `send_data` call this procedure can be called to free up memory.

3. #### get_local_indexes

       SUBROUTINE get_local_indexes (latStart, latEnd, lonStart, lonEnd, istart, iend, jstart, jend)

   DESCRIPTION
     Given a defined region, find the local indexes on the local PE surrounding the region.
   INPUT

     `latStart` | The minimum latitude value defining the region. This value must be less than latEnd, and be in the range [-90,90] [REAL]
     `latEnd` | The maximum latitude value defining the region. This value must be greater than latStart, and be in the range [-90,90] [REAL]
     `lonStart` | The western most longitude value defining the region. Possible ranges are either [-180,180] or [0,360]. [REAL]
     `lonEnd` | The eastern most longitude value defining the region. Possible ranges are either [-180,180] or [0,360]. [REAL]

   OUTPUT

     `istart` | The local start index on the local PE in the 'i' direction. [INTEGER]
     `iend` | The local end index on the local PE in the 'i' direction. [INTEGER]
     `jstart` | The local start index on the local PE in the 'j' direction. [INTEGER]
     `jend` | The local end index on the local PE in the 'j' direction. [INTEGER]

4. #### get_local_indexes2

       SUBROUTINE get_local_indexes2 (lat, lon, iindex, jindex)

   DESCRIPTION
     Given a specified location, find the nearest a-grid indices on the local PE.
   INPUT

     `lat` | The requested latitude. This value must be in the range [-90,90] [REAL]
     `lon` | The requested longitude. Possible ranges are either [-180,180] or [0,360]. [REAL]

   OUTPUT

     `iindex` | The local index on the local PE in the 'i' direction. [INTEGER]
     `jindex` | The local index on the local PE in the 'j' direction. [INTEGER]

5. #### gCirDistance

       PURE ELEMENTAL REAL FUNCTION gCirDistance (lat1, lon1, lat2, lon2)

   DESCRIPTION
     `aCirDistance` will find the distance, along the geodesic, between two points defined by the (lat,lon) position of each point.
   INPUT

     `lat1` | Latitude of the first point [REAL]
     `lon1` | Longitude of the first point [REAL]
     `lat2` | Latitude of the second point [REAL]
     `lon2` | Longitude of the second point [REAL]

#### FUTURE PLANS

- Multi-tile regional output in the cubed sphere.
- Single grid in the tri-polar grid.
- Multi-tile regional output in the tri-polar grid.
- Regional output using array masking. This should allow regional output to work on any current or future grid.

top