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

Module rivers_mod

Contact:  Christopher Milly
Reviewers:  Elena Shevliakova ,  Sergey Malyshev
Change History: WebCVS Log

OVERVIEW

Module containing processes relating to the rivers.

Allocates river data and sets river destination indices. Includes tests for checking whether points are coastal. Updates the state of the rivers and runoff on the fast and slow time-scales. River boundary data is updated on the slow time-scale. Given the local runoff field, calculates the local portion of discharge.

Initializes diagnostics and sends the diagnostic field output for the slow time-scale river fields and static fields to the diagnostic manager.

OTHER MODULES USED

   time_manager_mod
   diag_manager_mod
            mpp_mod
    mpp_domains_mod
         mpp_io_mod
            fms_mod
      constants_mod
     land_types_mod
land_properties_mod
       numerics_mod

PUBLIC INTERFACE

rivers_init:
Initializes rivers data instance.
rivers_end:
Deallocates rivers data instance.
init_routing:
Sets river destination indices.
is_coastal:
Tests whether a point is a coastal point.
init_rivers_diag:
Initializes diagnostics for rivers module.
update_rivers_fast:
Fast time-scale update of state.
calc_discharge:
Given local runoff field, calculates local portion of discharge.
update_rivers_slow:
Slow time-scale update of state.
update_rivers_bnd_slow:
Updates the river boundary data on the slow time-scale.
diag_slow:
Diagnostic field output of the slow time-scale variables.
diag_static:
Static diagnostic fields output.
print_error_mesg:
Reports error, including file name and line.

PUBLIC DATA

None.

PUBLIC ROUTINES

  1. rivers_init

    subroutine rivers_init &
     ( Rivers, gblon, gblat, garea, gfrac, time, dt_fast, dt_slow, domain, &
     id_lon, id_lat )

  type(rivers_type), intent(inout) :: Rivers     ! data to initialize
  real,            intent(in)      :: gblon(:)   ! lon boundaries of the grid cells
  real,            intent(in)      :: gblat(:)   ! lat boundaries of the grid cells
  real,            intent(in)      :: garea(:,:) ! total area of each grid cell
  real,            intent(in)      :: gfrac(:,:) ! fraction of the cell covered by land
  type(time_type), intent(in)      :: time       ! current time
  type(time_type), intent(in)      :: dt_fast    ! fast time step
  type(time_type), intent(in)      :: dt_slow    ! slow time step
  type(domain2d),  intent(in)      :: domain     ! our domain
  integer,         intent(in)      :: id_lon     ! ID of land longitude (X) diag axis
  integer,         intent(in)      :: id_lat     ! ID of land latitude (Y) diag axis
    call rivers_init ( Rivers, gblon, gblat, garea, gfrac, time, dt_fast, dt_slow, domain, id_lon, id_lat )
    DESCRIPTION
    Initializes rivers data instance.


  2. rivers_end

    subroutine rivers_end(Rivers)

  type(rivers_type), intent(inout) :: Rivers ! data to deallocate/finish
    call rivers_end (Rivers)
    DESCRIPTION
    Deallocates rivers data instance.


  3. init_routing

    subroutine init_routing ( glonb, glatb, gfrac, is,ie, js,je, i_dest,j_dest )

  real,    intent(in)  :: glonb(:)            ! lon boundaries of the global grid
  real,    intent(in)  :: glatb(:)            ! lat boundaries of the global grid
  real,    intent(in)  :: gfrac(:,:)          ! global array of land fractional area
  integer, intent(in)  :: is,ie,js,je         ! boundaries of our domain

  integer, intent(out) :: i_dest(is:ie,js:je) ! lon index of dest points
  integer, intent(out) :: j_dest(is:ie,js:je) ! lat index of dest points
    call init_routing ( glonb, glatb, gfrac, is,ie, js,je, i_dest,j_dest )
    DESCRIPTION
    Sets river destination indices.


  4. is_coastal

    logical function is_coastal(i, j, gfrac)

  integer, intent(in) :: i, j       ! coordinates of the point in question
  real,    intent(in) :: gfrac(:,:) ! fractional area of the land
    value= is_coastal (i, j, gfrac)
    DESCRIPTION
    Returns true if and only if point (i,j) is a coastal point on the map gfrac.


  5. init_rivers_diag

    subroutine init_rivers_diag ( id_lon, id_lat, Time)

  integer,         intent(in) :: id_lon  ! ID of land longitude (X) diag axis
  integer,         intent(in) :: id_lat  ! ID of land latitude (Y) diag axis
  type(time_type), intent(in) :: Time    ! current time
    call init_rivers_diag ( id_lon, id_lat, Time)
    DESCRIPTION
    Initializes diagnostics for rivers module.


  6. update_rivers_fast

    subroutine update_rivers_fast ( Rivers )

  type(rivers_type), intent(inout) :: Rivers ! data to update
    call update_rivers_fast ( Rivers )
    DESCRIPTION
    Updates state of the rivers and runoff on the fast time-scale.


  7. calc_discharge

    subroutine calc_discharge ( rivers, runoff, discharge )

  type(rivers_type), intent(in)  :: rivers                           ! data to update
  real,              intent(in)  :: runoff(rivers%is:,rivers%js:)    ! runoff, kg/m2/s
  real,              intent(out) :: discharge(rivers%is:,rivers%js:) ! resulting discharge, kg/s
    call calc_discharge ( rivers, runoff, discharge )
    DESCRIPTION
    Given local runoff field, calculates local portion of discharge. Both runoff and discharge fields are of local domain size.


  8. update_rivers_slow

    subroutine update_rivers_slow ( rivers, runoff_w, runoff_s )

  type(rivers_type), intent(inout) :: rivers         ! river data to update
  real,              intent(in)    :: runoff_w(:,:)  ! runoff of liquid water, kg/(m2 s)
  real,              intent(in)    :: runoff_s(:,:)  ! snow runoff,  kg/(m2 s)
    call update_rivers_slow ( rivers, runoff_w, runoff_s )
    DESCRIPTION
    Updates state of the rivers and runoff on the slow time-scale.


  9. update_rivers_bnd_slow

    subroutine update_rivers_bnd_slow ( rivers, bnd )

  type(rivers_type),    intent(in)    :: rivers  ! river data to update
  type(land_data_type), intent(inout) :: bnd     ! land boundary data
    call update_rivers_bnd_slow ( rivers, bnd )
    DESCRIPTION
    Updates the river boundary data on the slow time-scale.


  10. diag_slow

    subroutine diag_slow ( rivers )

  type(rivers_type), intent(in) :: rivers  ! river data to update
    call diag_slow ( rivers )
    DESCRIPTION
    Diagnostic field output of the slow time-scale variables.


  11. diag_static

    subroutine diag_static ( rivers )

  type(rivers_type), intent(in) :: rivers  ! river data
    call diag_static ( rivers )
    DESCRIPTION
    Static diagnostic fields output.


  12. print_error_mesg

    subroutine print_error_mesg(mod_name, message, mode, file, line)

  character(len=*), intent(in) :: mod_name   ! module name
  character(len=*), intent(in) :: message    ! error message
  integer,          intent(in) :: mode       ! error mode
  character(len=*), intent(in) :: file       ! file containing error
  integer,          intent(in) :: line       ! line number or error
    call print_error_mesg (mod_name, message, mode, file, line)
    DESCRIPTION
    Reports error, including file name and line.


PUBLIC TYPES

rivers_type

Describes the domain and physical properties of the rivers.

domain
Computational domain
[domain2d, dimension2]
is
Computational domain bounds
[integer]
ie
Computational domain bounds
[integer]
js
Computational domain bounds
[integer]
je
Computational domain bounds
[integer]
gnlon
Size of global grid
[integer]
gnlat
Size of global grid
[integer]
i_dest
Longitude destination indices
[integer, pointer, dimension2]
j_dest
Latitude destination indices
[integer, pointer, dimension2]
warea
Area covered by water per grid cell
[real, pointer, dimension2, units: m2]
larea
Area of land per grid cell
[real, pointer, dimension2, units: m2]
discharge
Water discharge
[real, pointer, dimension2, units: kg/m2/s]
discharge_snow
Snow discharge
[real, pointer, dimension2, units: kg/m2/s]
time
Current time
[time_type, units: s]
dt
Fast time step
[real, units: s]
dt_slow
Slow time step
[real, units: s]

NAMELIST

&rivers_nml

use_single_basin
If true, all river discharge goes to a single point
[logical, default: .false.]
i_dest0
Destination point longitude index
[integer, default: 1]
j_dest0
Destination point latitude index
[integer, default: 1]
min_water_frac
Minimum water area fraction for the point to be a valid discharge destination
[real, default: 1e-4]
min_land_frac
"Land" for discharge destination calculations
[real, default: 1e-4]

DIAGNOSTIC FIELDS

Diagnostic fields may be output to a netcdf file by specifying the module name identifier and the desired field names (given below) in file diag_table. See the documentation for diag_manager.
Diagnostic fields for module name identifier: 

field name   
----------   
discharge   
discharge_snow   
discharge_aw   
discharge_snow_aw   
dest   
basin   

field description (units)
-------------------------
Discharge (kg/s)
Snow Discharge (kg/s)
Water discharge per unit ocean area (kg/(m2 s))
Snow discharge per unit ocean area (kg/(m2 s))
Destination points (dimensionless)
River basins (dimensionless)

DATA SETS

None.

ERROR MESSAGES

FATAL in rivers_init
Cannot allocate river data
FATAL in init_routing
Cannot find file INPUT/river_destination_field: provide this file or set use_single_basin = .true. in rivers_nml
The namelist settings request the river destination field to be read, but the file cannot be found. Either provide this file, or change module namelist parameters so it is not necessary. To do the latter, set use_single_basin = .true. in the namelist rivers_nml.
FATAL in init_routing
Cannot allocate buffers
FATAL in init_routing
Cannot allocate buffers for route compacting
FATAL in init_routing
Cannot allocate routing table
FATAL in init_routing
Route_compact index below zero
FATAL in init_routing
Route_compact index above n_dest
FATAL in init_routing
Route index below zero
FATAL in init_routing
Route index above n_dest
ERROR in init_routing
Runoff sink is not near coast
NOTE in init_routing
Runoff sink re-routed from land or ocean cell to coastal cell

top