FatesLitterMod.F90

module FatesLitterMod

  ! -------------------------------------------------------------------------------------
  ! This module contains methods and type definitions for all things litter.
  ! "litter" is used here in the broadest sense.  It means all organic material
  ! that is no longer associated with a live plant.
  !
  ! This encompasses:  1) "Coarse Woody Debris"
  !                    2) fine materials leaves, roots etc 
  !                       (sometimes exclusively refered to as litter)
  !                    3) Reproductive materials (seeds, nuts, fruits)
  !
  ! Important point:   THESE POOLS DO NOT CONTAIN DECOMPOSING MATTER !!!!!
  ! 
  ! Continued: These litter pools will fragment, and then be passed to a 
  ! soil-biogeochemical model (NOT FATES) to handle decomposition.
  ! -------------------------------------------------------------------------------------


   ! To-do:
   ! 1) Add the state integration step
   ! 2) Evaluate how we are handling disturbance
   ! 3) Add root fraction variable to each cohort?
   ! 4) Tracking site level mass balances, where should the new litter structure 
   !    help in tracking that sort of thing? 
   ! 5) Add a routine that performs all of the site-level mass balance
   !    integrations from daily sources?
   ! 6) Add check in the initialization sequence to make sure that the
   !    first element is carbon12_element, and carbon12_element is 1
   ! 7) In SFMain, make the indexing consistent with Jackie's changes
   ! 8) In CWD_IN, add the flux diagnostics, then remove the
   !    patch level rate in the history code
   ! 9) Add litter_flux_output to the flux_diags, add it to history
   ! 10) Add termination fluxes to the flux_diags array as well
   ! 11) re-evaluate the removed FATES_BGC_Carbon_Balancecheck
   !     re-write per its original intent
   
   use FatesConstantsMod, only : r8 => fates_r8
   use FatesConstantsMod, only : i4 => fates_int
   use FatesConstantsMod, only : nearzero
   use FatesConstantsMod, only : calloc_abs_error
   use FatesConstantsMod, only : fates_unset_r8

   use FatesGlobals     , only : endrun => fates_endrun
   use FatesGlobals     , only : fates_log 
   use shr_log_mod      , only : errMsg => shr_log_errMsg

   implicit none
   private


   integer, public,  parameter :: ncwd  = 4   ! number of coarse woody debris pools 
                                              ! (twig,s branch,l branch, trunk)
   type, public ::  litter_type

      
      ! This object is allocated for each element (C, N, P, etc) that we wish to track.

      integer              :: element_id            ! This element ID should
                                                    ! be associated with the element
                                                    ! types listed in parteh/PRTGenericMod.F90

                                                    ! Prognostic variables (litter and coarse woody debris)

      real(r8)             :: ag_cwd(ncwd)          ! above ground coarse wood debris (cwd)        [kg/m2]
      real(r8),allocatable :: bg_cwd(:,:)           ! below ground coarse wood debris (cwd x soil) [kg/m2]
      real(r8),allocatable :: leaf_fines(:)         ! above ground leaf litter (pft)               [kg/m2]
      real(r8),allocatable :: root_fines(:,:)       ! below ground fine root litter (pft x soil)   [kg/m2]
      
      real(r8),allocatable :: seed(:)               ! the seed pool (viable)    (pft) [kg/m2]
      real(r8),allocatable :: seed_germ(:)          ! the germinated seed pool  (pft) [kg/m2]

      ! Fluxes in - dying trees / seed rain  (does not include disturbance fluxes)
      
      real(r8)             ::  ag_cwd_in(ncwd)      ! kg/m2/day
      real(r8),allocatable ::  bg_cwd_in(:,:)       ! kg/m2/day
      real(r8),allocatable ::  leaf_fines_in(:)     ! kg/m2/day
      real(r8),allocatable ::  root_fines_in(:,:)   ! kg/m2/day

      real(r8),allocatable ::  seed_in_local(:)     ! kg/m2/day (from local sources)
      real(r8),allocatable ::  seed_in_extern(:)    ! kg/m2/day (from outside cell)

                                                    ! Fluxes out - fragmentation
      
      real(r8)             ::  ag_cwd_frag(ncwd)    ! kg/m2/day
      real(r8),allocatable ::  bg_cwd_frag(:,:)     ! kg/m2/day
      real(r8),allocatable ::  leaf_fines_frag(:)   ! kg/m2/day
      real(r8),allocatable ::  root_fines_frag(:,:) ! kg/m2/day

      ! Fluxes out from burning are not tracked here because this process changes 
      ! the size of the patch as well, and the unit fluxes that would be tracked
      ! here are convoluted

      ! Flux (in/out ... transfer) of seeds
      
      real(r8), allocatable :: seed_decay(:)      ! decay of viable seeds to litter [kg/m2/day]
      real(r8), allocatable :: seed_germ_decay(:) ! decay of germinated seeds to litter [kg/m2/day]
      real(r8), allocatable :: seed_germ_in(:)    ! flux from viable to germinated seed [kg/m2/day]

    contains
      
      procedure,non_overridable :: InitAllocate
      procedure,non_overridable :: DeallocateLitt
      procedure,non_overridable :: InitConditions
      procedure,non_overridable :: FuseLitter
      procedure,non_overridable :: CopyLitter
      procedure,non_overridable :: ZeroFlux
      
   end type litter_type

   ! Part 3: Public extended types

   character(len=*), parameter, private :: sourcefile = __FILE__

contains

  subroutine FuseLitter(this,self_area,donor_area,donor_litt)

    class(litter_type) :: this
    real(r8),intent(in)           :: self_area
    real(r8),intent(in)           :: donor_area
    type(litter_type),intent(in)  :: donor_litt

    ! locals
    integer  :: nlevsoil        ! number of soil layers
    integer  :: c               ! cwd index
    integer  :: pft             ! pft index
    integer  :: ilyr            ! soil layer index
    integer  :: npft            ! number of PFTs
    real(r8) :: self_weight
    real(r8) :: donor_weight
    

    nlevsoil = size(this%bg_cwd,dim=2)
    npft     = size(this%leaf_fines,dim=1)

    self_weight  = self_area /(donor_area+self_area)
    donor_weight = 1._r8 - self_weight

    
    do c=1,ncwd
       this%ag_cwd(c)      = this%ag_cwd(c) *self_weight +  &
                             donor_litt%ag_cwd(c) * donor_weight
       this%ag_cwd_in(c)   = this%ag_cwd_in(c) *self_weight + &
                             donor_litt%ag_cwd_in(c) * donor_weight
       this%ag_cwd_frag(c) = this%ag_cwd_frag(c) *self_weight + &
                             donor_litt%ag_cwd_frag(c) * donor_weight
       do ilyr = 1,nlevsoil
          this%bg_cwd(c,ilyr)      = this%bg_cwd(c,ilyr) * self_weight + &
                                     donor_litt%bg_cwd(c,ilyr) * donor_weight
          this%bg_cwd_in(c,ilyr)   = this%bg_cwd_in(c,ilyr) * self_weight + &
                                     donor_litt%bg_cwd_in(c,ilyr) * donor_weight
          this%bg_cwd_frag(c,ilyr) = this%bg_cwd_frag(c,ilyr) * self_weight + &
                                     donor_litt%bg_cwd_frag(c,ilyr) * donor_weight
       end do
    end do
    
    
    do pft=1,npft
       this%leaf_fines(pft)      = this%leaf_fines(pft) * self_weight + &
                                   donor_litt%leaf_fines(pft) * donor_weight
       this%seed(pft)            = this%seed(pft) * self_weight + &
                                   donor_litt%seed(pft) * donor_weight
       this%seed_germ(pft)       = this%seed_germ(pft) * self_weight + &
                                   donor_litt%seed_germ(pft) * donor_weight
       this%leaf_fines_in(pft)   = this%leaf_fines_in(pft) * self_weight + &
                                   donor_litt%leaf_fines_in(pft) * donor_weight
       this%seed_in_local(pft)   = this%seed_in_local(pft) * self_weight + &
                                   donor_litt%seed_in_local(pft) * donor_weight
       this%seed_in_extern(pft)  = this%seed_in_extern(pft) * self_weight + &
                                   donor_litt%seed_in_extern(pft) * donor_weight
       this%leaf_fines_frag(pft) = this%leaf_fines_frag(pft) * self_weight + &
                                   donor_litt%leaf_fines_frag(pft) * donor_weight
       this%seed_decay(pft)      = this%seed_decay(pft) * self_weight + &
                                   donor_litt%seed_decay(pft) * donor_weight
       this%seed_germ_decay(pft) = this%seed_germ_decay(pft) * self_weight + &
                                   donor_litt%seed_germ_decay(pft) * donor_weight
       this%seed_germ_in(pft)    = this%seed_germ_in(pft) * self_weight + &
                                   donor_litt%seed_germ_in(pft) * donor_weight

       do ilyr=1,nlevsoil
          this%root_fines(pft,ilyr)      = this%root_fines(pft,ilyr) * self_weight + &
                                           donor_litt%root_fines(pft,ilyr) * donor_weight
          this%root_fines_in(pft,ilyr)   = this%root_fines_in(pft,ilyr) * self_weight + &
                                           donor_litt%root_fines_in(pft,ilyr) * donor_weight
          this%root_fines_frag(pft,ilyr) = this%root_fines_frag(pft,ilyr) * self_weight + &
                                           donor_litt%root_fines_frag(pft,ilyr) * donor_weight
       end do
    end do

    return
  end subroutine FuseLitter

  ! =====================================================================================

  subroutine CopyLitter(this,donor_litt)

    ! This might not need to ever be called.  When a new patch is created
    ! from disturbance, litter initialization is handled elsewhere (EDPatchDynamics)


    class(litter_type) :: this
    type(litter_type),intent(in) :: donor_litt


    this%ag_cwd(:)      = donor_litt%ag_cwd(:)
    this%ag_cwd_in(:)   = donor_litt%ag_cwd_in(:)
    this%ag_cwd_frag(:) = donor_litt%ag_cwd_frag(:)
    
    this%bg_cwd(:,:)      = donor_litt%bg_cwd(:,:)
    this%bg_cwd_in(:,:)   = donor_litt%bg_cwd_in(:,:)
    this%bg_cwd_frag(:,:) = donor_litt%bg_cwd_frag(:,:)

    this%leaf_fines(:)    = donor_litt%leaf_fines(:)
    this%seed(:)          = donor_litt%seed(:)
    this%seed_germ(:)     = donor_litt%seed_germ(:)
    this%leaf_fines_in(:) = donor_litt%leaf_fines_in(:)
    this%seed_in_local(:) = donor_litt%seed_in_local(:)
    
    this%seed_in_extern(:)    = donor_litt%seed_in_extern(:)
    this%leaf_fines_frag(:)   = donor_litt%leaf_fines_frag(:)
    
    this%seed_decay(:)        = donor_litt%seed_decay(:)
    this%seed_germ_decay(:)   = donor_litt%seed_germ_decay(:)
    this%seed_germ_in(:)      = donor_litt%seed_germ_in(:)
    this%root_fines(:,:)      = donor_litt%root_fines(:,:)
    this%root_fines_in(:,:)   = donor_litt%root_fines_in(:,:)
    this%root_fines_frag(:,:) = donor_litt%root_fines_frag(:,:)

    return
  end subroutine CopyLitter

  ! =====================================================================================

  subroutine InitAllocate(this,numpft,numlevsoil)

    class(litter_type) :: this
    integer,intent(in)  :: numpft   ! number of plant functional types
    integer,intent(in)  :: numlevsoil ! number of soil layers

    allocate(this%bg_cwd(ncwd,numlevsoil))
    allocate(this%leaf_fines(numpft))
    allocate(this%root_fines(numpft,numlevsoil))
    allocate(this%seed(numpft))
    allocate(this%seed_germ(numpft))

    allocate(this%bg_cwd_in(ncwd,numlevsoil))
    allocate(this%leaf_fines_in(numpft))
    allocate(this%root_fines_in(numpft,numlevsoil))
    allocate(this%seed_in_local(numpft))
    allocate(this%seed_in_extern(numpft))

    allocate(this%bg_cwd_frag(ncwd,numlevsoil))
    allocate(this%leaf_fines_frag(numpft))
    allocate(this%root_fines_frag(numpft,numlevsoil))

    allocate(this%seed_germ_in(numpft))
    allocate(this%seed_germ_decay(numpft))
    allocate(this%seed_decay(numpft))


    ! Initialize everything to a nonsense flag
    this%ag_cwd(:)            = fates_unset_r8
    this%bg_cwd(:,:)          = fates_unset_r8
    this%leaf_fines(:)        = fates_unset_r8
    this%root_fines(:,:)      = fates_unset_r8
    this%seed(:)              = fates_unset_r8
    this%seed_germ(:)         = fates_unset_r8

    this%ag_cwd_in(:)         = fates_unset_r8
    this%bg_cwd_in(:,:)       = fates_unset_r8
    this%leaf_fines_in(:)     = fates_unset_r8
    this%root_fines_in(:,:)   = fates_unset_r8
    this%seed_in_local(:)     = fates_unset_r8
    this%seed_in_extern(:)    = fates_unset_r8

    this%ag_cwd_frag(:)       = fates_unset_r8
    this%bg_cwd_frag(:,:)     = fates_unset_r8
    this%leaf_fines_frag(:)   = fates_unset_r8
    this%root_fines_frag(:,:) = fates_unset_r8

    this%seed_decay(:)        = fates_unset_r8
    this%seed_germ_decay(:)   = fates_unset_r8
    this%seed_germ_in(:)      = fates_unset_r8

    return
  end subroutine InitAllocate

  ! =====================================================================================

  subroutine InitConditions(this, &
                            init_leaf_fines, &
                            init_root_fines, &
                            init_ag_cwd,     &
                            init_bg_cwd,     &
                            init_seed)
    
    class(litter_type) :: this
    real(r8),intent(in) :: init_leaf_fines
    real(r8),intent(in) :: init_root_fines
    real(r8),intent(in) :: init_ag_cwd
    real(r8),intent(in) :: init_bg_cwd
    real(r8),intent(in) :: init_seed
    
    this%ag_cwd(:)              = init_leaf_fines
    this%bg_cwd(:,:)            = init_root_fines
    this%leaf_fines(:)          = init_ag_cwd
    this%root_fines(:,:)        = init_bg_cwd
    this%seed(:)                = init_seed
    
    return
  end subroutine InitConditions
  
  ! =====================================================================================
  
  subroutine DeallocateLitt(this)
    
    class(litter_type) :: this

    deallocate(this%bg_cwd)
    deallocate(this%leaf_fines)
    deallocate(this%root_fines)
    deallocate(this%seed)
    deallocate(this%seed_germ)

    deallocate(this%bg_cwd_in)
    deallocate(this%leaf_fines_in)
    deallocate(this%root_fines_in)
    deallocate(this%seed_in_local)
    deallocate(this%seed_in_extern)
    
    deallocate(this%bg_cwd_frag)
    deallocate(this%leaf_fines_frag)
    deallocate(this%root_fines_frag)
   
    deallocate(this%seed_decay)
    deallocate(this%seed_germ_decay)
    deallocate(this%seed_germ_in)

    return
  end subroutine DeallocateLitt
  
  ! =====================================================================================

  subroutine ZeroFlux(this)
    
    class(litter_type) :: this
    
    this%ag_cwd_in(:)         = 0._r8
    this%bg_cwd_in(:,:)       = 0._r8
    this%leaf_fines_in(:)     = 0._r8
    this%root_fines_in(:,:)   = 0._r8
    this%seed_in_local(:)     = 0._r8
    this%seed_in_extern(:)    = 0._r8

    this%ag_cwd_frag(:)       = 0._r8
    this%bg_cwd_frag(:,:)     = 0._r8
    this%leaf_fines_frag(:)   = 0._r8
    this%root_fines_frag(:,:) = 0._r8
    
    this%seed_germ_in(:)      = 0._r8
    this%seed_decay(:)        = 0._r8
    this%seed_germ_decay(:)   = 0._r8


    return
  end subroutine ZeroFlux



  
end module FatesLitterMod