Update active crown fire per Scott and Reinhardt 2001, Rothermel 1977

.github/PULL_REQUEST_TEMPLATE.md

@@ -14,29 +14,39 @@
 <!--- the model is expected to generated different answers -->
 <!--- from the master version of the code -->
 
-
-### Checklist:
+### Checklist
 <!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
 <!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
-- [ ] My change requires a change to the documentation.
-- [ ] I have updated the in-code documentation .AND. (the [technical note](https://github.com/NGEET/fates-docs) .OR. the wiki) accordingly.
-- [ ] I have read the [**CONTRIBUTING**](https://github.com/NGEET/fates/blob/master/CONTRIBUTING.md) document.
+*If this is your first time contributing, please read the [**CONTRIBUTING**](https://github.com/NGEET/fates/blob/main/CONTRIBUTING.md) document.*
+
+All checklist items must be checked to enable merging this pull request:
+
+*Contributor*
+- [ ] The in-code documentation has been updated with descriptive comments
+- [ ] The documentation has been assessed to determine if updates are necessary
+
+*Integrator*
 - [ ] FATES PASS/FAIL regression tests were run
-- [ ] If answers were expected to change, evaluation was performed and provided
+- [ ] Evaluation of test results for answer changes was performed and results provided
 
+### Documentation
+<!--- If this pull requests warrants an update to the tech doc or user's guide, and said changes have been made paste a link to the documentation pull request below.  -->
+<!--- If documentation updates are needed, but changes do not yet have their own separate pull request, please create an issue on either repo so that we can keep track of necessary updates.-->
+- [Technical Note](https://github.com/NGEET/fates-docs) update:
+- [User's Guide](https://github.com/NGEET/fates-users-guide) update: 
 
 ### Test Results:
 <!--- Non-trivial changes require the PASS/FAIL regression tests. -->
 <!--- If changes to code are NOT expected to change answers, tests must -->
 <!--- be run against a baseline. -->
 
-CTSM (or) E3SM (specify which) test hash-tag:
+*CTSM (or) E3SM (specify which) test hash-tag:*
 
-CTSM (or) E3SM (specify which) baseline hash-tag:
+*CTSM (or) E3SM (specify which) baseline hash-tag:*
 
-FATES baseline hash-tag:
+*FATES baseline hash-tag:*
 
-Test Output:
+*Test Output:*
 
 <!--- paste in test results here -->
 

.github/workflows/add-to-gh_projects.yml

@@ -0,0 +1,23 @@
+# This is a basic workflow to help you get started with Actions
+
+name: Add issue to github project issue triage board
+
+# Controls when the workflow will run
+on:
+  issues:
+    types:
+      - opened
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  add-to-project:
+    name: add issue to issue triage board project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/[email protected]
+        with:
+          # URL of the project to add issues to
+          project-url: https://github.com/orgs/NGEET/projects/1
+          # A GitHub personal access token with write access to the project
+          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
+

README.md

@@ -5,8 +5,11 @@
 
 This repository holds the Functionally Assembled Terrestrial Ecosystem Simulator (FATES).  FATES is a numerical terrestrial ecosystem model. Its development and support is primarily supported by the Department of Energy's Office of Science, through the Next Generation Ecosystem Experiment - Tropics ([NGEE-T](https://ngee-tropics.lbl.gov/)) project.
 
-For more information on the FATES model, see our [User's Guide](https://fates-users-guide.readthedocs.io/en/latest/) and [technical documentation](https://fates-docs.readthedocs.io/en/latest/index.html).
+For more information on the FATES model, see our [User's Guide](https://fates-users-guide.readthedocs.io/en/latest/) and [technical documentation](https://fates-docs.readthedocs.io/en/latest/index.html).  
 
+Please submit any questions you may have to the [FATES Github Discussions board](https://github.com/NGEET/fates/discussions).
+
+To receive email updates about forthcoming release tags, regular meeting notifications, and other important announcements, please join the [FATES Google group](https://groups.google.com/g/fates_model).
 
 ## Important Guides:
 ------------------------------
@@ -21,7 +24,6 @@ For more information on the FATES model, see our [User's Guide](https://fates-us
 
 [Code of Conduct](https://github.com/NGEET/fates/blob/master/CODE_OF_CONDUCT.md)
 
-
 ## Important Note:
 ------------------------------
 
@@ -33,13 +35,4 @@ https://github.com/E3SM-Project/E3SM
 
 https://github.com/ESCOMP/cesm
 
-## Important Note About Host-Models and Compatible Branches:
-------------------------------------------------------------
-
-The FATES and E3SM teams maintain compatability of the NGEET/FATES master branch with the **E3SM master** branch. When changes to the FATES API force compatability updates with E3SM, there may be some modest lag time.
-
-The FATES team maintains compatability of the NGEET/FATES master branch with the **CTSM fates_next_api** branch.  Since the FATES team uses this branch for its internal testing, this compatability is tightly (immediately) maintained and these two should always be in sync.  However, CTSM master may become out of sync with FATES master for large periods (months) of time.
-
-
-
-
+The FATES, E3SM and CTSM teams maintain compatability of the NGEET/FATES master branch with the E3SM master and CTSM master branches respectively. There may be some modest lag time in which the latest commit on the FATES master branch is available to these host land models (HLM) by default.  This is typically correlated with FATES development updates forcing necessary changes to the FATES API.  See the table of [FATES API/HLM compatibility](https://fates-users-guide.readthedocs.io/en/latest/user/Table-of-FATES-API-and-HLM-STATUS.html) for information on which fates tag corresponds to which HLM tag or commit.  

biogeochem/DamageMainMod.F90

@@ -0,0 +1,225 @@
+module DamageMainMod
+
+  use FatesConstantsMod     , only : r8 => fates_r8
+  use FatesConstantsMod     , only : i4 => fates_int
+  use FatesConstantsMod     , only : itrue, ifalse
+  use FatesConstantsMod     , only : years_per_day
+  use FatesConstantsMod     , only : nearzero
+  use FatesGlobals          , only : fates_log
+  use FatesGlobals          , only : endrun => fates_endrun
+  use shr_log_mod           , only : errMsg => shr_log_errMsg
+  use EDPftvarcon           , only : EDPftvarcon_inst
+  use EDParamsMod           , only : damage_event_code
+  use EDParamsMod           , only : ED_val_history_damage_bin_edges
+  use FatesInterfaceTypesMod, only : hlm_current_day
+  use FatesInterfaceTypesMod, only : hlm_current_month
+  use FatesInterfaceTypesMod, only : hlm_current_year
+  use FatesInterfaceTypesMod, only : hlm_model_day
+  use FatesInterfaceTypesMod, only : hlm_day_of_year
+
+  implicit none
+  private
+
+  logical, protected :: damage_time  ! if true then damage occurs during current time step
+
+  character(len=*), parameter, private :: sourcefile = &
+       __FILE__
+
+  public :: GetCrownReduction
+  public :: GetDamageFrac
+  public :: IsItDamageTime
+  public :: damage_time
+  public :: GetDamageMortality
+
+
+  logical :: debug = .false.  ! for debugging
+
+
+  ! The following is the special classification for undamaged plants
+  ! and is used in contexts where cohort%damageclass is used. This is
+  ! to flag to the user that an undamaged plant is assumed in those contexts
+
+  integer, parameter, public :: undamaged_class = 1
+
+
+  ! ============================================================================
+  ! ============================================================================
+
+contains
+
+
+
+
+  subroutine IsItDamageTime(is_master)
+
+    !----------------------------------------------------------------------------
+    ! This subroutine determines whether damage should occur (it is called daily)
+    ! This is almost an exact replica of the IsItLoggingTime subroutine
+    !-----------------------------------------------------------------------------
+
+
+    integer, intent(in) :: is_master
+    !type(ed_site_type), intent(inout), target :: currentSite
+
+    integer :: icode     ! Integer equivalent of the event code (parameter file only allows reals)
+    integer :: damage_date  ! Day of month for damage extracted from event code
+    integer :: damage_month ! Month of year for damage extracted from event code
+    integer :: damage_year  ! Year for damage extracted from event code
+    integer :: model_day_int  ! Model day
+
+    character(len=64) :: fmt = '(a,i2.2,a,i2.2,a,i4.4)'
+
+    damage_time = .false.
+    icode = int(damage_event_code)
+
+    model_day_int = int(hlm_model_day)
+
+    if(icode .eq. 1) then
+       ! Damage is turned off 
+       damage_time = .false.
+
+    else if(icode .eq. 2) then
+       ! Damage event on first time step 
+       if(model_day_int .eq.1) then
+          damage_time = .true.
+       end if
+
+    else if(icode .eq. 3) then
+       ! Damage event every day - this is not recommended as it will result in a very large
+       ! number of cohorts which will likely be terminated 
+       damage_time = .true.
+
+    else if(icode .eq. 4) then
+       ! Damage event once a month
+       if(hlm_current_day.eq.1 ) then
+          damage_time = .true.
+       end if
+
+    else if(icode < 0 .and. icode > -366) then
+       ! Damage event every year on a specific day of the year
+       ! specified as negative day of year
+       if(hlm_day_of_year .eq. abs(icode) ) then
+          damage_time = .true.
+       end if
+
+    else if(icode > 10000 ) then
+       ! Specific Event: YYYYMMDD
+       damage_date  = icode - int(100* floor(real(icode,r8)/100._r8))
+       damage_year  = floor(real(icode,r8)/10000._r8)
+       damage_month = floor(real(icode,r8)/100._r8) - damage_year*100
+
+       if(hlm_current_day .eq. damage_date .and. &
+            hlm_current_month .eq. damage_month .and. &
+            hlm_current_year .eq. damage_year ) then
+          damage_time = .true.
+       end if
+
+    else
+       ! Bad damage event flag
+       write(fates_log(),*) 'An invalid damage code was specified in fates_params'
+       write(fates_log(),*) 'Check DamageMainMod.F90:IsItDamageTime()'
+       write(fates_log(),*) 'for a breakdown of the valid codes and change'
+       write(fates_log(),*) 'fates_damage_event_code in the file accordingly.'
+       write(fates_log(),*) 'exiting'
+       call endrun(msg=errMsg(sourcefile, __LINE__))
+    end if
+
+    if(damage_time .and. (is_master.eq.itrue) ) then
+       write(fates_log(),fmt) 'Damage Event Enacted on date: ', &
+            hlm_current_month,'-', hlm_current_day,'-',hlm_current_year
+    end if
+
+    return
+
+  end subroutine IsItDamageTime
+
+  !----------------------------------------------------------------------------
+
+  subroutine GetDamageFrac(cc_cd, nc_cd, pft, dist_frac)
+
+
+    ! Given the current cohort damage class find the fraction of individuals
+    ! going to the new damage class.
+    ! This subroutine consults a look up table of transitions from param derived. 
+
+    ! USES
+    use FatesParameterDerivedMod, only : param_derived
+
+
+    ! ARGUMENTS
+    integer, intent(in) :: cc_cd                   ! current cohort crown damage
+    integer, intent(in) :: nc_cd                   ! new cohort crown damage
+    integer, intent(in) :: pft                     ! plant functional type
+    real(r8), intent(out) :: dist_frac             ! fraction of current cohort moving to
+                                                   ! new damage level
+
+    dist_frac = param_derived%damage_transitions(cc_cd, nc_cd, pft) 
+
+  end subroutine GetDamageFrac
+
+  !-------------------------------------------------------    
+
+  subroutine GetCrownReduction(crowndamage, crown_reduction)
+
+    !------------------------------------------------------------------
+    ! This subroutine takes the crown damage class of a cohort (integer)
+    ! and returns the fraction of the crown that is lost.                                                                  
+    !-------------------------------------------------------------------       
+
+    integer(i4), intent(in)   :: crowndamage        ! crown damage class of the cohort
+    real(r8),    intent(out)  :: crown_reduction    ! fraction of crown lost from damage
+
+    crown_reduction = ED_val_history_damage_bin_edges(crowndamage)/100.0_r8
+
+    return
+  end subroutine GetCrownReduction
+
+
+  !----------------------------------------------------------------------------------------
+
+
+  subroutine GetDamageMortality(crowndamage,pft, dgmort)
+
+    !------------------------------------------------------------------
+    ! This subroutine calculates damage-dependent mortality. 
+    ! Not all damage related mortality will be captured by mechanisms in FATES
+    ! (e.g. carbon starvation mortality). Damage could also lead to damage 
+    ! due to unrepresented mechanisms such as pathogens or increased 
+    ! vulnerability to wind throws. This function captures mortality due to 
+    ! those unrepresented mechanisms. 
+    !------------------------------------------------------------------
+
+    use EDPftvarcon                , only : EDPftvarcon_inst
+
+    integer(i4), intent(in) :: crowndamage       ! crown damage class of the cohort
+    integer(i4), intent(in) :: pft               ! plant functional type
+    real(r8),    intent(out) :: dgmort           ! mortality directly associated with damage
+
+    ! local variables
+    real(r8) :: damage_mort_p1       ! inflection  point of the damage mortalty relationship
+    real(r8) :: damage_mort_p2       ! rate parameter for the damage mortality relationship
+    real(r8) :: crown_loss           ! fraction of  crown lost 
+
+    damage_mort_p1 = EDPftvarcon_inst%damage_mort_p1(pft)
+    damage_mort_p2 = EDPftvarcon_inst%damage_mort_p2(pft)
+
+    ! make damage mortality a function of crownloss and not crowndamage
+    ! class so that it doesn't need to be re-parameterised if the number
+    ! of damage classes change.
+    crown_loss = ED_val_history_damage_bin_edges(crowndamage)/100.0_r8
+
+    if (crowndamage .eq. 1 ) then
+       dgmort = 0.0_r8
+    else
+       dgmort = 1.0_r8 / (1.0_r8 + exp(-1.0_r8 * damage_mort_p2 * &
+            (crown_loss - damage_mort_p1) ) )
+
+    end if
+
+    return
+  end subroutine GetDamageMortality
+  !----------------------------------------------------------------------------------------
+
+
+end module DamageMainMod
+