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

Module topography_mod

Contact:  Bruce Wyman
Reviewers: 
Change History: WebCVS Log

OVERVIEW

Routines for creating land surface topography fields and land-water masks for latitude-longitude grids.

This module generates realistic mountains and land-water masks on a specified latitude-longitude grid by interpolating from the 1/6 degree Navy mean topography and percent water data sets. The fields that can be generated are mean and standard deviation of topography within the specified grid boxes; and land-ocean (or water) mask and land-ocean (or water) fractional area.

The interpolation scheme conserves the area-weighted average of the input data by using module horiz_interp.

The interfaces get_gaussian_topog and gaussian_topog_init are documented in idealized_topog_mod.

OTHER MODULES USED

idealized_topog_mod
  horiz_interp_mod
           fms_mod
        fms_io_mod

PUBLIC INTERFACE

get_topog_mean:
Returns a "realistic" mean surface height field.
get_topog_stdev:
Returns a standard deviation of higher resolution topography with the given model grid boxes.
get_ocean_frac:
Returns fractional area covered by ocean in a grid box.
get_ocean_mask:
Returns a land-ocean mask in a grid box.
get_water_frac:
Returns fractional area covered by water.
get_water_mask:
Returns a land-water mask in a grid box.

PUBLIC DATA

None.

PUBLIC ROUTINES

  1. get_topog_mean

     
get_topog_mean
    DESCRIPTION
    Returns realistic mountains on a latitude-longtude grid. The returned field is the mean topography for the given grid boxes. Computed using a conserving area-weighted interpolation. The current input data set is the 1/6 degree Navy mean topography.


    INPUT
    blon    The longitude (in radians) at grid box boundaries.
       [real, dimension(:)]
    blat    The latitude (in radians) at grid box boundaries.
       [real, dimension(:)]

    OUTPUT
    zmean    The mean surface height (meters). The size of this field must be size(blon)-1 by size(blat)-1.
       [real, dimension(:,:)]
    get_topog_mean    A logical value of TRUE is returned if the surface height field was successfully created. A value of FALSE may be returned if the input topography data set was not readable.
       [logical]

  2. get_topog_stdev

     
get_topog_stdev
    DESCRIPTION
    Returns the standard deviation of the "finer" input topography data set, currently the Navy 1/6 degree mean topography data, within the boundaries of the given input grid.


    INPUT
    blon    The longitude (in radians) at grid box boundaries.
       [real, dimension(:)]
    blat    The latitude (in radians) at grid box boundaries.
       [real, dimension(:)]

    OUTPUT
    stdev    The standard deviation of surface height (in meters) within given input model grid boxes. The size of this field must be size(blon)-1 by size(blat)-1.
       [real, dimension(:,:)]
    get_topog_stdev    A logical value of TRUE is returned if the output field was successfully created. A value of FALSE may be returned if the input topography data set was not readable.
       [logical]

  3. get_ocean_frac

     
get_ocean_frac
    DESCRIPTION
    Returns fractional area covered by ocean in the given model grid boxes.


    INPUT
    blon    The longitude (in radians) at grid box boundaries.
       [real, dimension(:)]
    blat    The latitude (in radians) at grid box boundaries.
       [real, dimension(:)]

    OUTPUT
    ocean_frac    The fractional amount (0 to 1) of ocean in a grid box. The size of this field must be size(blon)-1 by size(blat)-1.
       [real, dimension(:,:)]
    get_ocean_frac    A logical value of TRUE is returned if the output field was successfully created. A value of FALSE may be returned if the Navy 1/6 degree percent water data set was not readable.
       [logical]

  4. get_ocean_mask

     
get_ocean_mask
    DESCRIPTION
    Returns a land-ocean mask in the given model grid boxes.


    INPUT
    blon    The longitude (in radians) at grid box boundaries.
       [real, dimension(:)]
    blat    The latitude (in radians) at grid box boundaries.
       [real, dimension(:)]

    OUTPUT
    ocean_frac    The fractional amount (0 to 1) of ocean in a grid box. The size of this field must be size(blon)-1 by size(blat)-1.
       [real, dimension(:,:)]
    get_ocean_mask    A logical value of TRUE is returned if the output field was successfully created. A value of FALSE may be returned if the Navy 1/6 degree percent water data set was not readable.
       [logical]

  5. get_water_frac

     
get_water_frac
    DESCRIPTION
    Returns the percent of water in a grid box.


    INPUT
    blon    The longitude (in radians) at grid box boundaries.
       [real, dimension(:)]
    blat    The latitude (in radians) at grid box boundaries.
       [real, dimension(:)]

    OUTPUT
    water_frac    The fractional amount (0 to 1) of water in a grid box. The size of this field must be size(blon)-1 by size(blat)-1.
       [real, dimension(:,:)]
    get_water_frac    A logical value of TRUE is returned if the output field was successfully created. A value of FALSE may be returned if the Navy 1/6 degree percent water data set was not readable.
       [logical]

  6. get_water_mask

     
get_water_mask
    DESCRIPTION
    Returns a land-water mask in the given model grid boxes.


    INPUT
    blon    The longitude (in radians) at grid box boundaries.
       [real, dimension(:)]
    blat    The latitude (in radians) at grid box boundaries.
       [real, dimension(:)]

    OUTPUT
    water_mask    A binary mask for water (true) or land (false). The size of this field must be size(blon)-1 by size(blat)-1.
       [real, dimension(:,:)]
    get_water_mask    A logical value of TRUE is returned if the output field was successfully created. A value of FALSE may be returned if the Navy 1/6 degree percent water data set was not readable.
       [logical]

NAMELIST

&topography_nml

topog_file
Name of topography file.
[character, default: DATA/navy_topography.data]
water_file
Name of percent water file.
[character, default: DATA/navy_pctwater.data]

DATA SETS

This module uses the 1/6 degree U.S. Navy mean topography and percent water data sets.

These data sets have been re-formatted to separate 32-bit IEEE files. The names of these files is specified by the namelist input.

The format for both files is as follows: 
     record = 1    nlon, nlat
     record = 2    blon, blat
     record = 3    data
where: 
     nlon, nlat = The number of longitude and latitude points
                  in the horizontal grid.  For the 1/6 degree
                  data sets this is 2160 x 1080. [integer]
     blon, blat = The longitude and latitude grid box boundaries in degrees.
                     [real :: blon(nlon+1), blat(nlat+1)]

     data       = The topography or percent water data.
                    [real :: data(nlon,nlat)]

ERROR MESSAGES

FATAL in get_topog_mean
shape(zmean) is not equal to (/size(blon)-1,size(blat)-1/))
Check the input grid size and output field size.
FATAL in get_water_frac
shape(water_frac) is not equal to (/size(blon)-1,size(blat)-1/))
Check the input grid size and output field size.

REFERENCES

None.

COMPILER SPECIFICS

None.

PRECOMPILER OPTIONS

None.

LOADER OPTIONS

None.

TEST PROGRAM

To run this program you will need the topography and percent water data sets and use the following namelist (in file input.nml).

&idealized_topog_nml height = 5000., 3000., 3000., 3000., olon = 90., 255., 285., 0., olat = 45., 45., -15., -90., wlon = 15., 10., 5., 180., wlat = 15., 25., 25., 20., /

program test

test program for topography and gaussian_topog modules 
  use topography_mod
  implicit none
  
  integer, parameter :: nlon=24, nlat=18
  real :: x(nlon), y(nlat), xb(nlon+1), yb(nlat+1), z(nlon,nlat)
  real :: hpi, rtd
  integer :: i,j
  logical :: a
  
 gaussian mountain parameters
  real, parameter :: ht=4000.
  real, parameter :: x0=90., y0=45. ! origin in degrees
  real, parameter :: xw=15., yw=15. ! half-width in degees
  real, parameter :: xr=30., yr= 0. ! ridge-width in degrees
  
 create lat/lon grid in radians
    hpi = acos(0.0)
    rtd = 90./hpi ! rad to deg
    do i=1,nlon
      xb(i) = 4.*hpi*real(i-1)/real(nlon)
    enddo
      xb(nlon+1) = xb(1)+4.*hpi
      yb(1) = -hpi
    do j=2,nlat
      yb(j) = yb(j-1) + 2.*hpi/real(nlat)
    enddo
      yb(nlat+1) = hpi
 mid-point of grid boxes
    x(1:nlon) = 0.5*(xb(1:nlon)+xb(2:nlon+1))
    y(1:nlat) = 0.5*(yb(1:nlat)+yb(2:nlat+1))
 test topography_mod routines
    a = get_topog_mean(xb,yb,z)
    call printz ('get_topog_mean')
  
    a = get_water_frac(xb,yb,z)
    z = z*100. ! in percent
    call printz ('get_water_frac')
  
    a = get_ocean_frac(xb,yb,z)
    z = z*100. ! in percent
    call printz ('get_ocean_frac')
  
 test idealized_topog_mod routines
    a = .true.
    z = get_gaussian_topog(x,y,ht,x0,y0,xw,yw,xr,yr)
    call printz ('get_gaussian_topog')
  
    call gaussian_topog_init (x,y,z)
    call printz ('gaussian_topog_init')
  
  contains
  
 simple printout of topog/water array
    subroutine printz (lab)
    character(len=*), intent(in) :: lab
     if (a) then
        print '(/a)', trim(lab)
     else
        print '(/a)', 'no data available: '//trim(lab)
        return
     endif
 print full grid
        print '(3x,25i5)', (nint(x(i)*rtd),i=1,nlon)
      do j=nlat,1,-1
        print '(i3,25i5)', nint(y(j)*rtd), (nint(z(i,j)),i=1,nlon)
      enddo
    end subroutine printz
  
  end program test

KNOWN BUGS

Water mask produces some possible erroneous water points along the coast of Antarctic (at about 90W).


NOTES

None.

FUTURE PLANS

Use of netcdf data sets.

Incorporate other topography and ocean data sets.


top