mod_urban_vars.f90

Go to the documentation of this file.

!-------------------------------------------------------------------------------
!-------------------------------------------------------------------------------
module mod_urban_vars
  !-----------------------------------------------------------------------------
  !
  !++ used modules
  !
  use scale_precision
  use scale_stdio
  use scale_prof
  use scale_debug
  use scale_grid_index
  use scale_urban_grid_index

  use scale_const, only: &
     i_sw  => const_i_sw, &
     i_lw  => const_i_lw
  !-----------------------------------------------------------------------------
  implicit none
  private
  !-----------------------------------------------------------------------------
  !
  !++ Public procedure
  !
  public :: urban_vars_setup
  public :: urban_vars_restart_read
  public :: urban_vars_restart_write
  public :: urban_vars_history
  public :: urban_vars_total
  public :: urban_vars_external_in

  public :: urban_vars_restart_create
  public :: urban_vars_restart_open
  public :: urban_vars_restart_def_var
  public :: urban_vars_restart_enddef
  public :: urban_vars_restart_close

  !-----------------------------------------------------------------------------
  !
  !++ Public parameters & variables
  !
  logical,               public :: urban_restart_output                = .false.         

  character(len=H_LONG),  public :: urban_restart_in_basename           = ''
  logical,                public :: urban_restart_in_postfix_timelabel  = .false.         
  character(len=H_LONG),  public :: urban_restart_out_basename          = ''
  logical,                public :: urban_restart_out_postfix_timelabel = .true.          
  character(len=H_MID),   public :: urban_restart_out_title             = 'URBAN restart'
  character(len=H_SHORT), public :: urban_restart_out_dtype             = 'DEFAULT'

  ! prognostic variables
  real(RP), public, allocatable :: urban_tr   (:,:)   ! urban surface temperature of roof [K]
  real(RP), public, allocatable :: urban_tb   (:,:)   ! urban surface temperature of wall [K]
  real(RP), public, allocatable :: urban_tg   (:,:)   ! urban surface temperature of road [K]
  real(RP), public, allocatable :: urban_tc   (:,:)   ! urban canopy air temperature [K]
  real(RP), public, allocatable :: urban_qc   (:,:)   ! urban canopy humidity [kg/kg]
  real(RP), public, allocatable :: urban_uc   (:,:)   ! urban canopy wind [m/s]
  real(RP), public, allocatable :: urban_trl  (:,:,:) ! urban temperature in layer of roof [K]
  real(RP), public, allocatable :: urban_tbl  (:,:,:) ! urban temperature in layer of wall [K]
  real(RP), public, allocatable :: urban_tgl  (:,:,:) ! urban temperature in layer of road [K]
  real(RP), public, allocatable :: urban_rainr(:,:)   ! urban rain storage on roof [mm=kg/m2]
  real(RP), public, allocatable :: urban_rainb(:,:)   ! urban rain storage on wall [mm=kg/m2]
  real(RP), public, allocatable :: urban_raing(:,:)   ! urban rain storage on road [mm=kg/m2]
  real(RP), public, allocatable :: urban_roff (:,:)   ! urban runoff [mm=kg/m2]

  ! tendency variables
  real(RP), public, allocatable :: urban_trl_t  (:,:,:) ! tendency of URBAN_TRL
  real(RP), public, allocatable :: urban_tbl_t  (:,:,:) ! tendency of URBAN_TBL
  real(RP), public, allocatable :: urban_tgl_t  (:,:,:) ! tendency of URBAN_TGL
  real(RP), public, allocatable :: urban_tc_t   (:,:)   ! tendency of URBAN_TC
  real(RP), public, allocatable :: urban_uc_t   (:,:)   ! tendency of URBAN_UC
  real(RP), public, allocatable :: urban_qc_t   (:,:)   ! tendency of URBAN_QC
  real(RP), public, allocatable :: urban_tr_t   (:,:)   ! tendency of URBAN_TR
  real(RP), public, allocatable :: urban_tb_t   (:,:)   ! tendency of URBAN_TB
  real(RP), public, allocatable :: urban_tg_t   (:,:)   ! tendency of URBAN_TG
  real(RP), public, allocatable :: urban_rainr_t(:,:)   ! tendency of URBAN_RAINR
  real(RP), public, allocatable :: urban_rainb_t(:,:)   ! tendency of URBAN_RAINB
  real(RP), public, allocatable :: urban_raing_t(:,:)   ! tendency of URBAN_RAING
  real(RP), public, allocatable :: urban_roff_t (:,:)   ! tendency of URBAN_ROFF

  ! for restart
  real(RP), public, allocatable :: urban_sfc_temp  (:,:)   ! urban grid average of surface temperature [K]
  real(RP), public, allocatable :: urban_sfc_albedo(:,:,:) ! urban grid average of albedo (0-1)
  real(RP), public, allocatable :: urban_sflx_mw   (:,:)   ! urban grid average of w-momentum flux [kg/m2/s]
  real(RP), public, allocatable :: urban_sflx_mu   (:,:)   ! urban grid average of u-momentum flux [kg/m2/s]
  real(RP), public, allocatable :: urban_sflx_mv   (:,:)   ! urban grid average of v-momentum flux [kg/m2/s]
  real(RP), public, allocatable :: urban_sflx_sh   (:,:)   ! urban grid average of sensible heat flux [W/m2]
  real(RP), public, allocatable :: urban_sflx_lh   (:,:)   ! urban grid average of latent heat flux [W/m2]
  real(RP), public, allocatable :: urban_sflx_gh   (:,:)   ! urban grid average of ground heat flux [W/m2]
  real(RP), public, allocatable :: urban_sflx_evap (:,:)   ! urban grid average of water vapor flux [kg/m2/s]

  ! diagnostic variables
  real(RP), public, allocatable :: urban_z0m(:,:) ! urban grid average of rougness length (momentum) [m]
  real(RP), public, allocatable :: urban_z0h(:,:) ! urban grid average of rougness length (heat) [m]
  real(RP), public, allocatable :: urban_z0e(:,:) ! urban grid average of rougness length (vapor) [m]
  real(RP), public, allocatable :: urban_u10(:,:) ! urban grid average of velocity u at 10m [m/s]
  real(RP), public, allocatable :: urban_v10(:,:) ! urban grid average of velocity v at 10m [m/s]
  real(RP), public, allocatable :: urban_t2 (:,:) ! urban grid average of temperature at 2m [K]
  real(RP), public, allocatable :: urban_q2 (:,:) ! urban grid average of water vapor at 2m [kg/kg]

  ! recieved atmospheric variables
  real(RP), public, allocatable :: atmos_temp     (:,:)
  real(RP), public, allocatable :: atmos_pres     (:,:)
  real(RP), public, allocatable :: atmos_w        (:,:)
  real(RP), public, allocatable :: atmos_u        (:,:)
  real(RP), public, allocatable :: atmos_v        (:,:)
  real(RP), public, allocatable :: atmos_dens     (:,:)
  real(RP), public, allocatable :: atmos_qv       (:,:)
  real(RP), public, allocatable :: atmos_pbl      (:,:)
  real(RP), public, allocatable :: atmos_sfc_pres (:,:)
  real(RP), public, allocatable :: atmos_sflx_lw  (:,:,:)
  real(RP), public, allocatable :: atmos_sflx_sw  (:,:,:)
  real(RP), public, allocatable :: atmos_cossza   (:,:)
  real(RP), public, allocatable :: atmos_sflx_prec(:,:)

  !-----------------------------------------------------------------------------
  !
  !++ Private procedure
  !
  !-----------------------------------------------------------------------------
  !
  !++ Private parameters & variables
  !
  logical,                private :: urban_vars_checkrange      = .false.

  integer,                private, parameter :: vmax        = 23
  integer,                private, parameter :: i_tr        = 1
  integer,                private, parameter :: i_tb        = 2
  integer,                private, parameter :: i_tg        = 3
  integer,                private, parameter :: i_tc        = 4
  integer,                private, parameter :: i_qc        = 5
  integer,                private, parameter :: i_uc        = 6
  integer,                private, parameter :: i_trl       = 7
  integer,                private, parameter :: i_tbl       = 8
  integer,                private, parameter :: i_tgl       = 9
  integer,                private, parameter :: i_rainr     = 10
  integer,                private, parameter :: i_rainb     = 11
  integer,                private, parameter :: i_raing     = 12
  integer,                private, parameter :: i_roff      = 13
  integer,                private, parameter :: i_sfc_temp  = 14
  integer,                private, parameter :: i_alb_lw    = 15
  integer,                private, parameter :: i_alb_sw    = 16
  integer,                private, parameter :: i_sflx_mw   = 17
  integer,                private, parameter :: i_sflx_mu   = 18
  integer,                private, parameter :: i_sflx_mv   = 19
  integer,                private, parameter :: i_sflx_sh   = 20
  integer,                private, parameter :: i_sflx_lh   = 21
  integer,                private, parameter :: i_sflx_gh   = 22
  integer,                private, parameter :: i_sflx_evap = 23

  character(len=H_SHORT), private            :: var_name(vmax)
  character(len=H_MID),   private            :: var_desc(vmax)
  character(len=H_SHORT), private            :: var_unit(vmax)
  integer,                private            :: var_id(vmax)
  integer,                private            :: restart_fid = -1  ! file ID

  logical,                private            :: urban_restart_in_check_coordinates = .true.

  data var_name / 'URBAN_TR' ,       &
                  'URBAN_TB' ,       &
                  'URBAN_TG' ,       &
                  'URBAN_TC' ,       &
                  'URBAN_QC' ,       &
                  'URBAN_UC' ,       &
                  'URBAN_TRL' ,      &
                  'URBAN_TBL' ,      &
                  'URBAN_TGL' ,      &
                  'URBAN_RAINR' ,    &
                  'URBAN_RAINB' ,    &
                  'URBAN_RAING' ,    &
                  'URBAN_ROFF',      &
                  'URBAN_SFC_TEMP',  &
                  'URBAN_ALB_LW',    &
                  'URBAN_ALB_SW',    &
                  'URBAN_SFLX_MW',   &
                  'URBAN_SFLX_MU',   &
                  'URBAN_SFLX_MV',   &
                  'URBAN_SFLX_SH',   &
                  'URBAN_SFLX_LH',   &
                  'URBAN_SFLX_GH',   &
                  'URBAN_SFLX_evap'  /

  data var_desc / 'urban surface temperature of roof',                &
                  'urban surface temperature of wall',                &
                  'urban surface temperature of road',                &
                  'urban canopy air temperature',                     &
                  'urban canopy humidity',                            &
                  'urban canopy wind',                                &
                  'urban temperature in layer of roof',               &
                  'urban temperature in layer of wall',               &
                  'urban temperature in layer of road',               &
                  'urban rain strage on roof',                        &
                  'urban rain strage on wall',                        &
                  'urban rain strage on road',                        &
                  'urban runoff ',                                    &
                  'urban grid average of temperature',                &
                  'urban grid average of albedo LW',                  &
                  'urban grid average of albedo SW',                  &
                  'urban grid average of w-momentum flux',            &
                  'urban grid average of u-momentum flux',            &
                  'urban grid average of v-momentum flux',            &
                  'urban grid average of sensible heat flux',         &
                  'urban grid average of latent heat flux',           &
                  'urban grid average of ground heat flux',           &
                  'urban grid average of water vapor flux'            /

  data var_unit / 'K',       &
                  'K',       &
                  'K',       &
                  'K',       &
                  'kg/kg',   &
                  'm/s',     &
                  'K',       &
                  'K',       &
                  'K',       &
                  'kg/m2',   &
                  'kg/m2',   &
                  'kg/m2',   &
                  'kg/m2',   &
                  'K',       &
                  '1',       &
                  '1',       &
                  'kg/m2/s', &
                  'kg/m2/s', &
                  'kg/m2/s', &
                  'W/m2',    &
                  'W/m2',    &
                  'W/m2',    &
                  'kg/m2/s'  /

  !-----------------------------------------------------------------------------
contains
  !-----------------------------------------------------------------------------
  subroutine urban_vars_setup
    use scale_process, only: &
       prc_mpistop
    use scale_const, only: &
       undef => const_undef
    implicit none

    namelist / param_urban_vars /  &
       urban_restart_in_basename,           &
       urban_restart_in_postfix_timelabel,  &
       urban_restart_in_check_coordinates,  &
       urban_restart_output,                &
       urban_restart_out_basename,          &
       urban_restart_out_postfix_timelabel, &
       urban_restart_out_title,             &
       urban_restart_out_dtype,             &
       urban_vars_checkrange

    integer :: ierr
    integer :: iv
    !---------------------------------------------------------------------------

    if( io_l ) write(io_fid_log,*)
    if( io_l ) write(io_fid_log,*) '++++++ Module[VARS] / Categ[URBAN] / Origin[SCALE-RM]'

    allocate( urban_tr(ia,ja)         )
    allocate( urban_tb(ia,ja)         )
    allocate( urban_tg(ia,ja)         )
    allocate( urban_tc(ia,ja)         )
    allocate( urban_qc(ia,ja)         )
    allocate( urban_uc(ia,ja)         )
    allocate( urban_trl(uks:uke,ia,ja) )
    allocate( urban_tbl(uks:uke,ia,ja) )
    allocate( urban_tgl(uks:uke,ia,ja) )
    allocate( urban_rainr(ia,ja)         )
    allocate( urban_rainb(ia,ja)         )
    allocate( urban_raing(ia,ja)         )
    allocate( urban_roff(ia,ja)         )
    urban_tr(:,:)   = undef
    urban_tb(:,:)   = undef
    urban_tg(:,:)   = undef
    urban_tc(:,:)   = undef
    urban_qc(:,:)   = undef
    urban_uc(:,:)   = undef
    urban_trl(:,:,:) = undef
    urban_tbl(:,:,:) = undef
    urban_tgl(:,:,:) = undef
    urban_rainr(:,:)   = undef
    urban_rainb(:,:)   = undef
    urban_raing(:,:)   = undef
    urban_roff(:,:)   = undef

    allocate( urban_tr_t(ia,ja)         )
    allocate( urban_tb_t(ia,ja)         )
    allocate( urban_tg_t(ia,ja)         )
    allocate( urban_tc_t(ia,ja)         )
    allocate( urban_qc_t(ia,ja)         )
    allocate( urban_uc_t(ia,ja)         )
    allocate( urban_trl_t(uks:uke,ia,ja) )
    allocate( urban_tbl_t(uks:uke,ia,ja) )
    allocate( urban_tgl_t(uks:uke,ia,ja) )
    allocate( urban_rainr_t(ia,ja)         )
    allocate( urban_rainb_t(ia,ja)         )
    allocate( urban_raing_t(ia,ja)         )
    allocate( urban_roff_t(ia,ja)         )
    urban_tr_t(:,:)   = undef
    urban_tb_t(:,:)   = undef
    urban_tg_t(:,:)   = undef
    urban_tc_t(:,:)   = undef
    urban_qc_t(:,:)   = undef
    urban_uc_t(:,:)   = undef
    urban_trl_t(:,:,:) = undef
    urban_tbl_t(:,:,:) = undef
    urban_tgl_t(:,:,:) = undef
    urban_rainr_t(:,:)   = undef
    urban_rainb_t(:,:)   = undef
    urban_raing_t(:,:)   = undef
    urban_roff_t(:,:)   = undef

    allocate( urban_sfc_temp(ia,ja)   )
    allocate( urban_sfc_albedo(ia,ja,2) )
    allocate( urban_sflx_mw(ia,ja)   )
    allocate( urban_sflx_mu(ia,ja)   )
    allocate( urban_sflx_mv(ia,ja)   )
    allocate( urban_sflx_sh(ia,ja)   )
    allocate( urban_sflx_lh(ia,ja)   )
    allocate( urban_sflx_gh(ia,ja)   )
    allocate( urban_sflx_evap(ia,ja)   )
    urban_sfc_temp(:,:)   = undef
    urban_sfc_albedo(:,:,:) = undef
    urban_sflx_mw(:,:)   = undef
    urban_sflx_mu(:,:)   = undef
    urban_sflx_mv(:,:)   = undef
    urban_sflx_sh(:,:)   = undef
    urban_sflx_lh(:,:)   = undef
    urban_sflx_gh(:,:)   = undef
    urban_sflx_evap(:,:)   = undef

    allocate( urban_z0m(ia,ja) )
    allocate( urban_z0h(ia,ja) )
    allocate( urban_z0e(ia,ja) )
    allocate( urban_u10(ia,ja) )
    allocate( urban_v10(ia,ja) )
    allocate( urban_t2(ia,ja) )
    allocate( urban_q2(ia,ja) )
    urban_z0m(:,:) = undef
    urban_z0h(:,:) = undef
    urban_z0e(:,:) = undef
    urban_u10(:,:) = undef
    urban_v10(:,:) = undef
    urban_t2(:,:) = undef
    urban_q2(:,:) = undef

    allocate( atmos_temp(ia,ja)   )
    allocate( atmos_pres(ia,ja)   )
    allocate( atmos_w(ia,ja)   )
    allocate( atmos_u(ia,ja)   )
    allocate( atmos_v(ia,ja)   )
    allocate( atmos_dens(ia,ja)   )
    allocate( atmos_qv(ia,ja)   )
    allocate( atmos_pbl(ia,ja)   )
    allocate( atmos_sfc_pres(ia,ja)   )
    allocate( atmos_sflx_lw(ia,ja,2) )
    allocate( atmos_sflx_sw(ia,ja,2) )
    allocate( atmos_cossza(ia,ja)   )
    allocate( atmos_sflx_prec(ia,ja)   )
    atmos_temp(:,:)   = undef
    atmos_pres(:,:)   = undef
    atmos_w(:,:)   = undef
    atmos_u(:,:)   = undef
    atmos_v(:,:)   = undef
    atmos_dens(:,:)   = undef
    atmos_qv(:,:)   = undef
    atmos_pbl(:,:)   = undef
    atmos_sfc_pres(:,:)   = undef
    atmos_sflx_lw(:,:,:) = undef
    atmos_sflx_sw(:,:,:) = undef
    atmos_cossza(:,:)   = undef
    atmos_sflx_prec(:,:)   = undef

    !--- read namelist
    rewind(io_fid_conf)
    read(io_fid_conf,nml=param_urban_vars,iostat=ierr)
    if( ierr < 0 ) then !--- missing
       if( io_l ) write(io_fid_log,*) '*** Not found namelist. Default used.'
    elseif( ierr > 0 ) then !--- fatal error
       write(*,*) 'xxx Not appropriate names in namelist PARAM_URBAN_VARS. Check!'
       call prc_mpistop
    endif
    if( io_nml ) write(io_fid_nml,nml=param_urban_vars)

    if( io_l ) write(io_fid_log,*)
    if( io_l ) write(io_fid_log,*) '*** List of prognostic variables (URBAN) ***'
    if( io_l ) write(io_fid_log,'(1x,A,A24,A,A48,A,A12,A)') &
               '***       |', 'VARNAME                 ','|', &
               'DESCRIPTION                                     ', '[', 'UNIT        ', ']'
    do iv = 1, vmax
       if( io_l ) write(io_fid_log,'(1x,A,I3,A,A24,A,A48,A,A12,A)') &
                  '*** NO.',iv,'|',var_name(iv),'|',var_desc(iv),'[',var_unit(iv),']'
    enddo

    if( io_l ) write(io_fid_log,*)
    if ( urban_restart_in_basename /= '' ) then
       if( io_l ) write(io_fid_log,*) '*** Restart input?  : YES, file = ', trim(urban_restart_in_basename)
       if( io_l ) write(io_fid_log,*) '*** Add timelabel?  : ', urban_restart_in_postfix_timelabel
    else
       if( io_l ) write(io_fid_log,*) '*** Restart input?  : NO'
    endif
    if (       urban_restart_output             &
         .AND. urban_restart_out_basename /= '' ) then
       if( io_l ) write(io_fid_log,*) '*** Restart output? : YES, file = ', trim(urban_restart_out_basename)
       if( io_l ) write(io_fid_log,*) '*** Add timelabel?  : ', urban_restart_out_postfix_timelabel
    else
       if( io_l ) write(io_fid_log,*) '*** Restart output? : NO'
       urban_restart_output = .false.
    endif

    return
  end subroutine urban_vars_setup

  !-----------------------------------------------------------------------------
  subroutine urban_vars_restart_open
    use scale_time, only: &
       time_gettimelabel
    use scale_fileio, only: &
       fileio_open, &
       fileio_check_coordinates
    use mod_urban_admin, only: &
       urban_sw
    implicit none

    character(len=19)     :: timelabel
    character(len=H_LONG) :: basename
    !---------------------------------------------------------------------------

    if( io_l ) write(io_fid_log,*)
    if( io_l ) write(io_fid_log,*) '*** Open restart file (URBAN) ***'

    if ( urban_sw .and. urban_restart_in_basename /= '' ) then

       if ( urban_restart_in_postfix_timelabel ) then
          call time_gettimelabel( timelabel )
          basename = trim(urban_restart_in_basename)//'_'//trim(timelabel)
       else
          basename = trim(urban_restart_in_basename)
       endif

       if( io_l ) write(io_fid_log,*) '*** basename: ', trim(basename)

       call fileio_open( restart_fid, & ! [OUT]
                         basename     ) ! [IN]

       if ( urban_restart_in_check_coordinates ) then
          call fileio_check_coordinates( restart_fid, urban=.true. )
       end if

    else
       if( io_l ) write(io_fid_log,*) '*** restart file for urban is not specified.'
    endif

    return
  end subroutine urban_vars_restart_open

  !-----------------------------------------------------------------------------
  subroutine urban_vars_restart_read
    use scale_fileio, only: &
       fileio_read, &
       fileio_flush
    implicit none
    !---------------------------------------------------------------------------

    if ( restart_fid /= -1 ) then
       if( io_l ) write(io_fid_log,*)
       if( io_l ) write(io_fid_log,*) '*** Read from restart file (URBAN) ***'

       call fileio_read( urban_tr(:,:),                            & ! [OUT]
                         restart_fid, var_name(i_tr), 'XY', step=1 ) ! [IN]
       call fileio_read( urban_tb(:,:),                            & ! [OUT]
                         restart_fid, var_name(i_tb), 'XY', step=1 ) ! [IN]
       call fileio_read( urban_tg(:,:),                            & ! [OUT]
                         restart_fid, var_name(i_tg), 'XY', step=1 ) ! [IN]
       call fileio_read( urban_tc(:,:),                            & ! [OUT]
                         restart_fid, var_name(i_tc), 'XY', step=1 ) ! [IN]
       call fileio_read( urban_qc(:,:),                            & ! [OUT]
                         restart_fid, var_name(i_qc), 'XY', step=1 ) ! [IN]
       call fileio_read( urban_uc(:,:),                            & ! [OUT]
                         restart_fid, var_name(i_uc), 'XY', step=1 ) ! [IN]

       call fileio_read( urban_trl(:,:,:),                             & ! [OUT]
                         restart_fid, var_name(i_trl), 'Urban', step=1 ) ! [IN]
       call fileio_read( urban_tbl(:,:,:),                             & ! [OUT]
                         restart_fid, var_name(i_tbl), 'Urban', step=1 ) ! [IN]
       call fileio_read( urban_tgl(:,:,:),                             & ! [OUT]
                         restart_fid, var_name(i_tgl), 'Urban', step=1 ) ! [IN]

       call fileio_read( urban_rainr(:,:),                            & ! [OUT]
                         restart_fid, var_name(i_rainr), 'XY', step=1 ) ! [IN]
       call fileio_read( urban_rainb(:,:),                            & ! [OUT]
                         restart_fid, var_name(i_rainb), 'XY', step=1 ) ! [IN]
       call fileio_read( urban_raing(:,:),                            & ! [OUT]
                         restart_fid, var_name(i_raing), 'XY', step=1 ) ! [IN]
       call fileio_read( urban_roff(:,:),                             & ! [OUT]
                         restart_fid, var_name(i_roff),  'XY', step=1 ) ! [IN]

       call fileio_read( urban_sfc_temp(:,:),                            & ! [OUT]
                         restart_fid, var_name(i_sfc_temp), 'XY', step=1 ) ! [IN]
       call fileio_read( urban_sfc_albedo(:,:,i_lw),                     & ! [OUT]
                         restart_fid, var_name(i_alb_lw),   'XY', step=1 ) ! [IN]
       call fileio_read( urban_sfc_albedo(:,:,i_sw),                     & ! [OUT]
                         restart_fid, var_name(i_alb_sw),   'XY', step=1 ) ! [IN]

       call fileio_read( urban_sflx_mw(:,:),                              & ! [OUT]
                         restart_fid, var_name(i_sflx_mw),   'XY', step=1 ) ! [IN]
       call fileio_read( urban_sflx_mu(:,:),                              & ! [OUT]
                         restart_fid, var_name(i_sflx_mu),   'XY', step=1 ) ! [IN]
       call fileio_read( urban_sflx_mv(:,:),                              & ! [OUT]
                         restart_fid, var_name(i_sflx_mv),   'XY', step=1 ) ! [IN]
       call fileio_read( urban_sflx_sh(:,:),                              & ! [OUT]
                         restart_fid, var_name(i_sflx_sh),   'XY', step=1 ) ! [IN]
       call fileio_read( urban_sflx_lh(:,:),                              & ! [OUT]
                         restart_fid, var_name(i_sflx_lh),   'XY', step=1 ) ! [IN]
       call fileio_read( urban_sflx_gh(:,:),                              & ! [OUT]
                         restart_fid, var_name(i_sflx_gh),   'XY', step=1 ) ! [IN]
       call fileio_read( urban_sflx_evap(:,:),                            & ! [OUT]
                         restart_fid, var_name(i_sflx_evap), 'XY', step=1 ) ! [IN]

       if( io_aggregate ) call fileio_flush( restart_fid ) ! commit all pending read requests

       call urban_vars_total
    else
       if( io_l ) write(io_fid_log,*) '*** invalid restart file ID for urban.'
    endif

    return
  end subroutine urban_vars_restart_read

  !-----------------------------------------------------------------------------
  subroutine urban_vars_history
    use scale_history, only: &
       hist_in
    implicit none
    !---------------------------------------------------------------------------

    if ( urban_vars_checkrange ) then
       call valcheck( urban_tr(is:ie,js:je),          0.0_rp, 1000.0_rp, var_name(i_tr),        &
                     __file__, __line__ )
       call valcheck( urban_tb(is:ie,js:je),          0.0_rp, 1000.0_rp, var_name(i_tb),        &
                     __file__, __line__ )
       call valcheck( urban_tg(is:ie,js:je),          0.0_rp, 1000.0_rp, var_name(i_tg),        &
                     __file__, __line__ )
       call valcheck( urban_tc(is:ie,js:je),          0.0_rp, 1000.0_rp, var_name(i_tc),        &
                     __file__, __line__ )
       call valcheck( urban_qc(is:ie,js:je),          0.0_rp, 1000.0_rp, var_name(i_qc),        &
                     __file__, __line__ )
       call valcheck( urban_uc(is:ie,js:je),          0.0_rp, 1000.0_rp, var_name(i_uc),        &
                     __file__, __line__ )
       call valcheck( urban_trl(:,is:ie,js:je),        0.0_rp, 1000.0_rp, var_name(i_trl),       &
                     __file__, __line__ )
       call valcheck( urban_tbl(:,is:ie,js:je),        0.0_rp, 1000.0_rp, var_name(i_tbl),       &
                     __file__, __line__ )
       call valcheck( urban_tgl(:,is:ie,js:je),        0.0_rp, 1000.0_rp, var_name(i_tgl),       &
                     __file__, __line__ )
       call valcheck( urban_rainr(is:ie,js:je),      -1000.0_rp, 1000.0_rp, var_name(i_rainr),     &
                     __file__, __line__ )
       call valcheck( urban_rainb(is:ie,js:je),      -1000.0_rp, 1000.0_rp, var_name(i_rainb),     &
                     __file__, __line__ )
       call valcheck( urban_raing(is:ie,js:je),      -1000.0_rp, 1000.0_rp, var_name(i_raing),     &
                     __file__, __line__ )
       call valcheck( urban_roff(is:ie,js:je),      -1000.0_rp, 1000.0_rp, var_name(i_roff),      &
                     __file__, __line__ )
       call valcheck( urban_sfc_temp(is:ie,js:je),          0.0_rp, 1000.0_rp, var_name(i_sfc_temp),  &
                     __file__, __line__ )
       call valcheck( urban_sfc_albedo(is:ie,js:je,i_lw),     0.0_rp,    2.0_rp, var_name(i_alb_lw),    &
                     __file__, __line__ )
       call valcheck( urban_sfc_albedo(is:ie,js:je,i_sw),     0.0_rp,    2.0_rp, var_name(i_alb_sw),    &
                     __file__, __line__ )
    endif

    call hist_in( urban_tr(:,:), var_name(i_tr), var_desc(i_tr), var_unit(i_tr) )
    call hist_in( urban_tb(:,:), var_name(i_tb), var_desc(i_tb), var_unit(i_tb) )
    call hist_in( urban_tg(:,:), var_name(i_tg), var_desc(i_tg), var_unit(i_tg) )
    call hist_in( urban_tc(:,:), var_name(i_tc), var_desc(i_tc), var_unit(i_tc) )
    call hist_in( urban_qc(:,:), var_name(i_qc), var_desc(i_qc), var_unit(i_qc) )
    call hist_in( urban_uc(:,:), var_name(i_uc), var_desc(i_uc), var_unit(i_uc) )

    call hist_in( urban_trl(:,:,:), var_name(i_trl), var_desc(i_trl), var_unit(i_trl), zdim='urban' )
    call hist_in( urban_tbl(:,:,:), var_name(i_tbl), var_desc(i_tbl), var_unit(i_tbl), zdim='urban' )
    call hist_in( urban_tgl(:,:,:), var_name(i_tgl), var_desc(i_tgl), var_unit(i_tgl), zdim='urban' )

    call hist_in( urban_rainr(:,:), var_name(i_rainr), var_desc(i_rainr), var_unit(i_rainr) )
    call hist_in( urban_rainb(:,:), var_name(i_rainb), var_desc(i_rainb), var_unit(i_rainb) )
    call hist_in( urban_raing(:,:), var_name(i_raing), var_desc(i_raing), var_unit(i_raing) )
    call hist_in( urban_roff(:,:), var_name(i_roff),  var_desc(i_roff),  var_unit(i_roff)  )

    call hist_in( urban_sfc_temp(:,:),      var_name(i_sfc_temp), var_desc(i_sfc_temp), var_unit(i_sfc_temp) )
    call hist_in( urban_sfc_albedo(:,:,i_lw), var_name(i_alb_lw),   var_desc(i_alb_lw),   var_unit(i_alb_lw)   )
    call hist_in( urban_sfc_albedo(:,:,i_sw), var_name(i_alb_sw),   var_desc(i_alb_sw),   var_unit(i_alb_sw)   )

    call hist_in( urban_sflx_mw(:,:), var_name(i_sflx_mw),   var_desc(i_sflx_mw),   var_unit(i_sflx_mw)   )
    call hist_in( urban_sflx_mu(:,:), var_name(i_sflx_mu),   var_desc(i_sflx_mu),   var_unit(i_sflx_mu)   )
    call hist_in( urban_sflx_mv(:,:), var_name(i_sflx_mv),   var_desc(i_sflx_mv),   var_unit(i_sflx_mv)   )
    call hist_in( urban_sflx_sh(:,:), var_name(i_sflx_sh),   var_desc(i_sflx_sh),   var_unit(i_sflx_sh)   )
    call hist_in( urban_sflx_lh(:,:), var_name(i_sflx_lh),   var_desc(i_sflx_lh),   var_unit(i_sflx_lh)   )
    call hist_in( urban_sflx_gh(:,:), var_name(i_sflx_gh),   var_desc(i_sflx_gh),   var_unit(i_sflx_gh)   )
    call hist_in( urban_sflx_evap(:,:), var_name(i_sflx_evap), var_desc(i_sflx_evap), var_unit(i_sflx_evap) )

    return
  end subroutine urban_vars_history

  !-----------------------------------------------------------------------------
  subroutine urban_vars_total
    use scale_rm_statistics, only: &
       statistics_checktotal, &
       stat_total
    implicit none

    real(RP) :: total
    integer  :: k
    !---------------------------------------------------------------------------

    if ( statistics_checktotal ) then
       call stat_total( total, urban_tr(:,:), var_name(i_tr) )
       call stat_total( total, urban_tb(:,:), var_name(i_tb) )
       call stat_total( total, urban_tg(:,:), var_name(i_tg) )
       call stat_total( total, urban_tc(:,:), var_name(i_tc) )
       call stat_total( total, urban_qc(:,:), var_name(i_qc) )
       call stat_total( total, urban_uc(:,:), var_name(i_uc) )

       do k = uks, uke
          call stat_total( total, urban_trl(k,:,:), var_name(i_trl) )
          call stat_total( total, urban_tbl(k,:,:), var_name(i_tbl) )
          call stat_total( total, urban_tgl(k,:,:), var_name(i_tgl) )
       enddo

       call stat_total( total, urban_rainr(:,:), var_name(i_rainr) )
       call stat_total( total, urban_rainb(:,:), var_name(i_rainb) )
       call stat_total( total, urban_raing(:,:), var_name(i_raing) )
       call stat_total( total, urban_roff(:,:), var_name(i_roff)  )

       call stat_total( total, urban_sfc_temp(:,:),      var_name(i_sfc_temp) )
       call stat_total( total, urban_sfc_albedo(:,:,i_lw), var_name(i_alb_lw)   )
       call stat_total( total, urban_sfc_albedo(:,:,i_sw), var_name(i_alb_sw)   )

       call stat_total( total, urban_sflx_mw(:,:), var_name(i_sflx_mw)   )
       call stat_total( total, urban_sflx_mu(:,:), var_name(i_sflx_mu)   )
       call stat_total( total, urban_sflx_mv(:,:), var_name(i_sflx_mv)   )
       call stat_total( total, urban_sflx_sh(:,:), var_name(i_sflx_sh)   )
       call stat_total( total, urban_sflx_lh(:,:), var_name(i_sflx_lh)   )
       call stat_total( total, urban_sflx_gh(:,:), var_name(i_sflx_gh)   )
       call stat_total( total, urban_sflx_evap(:,:), var_name(i_sflx_evap) )

    endif

    return
  end subroutine urban_vars_total

  !-----------------------------------------------------------------------------
  subroutine urban_vars_external_in( &
       URBAN_TC_in,        &
       URBAN_QC_in,        &
       URBAN_UC_in,        &
       URBAN_SFC_TEMP_in,  &
       URBAN_SFC_albedo_in )
    implicit none

    real(RP), intent(in) :: urban_tc_in        (ia,ja)
    real(RP), intent(in) :: urban_qc_in        (ia,ja)
    real(RP), intent(in) :: urban_uc_in        (ia,ja)
    real(RP), intent(in) :: urban_sfc_temp_in  (ia,ja)
    real(RP), intent(in) :: urban_sfc_albedo_in(ia,ja,2)

    integer :: k
    !---------------------------------------------------------------------------

    if( io_l ) write(io_fid_log,*)
    if( io_l ) write(io_fid_log,*) '*** External Input (coupler) ***'

    urban_tr(:,:) = urban_sfc_temp_in(:,:)
    urban_tb(:,:) = urban_sfc_temp_in(:,:)
    urban_tg(:,:) = urban_sfc_temp_in(:,:)

    urban_tc(:,:) = urban_tc_in(:,:)
    urban_qc(:,:) = urban_qc_in(:,:)
    urban_uc(:,:) = urban_uc_in(:,:)

    do k = uks, uke
       urban_trl(k,:,:) = urban_sfc_temp_in(:,:)
       urban_tbl(k,:,:) = urban_sfc_temp_in(:,:)
       urban_tgl(k,:,:) = urban_sfc_temp_in(:,:)
    end do

    urban_rainr(:,:) = 0.0_rp
    urban_rainb(:,:) = 0.0_rp
    urban_raing(:,:) = 0.0_rp
    urban_roff(:,:) = 0.0_rp

    urban_sfc_temp(:,:)   = urban_sfc_temp_in(:,:)
    urban_sfc_albedo(:,:,:) = urban_sfc_albedo_in(:,:,:)

    urban_z0m(:,:) = 2.0_rp ! tentative, will be replace in urban scheme
    urban_z0h(:,:) = 0.2_rp ! tentative, will be replace in urban scheme
    urban_z0e(:,:) = 0.2_rp ! tentative, will be replace in urban scheme
    urban_sflx_mw(:,:) = 0.0_rp
    urban_sflx_mu(:,:) = 0.0_rp
    urban_sflx_mv(:,:) = 0.0_rp
    urban_sflx_sh(:,:) = 0.0_rp
    urban_sflx_lh(:,:) = 0.0_rp
    urban_sflx_gh(:,:) = 0.0_rp
    urban_sflx_evap(:,:) = 0.0_rp

    call urban_vars_total

    return
  end subroutine urban_vars_external_in

  !-----------------------------------------------------------------------------
  subroutine urban_vars_restart_create
    use scale_time, only: &
       time_gettimelabel
    use scale_fileio, only: &
       fileio_create
    use mod_urban_admin, only: &
       urban_sw
    implicit none

    character(len=19)     :: timelabel
    character(len=H_LONG) :: basename
    !---------------------------------------------------------------------------

    if ( urban_sw .and. urban_restart_out_basename /= '' ) then

       if( io_l ) write(io_fid_log,*)
       if( io_l ) write(io_fid_log,*) '*** Create restart file (URBAN) ***'

       if ( urban_restart_out_postfix_timelabel ) then
          call time_gettimelabel( timelabel )
          basename = trim(urban_restart_out_basename)//'_'//trim(timelabel)
       else
          basename = trim(urban_restart_out_basename)
       endif

       if( io_l ) write(io_fid_log,*) '*** basename: ', trim(basename)

       call fileio_create( restart_fid,                                               & ! [OUT]
                           basename, urban_restart_out_title, urban_restart_out_dtype ) ! [IN]

    endif

    return
  end subroutine urban_vars_restart_create

  !-----------------------------------------------------------------------------
  subroutine urban_vars_restart_enddef
    use scale_fileio, only: &
       fileio_enddef
    implicit none

    if ( restart_fid /= -1 ) then
       call fileio_enddef( restart_fid ) ! [IN]
    endif

    return
  end subroutine urban_vars_restart_enddef

  !-----------------------------------------------------------------------------
  subroutine urban_vars_restart_close
    use scale_fileio, only: &
       fileio_close
    implicit none
    !---------------------------------------------------------------------------

    if ( restart_fid /= -1 ) then
       if( io_l ) write(io_fid_log,*)
       if( io_l ) write(io_fid_log,*) '*** Close restart file (URBAN) ***'

       call fileio_close( restart_fid ) ! [IN]

       restart_fid = -1
    endif

    return
  end subroutine urban_vars_restart_close

  !-----------------------------------------------------------------------------
  subroutine urban_vars_restart_def_var
    use scale_fileio, only: &
       fileio_def_var
    implicit none
    !---------------------------------------------------------------------------

    if ( restart_fid /= -1 ) then

       call fileio_def_var( restart_fid, var_id(i_tr), var_name(i_tr), var_desc(i_tr), &
                            var_unit(i_tr), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_tb), var_name(i_tb), var_desc(i_tb), &
                            var_unit(i_tb), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_tg), var_name(i_tg), var_desc(i_tg), &
                            var_unit(i_tg), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_tc), var_name(i_tc), var_desc(i_tc), &
                            var_unit(i_tc), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_qc), var_name(i_qc), var_desc(i_qc), &
                            var_unit(i_qc), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_uc), var_name(i_uc), var_desc(i_uc), &
                            var_unit(i_uc), 'XY', urban_restart_out_dtype )

       call fileio_def_var( restart_fid, var_id(i_trl), var_name(i_trl), var_desc(i_trl), &
                            var_unit(i_trl), 'Urban', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_tbl), var_name(i_tbl), var_desc(i_tbl), &
                            var_unit(i_tbl), 'Urban', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_tgl), var_name(i_tgl), var_desc(i_tgl), &
                            var_unit(i_tgl), 'Urban', urban_restart_out_dtype )

       call fileio_def_var( restart_fid, var_id(i_rainr), var_name(i_rainr), var_desc(i_rainr), &
                            var_unit(i_rainr), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_rainb), var_name(i_rainb), var_desc(i_rainb), &
                            var_unit(i_rainb), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_raing), var_name(i_raing), var_desc(i_raing), &
                            var_unit(i_raing), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_roff), var_name(i_roff),  var_desc(i_roff),  &
                            var_unit(i_roff), 'XY', urban_restart_out_dtype )

       call fileio_def_var( restart_fid, var_id(i_sfc_temp), var_name(i_sfc_temp), var_desc(i_sfc_temp), &
                            var_unit(i_sfc_temp), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_alb_lw), var_name(i_alb_lw), var_desc(i_alb_lw), &
                            var_unit(i_alb_lw), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_alb_sw), var_name(i_alb_sw), var_desc(i_alb_sw), &
                            var_unit(i_alb_sw), 'XY', urban_restart_out_dtype )

       call fileio_def_var( restart_fid, var_id(i_sflx_mw), var_name(i_sflx_mw), var_desc(i_sflx_mw), &
                            var_unit(i_sflx_mw), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_sflx_mu), var_name(i_sflx_mu), var_desc(i_sflx_mu), &
                            var_unit(i_sflx_mu), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_sflx_mv), var_name(i_sflx_mv), var_desc(i_sflx_mv), &
                            var_unit(i_sflx_mv), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_sflx_sh), var_name(i_sflx_sh), var_desc(i_sflx_sh), &
                            var_unit(i_sflx_sh), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_sflx_lh), var_name(i_sflx_lh), var_desc(i_sflx_lh), &
                            var_unit(i_sflx_lh), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_sflx_gh), var_name(i_sflx_gh), var_desc(i_sflx_gh), &
                            var_unit(i_sflx_gh), 'XY', urban_restart_out_dtype )
       call fileio_def_var( restart_fid, var_id(i_sflx_evap), var_name(i_sflx_evap), var_desc(i_sflx_evap), &
                            var_unit(i_sflx_evap), 'XY', urban_restart_out_dtype )

    endif

    return
  end subroutine urban_vars_restart_def_var

  !-----------------------------------------------------------------------------
  subroutine urban_vars_restart_write
    use scale_fileio, only: &
       fileio_write_var
    implicit none
    !---------------------------------------------------------------------------

    if ( restart_fid /= -1 ) then

       call urban_vars_total

       call fileio_write_var( restart_fid, var_id(i_tr), urban_tr(:,:),                  & ! [IN]
                              var_name(i_tr), 'XY', nohalo=.true.                        ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_tb), urban_tb(:,:),                  & ! [IN]
                              var_name(i_tb), 'XY', nohalo=.true.                        ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_tg), urban_tg(:,:),                  & ! [IN]
                              var_name(i_tg), 'XY', nohalo=.true.                        ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_tc), urban_tc(:,:),                  & ! [IN]
                              var_name(i_tc), 'XY', nohalo=.true.                        ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_qc), urban_qc(:,:),                  & ! [IN]
                              var_name(i_qc), 'XY', nohalo=.true.                        ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_uc), urban_uc(:,:),                  & ! [IN]
                              var_name(i_uc), 'XY', nohalo=.true.                        ) ! [IN]

       call fileio_write_var( restart_fid, var_id(i_trl), urban_trl(:,:,:),              & ! [IN]
                              var_name(i_trl), 'Urban', nohalo=.true.                    ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_tbl), urban_tbl(:,:,:),              & ! [IN]
                              var_name(i_tbl), 'Urban', nohalo=.true.                    ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_tgl), urban_tgl(:,:,:),              & ! [IN]
                              var_name(i_tgl), 'Urban', nohalo=.true.                    ) ! [IN]

       call fileio_write_var( restart_fid, var_id(i_rainr), urban_rainr(:,:),            & ! [IN]
                              var_name(i_rainr), 'XY', nohalo=.true.                     ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_rainb), urban_rainb(:,:),            & ! [IN]
                              var_name(i_rainb), 'XY', nohalo=.true.                     ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_raing), urban_raing(:,:),            & ! [IN]
                              var_name(i_raing), 'XY', nohalo=.true.                     ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_roff), urban_roff(:,:),              & ! [IN]
                              var_name(i_roff),  'XY', nohalo=.true.                     ) ! [IN]

       call fileio_write_var( restart_fid, var_id(i_sfc_temp), urban_sfc_temp(:,:),      & ! [IN]
                              var_name(i_sfc_temp), 'XY', nohalo=.true.                  ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_alb_lw), urban_sfc_albedo(:,:,i_lw), & ! [IN]
                              var_name(i_alb_lw), 'XY', nohalo=.true.                    ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_alb_sw), urban_sfc_albedo(:,:,i_sw), & ! [IN]
                              var_name(i_alb_sw), 'XY', nohalo=.true.                    ) ! [IN]

       call fileio_write_var( restart_fid, var_id(i_sflx_mw), urban_sflx_mw(:,:),        & ! [IN]
                              var_name(i_sflx_mw), 'XY', nohalo=.true.                   ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_sflx_mu), urban_sflx_mu(:,:),        & ! [IN]
                              var_name(i_sflx_mu), 'XY', nohalo=.true.                   ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_sflx_mv), urban_sflx_mv(:,:),        & ! [IN]
                              var_name(i_sflx_mv), 'XY', nohalo=.true.                   ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_sflx_sh), urban_sflx_sh(:,:),        & ! [IN]
                              var_name(i_sflx_sh), 'XY', nohalo=.true.                   ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_sflx_lh), urban_sflx_lh(:,:),        & ! [IN]
                              var_name(i_sflx_lh), 'XY', nohalo=.true.                   ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_sflx_gh), urban_sflx_gh(:,:),        & ! [IN]
                              var_name(i_sflx_gh), 'XY', nohalo=.true.                   ) ! [IN]
       call fileio_write_var( restart_fid, var_id(i_sflx_evap), urban_sflx_evap(:,:),    & ! [IN]
                              var_name(i_sflx_evap), 'XY', nohalo=.true.                 ) ! [IN]

    endif

    return
  end subroutine urban_vars_restart_write

end module mod_urban_vars