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

Module soil_mod

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


OVERVIEW

Module containing processes relating to the soil.

Soil data type is defined and describes the characteristics of the soil. The soil module and the state of soil is initialized. The soil data is updated on the fast and slow time-scale. Contains updates to the "fast" boundary data that the atmosphere sees and the "slow" part of boundary data for the atmosphere. Sends tile-averaged data to the diagnostics manager.


OTHER MODULES USED

   time_manager_mod
mpp_domains_mod
fms_mod
fms_io_mod
rivers_mod
land_types_mod
land_properties_mod
constants_mod
diag_manager_mod
data_override_mod

PUBLIC INTERFACE

send_averaged_data:
Interface to tile-averaged diagnostic routines
soil_init:
Initializes the state of the soil.
init_soil_diag:
Initializes diagnostic for soil.
soil_end:
Deallocates soil data.
update_soil_fast:
Fast time-scale soil updater.
update_soil_slow:
Slow time-scale soil state updater: groundwater dynamics and routing of river flows (and calving).
update_soil_bnd_fast:
Updates boundary data for the atmosphere on the fast time-scale.
update_soil_bnd_slow:
Updates boundary data for the atmosphere on the slow time-scale.
diag_fast:
Sends data for diagnostics on fast time-scale.
diag_slow:
Diagnostics on slow time-scale.
diag_static:
Diagnostics of the static variables.
average_tiles:
Average 2-dimensional field over tiles.


PUBLIC DATA

None.


PUBLIC ROUTINES

  1. send_averaged_data

    function send_averaged_data ( id, field, area, time, mask )
    
      integer, intent(in)          :: id             ! id of the diagnostic field 
      real,    intent(in)          :: field(:,:,:)   ! field to average and send
      real,    intent(in)          :: area (:,:,:)   ! area of tiles (== averaging 
                                                     ! weights), arbitrary units
      type(time_type), intent(in)  :: time           ! current time
      logical, intent(in),optional :: mask (:,:,:)   ! land mask
    function send_averaged_data( id, field, area, time, mask )
    
      integer, intent(in)          :: id              ! id of the diagnostic field
      real,    intent(in)          :: field(:,:,:,:)  ! (lon, lat, tile, lev) field 
                                                      ! to average and send
      real,    intent(in)          :: area (:,:,:)    ! (lon, lat, tile) tile areas 
                                                      ! ( == averaging weights), 
                                                      ! arbitrary units
      type(time_type), intent(in)  :: time            ! current time
      logical, intent(in),optional :: mask (:,:,:)    ! (lon, lat, tile) land mask

    DESCRIPTION
    Interface to tile-averaged diagnostic routines


  2. soil_init

    subroutine soil_init ( soil, gblon, gblat, garea, gfrac,  &
         time, dt_fast, dt_slow, domain, frac, mask, &
         id_lon, id_lat, dz1 )
    
      type(soil_type), intent(inout) :: soil        ! soil 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(:,:)  ! full area of the land grid cells
      real,            intent(in)  :: gfrac(:,:)  ! fraction of grid cells covered by land
      type(time_type), intent(in)  :: time        ! time origin
      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      ! domain assigned for us
      ! may be the values below should be replaced with something more
      ! general, like "grid_type" ?
      real,            intent(in)  :: frac(:,:,:) ! fractional area of tiles
      logical,         intent(in)  :: mask(:,:,:) ! true if land
      integer,         intent(in)  :: id_lon      ! ID of longitude land diag axis
      integer,         intent(in)  :: id_lat      ! ID of latitude land diag axis
    
      real, optional,  intent(in)  :: dz1(:)      ! thickness of soil layers
    call soil_init ( soil, gblon, gblat, garea, gfrac, & time, dt_fast, dt_slow, domain, frac, mask, & id_lon, id_lat, dz1 )
    DESCRIPTION
    Reads the namelist, which is assumed to be named soil_nml and located in the file input.nml. Sets the number of tiles in the soil and the level number for the soil data. Allocate soil data. Sets up time-related values and vertical layering parameters. Sets up initial land area, fractional area, and mask. Reconciles the fractional area with mask: the sum of fractional areas has to be 1 everywhere, even where there is no land. Initializes accumulated values, soil diagnostics and rivers submodule. Assigns initial values to dynamic land properties (albedo). Send static fields to diagnostic manager for output and copies glacier mass conservation flag to the soil data stricture.


  3. init_soil_diag

    subroutine init_soil_diag ( id_lon, id_lat, zfull, zhalf, Time )
    
      integer,         intent(in) :: id_lon  ! ID of land longitude (X) axis  
      integer,         intent(in) :: id_lat  ! ID of land longitude (X) axis
      real,            intent(in) :: zfull(:)! Full levels, m
      real,            intent(in) :: zhalf(:)! Half levels, m
      type(time_type), intent(in) :: Time    ! Current time
    call init_soil_diag ( id_lon, id_lat, zfull, zhalf, Time )
    DESCRIPTION
    Initializes diagnostics for soil. Defines vertical axis, array of axis indices and diagnostic and static fields.


  4. soil_end

    subroutine soil_end ( soil )
    
      type(soil_type), intent(inout)      :: soil    ! data to finish using
    call soil_end ( soil )
    DESCRIPTION
    Deallocates soil data.


  5. update_soil_fast

    subroutine update_soil_fast ( soil, &
         fsw, flw, sens, evap, dhdt, dedt, drdt, lprec, fprec )
    
      type(soil_type), intent(inout) :: soil ! soil state to update
      real, intent(in) :: &
           fsw  (soil%is:soil%ie,soil%js:soil%je,soil%n_tiles), & ! shortwave flux
           flw  (soil%is:soil%ie,soil%js:soil%je,soil%n_tiles), & ! longwave flux
           sens (soil%is:soil%ie,soil%js:soil%je,soil%n_tiles), & ! sensible heat
                                                                  ! flux
           evap (soil%is:soil%ie,soil%js:soil%je,soil%n_tiles), & ! evaporation
           dhdt (:,:,:), & ! derivative of sens over T
           dedt (:,:,:), & ! derivative of evap over T
           drdt (:,:,:), & ! derivative of LW radiation over T
           lprec(:,:,:), & ! liquid prec
           fprec(:,:,:)    ! solid prec (snow)
    call update_soil_fast ( soil, & fsw, flw, sens, evap, dhdt, dedt, drdt, lprec, fprec )
    DESCRIPTION
    Calculate surface temperature with implicit correction via upward part of tridiagonal elimination for implicit correction. The surface temperature is corrected for snow melt before proceeding to complete downward part of tridiagonal elimination. If the temperature is above freezing and snow or glacial ice is present, compute potential melt.

    In non-glaciated regions, if there is not enough snow, melt only what's there and increase surface temperature above freezing. In glaciated regions, if there is not enough snow, melt only what's there and then melt the glacier. Otherwise go ahead and use all of the potential snow melt, and leave the surface temperature at freezing.

    Accumulate snow melt water into bucket in non-glacier regions. Using this snow melt-modified surface temperature, correct all fluxes and compute temperature increment and new temperature for output. Complete the tridiagonal solver.

    Bucket hydrology involves treating unglaciated cells first. Tentative changes are based on time-step evaporation and precipitation. If snow cover went negative during this step, take the necessary mass from the soil (water) and re-zero snow. Then put excess soil water into soil drainage. Then do the glaciated cells. soil water is not present, and glacier mass is not tracked. For all land cells, put excess snow into calving. Accumulate drainage for transfer to groundwater on the slow time step. Similarly, accumulate calving. Compute the new albedos and update rivers.


  6. update_soil_slow

    subroutine update_soil_slow(soil, blon, blat)
    
      type(soil_type), intent(inout) :: soil  ! state to update
      real, intent(inout) :: blon(:)
      real, intent(inout) :: blat(:)
    call update_soil_slow (soil)
    DESCRIPTION
    Slow time-scale soil state updater: groundwater dynamics and routing of river flows (and calving). Calculations include snow runoff, liquid water runoff and surface runoff. Ground water is modified and the accumulated values for the next interval are cleaned up. Calls to average_tiles and update_rivers_slow.


  7. update_soil_bnd_fast

    subroutine update_soil_bnd_fast ( soil, bnd )
    
      type(soil_type),      intent(in)  :: soil ! current soil state
      type(land_data_type), intent(inout) :: bnd  ! output boundary data
    call update_soil_bnd_fast ( soil, bnd )
    DESCRIPTION
    Updates boundary data for the atmosphere on the fast time-scale.


  8. update_soil_bnd_slow

    subroutine update_soil_bnd_slow ( soil, bnd )
    
      type(soil_type),      intent(in)  :: soil ! current soil state
      type(land_data_type), intent(inout) :: bnd  ! output boundary data
    call update_soil_bnd_slow ( soil, bnd )
    DESCRIPTION
    Updates boundary data for the atmosphere on the slow time-scale.


  9. diag_fast

    subroutine diag_fast &
         ( soil, prec, fprec, evap, sublim, smelt, gmelt, watsno, sens, lhf, flw, fsw )
    
      type(soil_type), intent(in) :: soil      ! soil state
      real,            intent(in), dimension(:,:,:) :: &
           prec,  &   ! total precipitation, 
           fprec, &   ! frozen precipitation (snow)
           evap,  &   ! evaporation
           sublim,&   ! sublimation
           smelt, &   ! snow melt
           gmelt, &   ! glacier melt
           watsno,&   ! water stolen by snow to satisfy sublimation
           sens,  &   ! sensible heat flux, W/m2
           lhf,   &   ! latent heat flux, W/m2
           flw,   &   ! net longwave flux, W/m2
           fsw        ! shortwave flux, W/m2
    call diag_fast & ( soil, prec, fprec, evap, sublim, smelt, gmelt, sens, lhf, flw, fsw )
    DESCRIPTION
    Sends data for diagnostics on fast time-scale.


  10. diag_slow

    subroutine diag_slow (soil, runoff_w, runoff_s )
    
      type(soil_type), intent(in)  :: soil           ! current soil state
      real,            intent(in)  :: runoff_w(:,:)  ! liquid runoff
      real,            intent(in)  :: runoff_s(:,:)  ! snow runoff
    call diag_slow (soil, runoff_w, runoff_s )
    DESCRIPTION
    Diagnostics on slow time-scale.


  11. diag_static

    subroutine diag_static(soil, frac)
    
      type(soil_type), intent(in) :: soil            ! soil state to diagnose
      real,            intent(in) :: frac(:,:)       ! fraction of land in each cell
    call diag_static (soil, frac)
    DESCRIPTION
    Diagnostics of the static variables.


  12. average_tiles

    subroutine average_tiles ( x, area, mask, out )
    
      real,    intent(in)  :: x   (:,:,:) ! (lon, lat, tile) field to average
      real,    intent(in)  :: area(:,:,:) ! (lon, lat, tile) fractional area
      logical, intent(in)  :: mask(:,:,:) ! (lon, lat, tile) land mask
      real,    intent(out) :: out (:,:)   ! (lon, lat)       result of averaging
    call average_tiles ( x, area, mask, out )
    DESCRIPTION
    Average 2-dimensional field over tiles.



PUBLIC TYPES

soil_type

Public data type describing soil characteristics.

domain
Domain of computation
[domain2d, dimension2]
is
Computational domain bounds
[integer]
ie
Computational domain bounds
[integer]
js
Computational domain bounds
[integer]
je
Computational domain bounds
[integer]
n_levels
Number of levels in the soil
[integer]
n_tiles
Maximum number of tiles in the soil
[integer]
area
Land area for each cell
[real, pointer, dimension2, units: m2]
frac
Tile area fraction for each tile
[real, pointer, dimension3]
mask
Land mask: true where data are present
[logical, pointer, dimension3]
dz
Thickness of layers
[real, pointer, dimension1, units: m]
z
Full level
[real, pointer, dimension1, units: m]
zz
Half level
[real, pointer, dimension1, units: m]
max_fusion
Max amount of energy stored in frozen water, J/m3
[real, pointer, dimension1, units: J/m3]
time
Current time
[time_type]
dt
Fast time step
[real, units: s]
dt_slow
Slow time step
[real, units: s]
temp
Temperature (i,j,tile,level)
[real, pointer, dimension4, units: K]
fusion
Energy needed to melt frozen freezable water (i,j,tile,level)
[real, pointer, dimension4, units: J/m3]
snow
Snow water mass (i,j,tile)
[real, pointer, dimension3, units: kg/m2]
water
Root-zone water (i,j,tile)
[real, pointer, dimension3, units: kg/m2]
groundwater
Groundwater (i,j,tile)
[real, pointer, dimension3, units: kg/m2]
drainage
Flux from water to groundwater (i,j,tile)
[real, pointer, dimension3, units: kg/(m2 s)]
drainage_accum
Drainage, accumulated for slow time steps (i,j,tile)
[real, pointer, dimension3, units: kg/m2]
calving
Horizontal snow flux divergence (i,j,tile)
[real, pointer, dimension3, units: kg/(m2 s)]
calving_accum
Calving, accumulated for slow time steps (i,j,tile)
[real, pointer, dimension3, units: kg/m2]
albedo
Snow-adjusted land (soil?) albedo (i,j,tile)
[real, pointer, dimension3]
albedo_vis_dir
Direct visible surface albedo (i,j,tile)
[real, pointer, dimension3]
albedo_nir_dir
Direct near-infrared surface albedo (i,j,tile)
[real, pointer, dimension3]
albedo_vis_dif
Diffuse visible surface albedo (i,j,tile)
[real, pointer, dimension3]
albedo_nir_dif
Diffuse near-infrared albedo (i,j,tile)
[real, pointer, dimension3]
rough_mom
Momentum roughness length (i,j,tile)
[real, pointer, dimension3, units: m]
rough_heat
Heat roughness length (i,j,tile)
[real, pointer, dimension3, units: m]
rough_scale
Scale momentum drag coefficient (i,j,tile)
[real, pointer, dimension3, units: m]
stomatal
Non-water-stressed bulk stomatal resistance (i,j,tile)
[real, pointer, dimension3, units: s/m]
max_water
Water capacity of root zone (i,j,tile)
[real, pointer, dimension3, units: kg/m2]
tcon
Thermal conductivity of the ground (i,j,tile,level)
[real, pointer, dimension4, units: W/(m K s)]
rho_cap
Volumetric heat capacity of the ground (i,j,tile,level)
[real, pointer, dimension4, units: J/(m3 K)]
tau_groundwater
Groundwater residence time (i,j,tile)
[real, pointer, dimension3, units: s]
glacier
Glacier mask, true if land is a glacier (lon, lat, tile)
[logical, pointer, dimension3]
lake
Lake mask, true where lake on land (lon, lat, tile)
[logical, pointer, dimension3]
cover_type
Land surface cover type (lon, lat, tile)
[integer, pointer, dimension3]
ground
Ground type (lon, lat, tile)
[integer, pointer, dimension3]
max_snow
Maximum snow capacity
[real]
conserve_glacier_mass
When true, prevent glacier sublimation and do not allow glacier melt to run off
[logical]
aa
Coefficients for diffusion
[real, pointer, dimension1]
cc
Coefficients for diffusion
[real, pointer, dimension1]
Rivers
State of rivers and runoff
[rivers_type]


NAMELIST

&soil_nml

n_levels
Default number of soil levels
[integer, default: 5]
dz(max_lev)
Default thickness of layers, from top down
[real, dimension1, units: m, default: (/ 0.005, 0.045, 0.10, 0.35, 1.0, 45*0. /)]
init_temp_no_ice
Initial no-ice T if no restart
[real, units: K, default: 288]
init_temp_ice
Initial ice T if no restart, used where snow or glacier
[real, units: K, default: 260]
init_water
Initial soil water is set to min(init_water, max_water) if no restart
[real, default: 0]
init_snow
Initial snow pack is set to min(init_snow, max_snow) if no restart
[real, default: 0]
init_groundwater
Initial groundwater storage if no restart
[real, default: 0]
conserve_glacier_mass
When true, prevent glacier sublimation and don't allow glacier melt to run off
[logical, default: .false.]
freezable_water(max_lev)
Amount of freezable water in soil, from top down
[real, dimension1, units: kg/m3, default: (/0,index=1,max_lev/)]
init_frozen_water
Initial amount of frozen water in soil if no restart
[real, units: kg/m3, default: 0]


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   
----------
zhalf zfull water snow temp albedo albedo_vis_dir albedo_nir_dir albedo_vis_dif albedo_nir_dif drainage calving precip snowfall evap sublim smelt gmelt sens latent flw fsw wroff sroff groundwater area lfrac glacier cover_type tcon rho_cap stomatal max_water rough_mom rough_heat tau_gw frozen hlf hlv
field description (units)
-------------------------
Half level (m) Full level (m) Mass of water in the bucket (kg/m2) Mass of snow on the ground (kg/m2) Temperature (degK) Albedo (dimensionless) Direct visible surface albedo (dimensionless) Direct near-infrared surface albedo (dimensionless) Diffuse visible surface albedo (dimensionless) Diffuse near-infrared surface albedo (dimensionless) Drainage rate (kg/(m2 s)) Snow sweep rate (kg/(m2 s)) Total precipitation rate (kg/(m2 s)) Snowfall rate (kg/(m2 s)) Evaporation rate (kg/(m2 s)) Sublimation rate (kg/(m2 s)) Snow melt rate (kg/(m2 s)) Glacier melt rate (kg/(m2 s)) Sensible heat flux (W/m2) Latent heat flux (W/m2) Net longwave radiative flux (W/m2) Net shortwave radiative flux (W/m2) Surface runoff of water (kg/(m2 s)) Surface runoff of snow (kg/(m2 s)) Mass of water below bucket (kg/m2) Land area (m2) Fraction of land in cell (dimensionless) Glacier logical mask (dimensionless) Land surface cover type (dimensionless) Ground thermal conductivity (W/(m K s)) Ground volumetric heat capacity (J/(m3 K)) Non-water-stressed stomatal resistance (s/m) Root-zone water capacity (kg/m2) Momentum roughness length (m) Scalar roughness length (m) Groundwater residence time (s) Amount of frozen water in soil (kg/m3) Latent heat of fusion (J/kg) Latent heat of evaporation (J/kg)

DATA SETS

None.


ERROR MESSAGES

FATAL in soil_init
Cannot allocate memory for soil
FATAL in update_soil_fast
update_land_fast:: input arguments have incorrect horizontal dimensions


top