Skip to content

Add a FATES namelist option for land use transition logic #3728

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JessicaNeedham wants to merge 15 commits into
base: master
Choose a base branch
from
+35 −6
Open

Add a FATES namelist option for land use transition logic #3728

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
a5efb18
add new namelist variable for fates
Oct 10, 2025
819a84e
fix merge error
Oct 13, 2025
caa106e
Merge branch 'master' into jfn-fates-nl-lulogic
Jan 30, 2026
782c977
remove 0 option for lu transition namelist
Jan 30, 2026
66189be
update default to match current code
Feb 9, 2026
62e0961
Merge tag 'ctsm5.4.022' into jfn-fates-nl-lulogic
glemieux Mar 9, 2026
a8fc8d1
minor whitespace change
glemieux Mar 9, 2026
08999a5
set the default fates lu transition ruleset when fates landuse mode i…
glemieux Mar 9, 2026
ef1ffc8
minor whitespace change
glemieux Mar 9, 2026
2a838fb
Add transition logic ruleset check to the landuse mode check
glemieux Mar 9, 2026
72a9074
minor whitespace change
glemieux Mar 9, 2026
3a176e5
add fail test for transition logic
glemieux Mar 9, 2026
0e02bcb
Merge pull request #4 from glemieux/lulogic-value-check
JessicaNeedham Mar 13, 2026
33c68e0
add explanation of default value
Mar 16, 2026
37ebbc7
Merge tag 'ctsm5.4.026' into jfn-fates-nl-lulogic
glemieux Mar 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions bld/CLMBuildNamelist.pm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -823,8 +823,7 @@ sub setup_cmdl_fates_mode {
"use_fates_daylength_factor", "fates_photosynth_acclimation", "fates_stomatal_model",
"fates_stomatal_assimilation", "fates_leafresp_model", "fates_cstarvation_model",
"fates_regeneration_model", "fates_hydro_solver", "fates_radiation_model", "fates_electron_transport_model",
"use_fates_managed_fire"
);
"use_fates_managed_fire", "fates_lu_transition_logic");

# dis-allow fates specific namelist items with non-fates runs
foreach my $var ( @list ) {
Expand Down Expand Up @@ -4925,7 +4924,7 @@ sub setup_logic_fates {
"use_fates_daylength_factor", "fates_photosynth_acclimation", "fates_stomatal_model",
"fates_stomatal_assimilation", "fates_leafresp_model", "fates_cstarvation_model",
"fates_regeneration_model", "fates_hydro_solver", "fates_radiation_model", "fates_electron_transport_model",
"use_fates_managed_fire"
"use_fates_managed_fire","fates_lu_transition_logic"
);

foreach my $var ( @list ) {
Expand All @@ -4938,6 +4937,7 @@ sub setup_logic_fates {
add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'use_fates_luh', 'use_fates'=>$nl_flags->{'use_fates'},
'use_fates_lupft'=>$nl->get_value('use_fates_lupft'),
'use_fates_potentialveg'=>$nl->get_value('use_fates_potentialveg'),
'fates_lu_transition_logic'=>$nl->get_value('fates_lu_transition_logic'),
'fates_harvest_mode'=>remove_leading_and_trailing_quotes($nl->get_value('fates_harvest_mode')) );
add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'use_fates_nocomp', 'use_fates'=>$nl_flags->{'use_fates'},
'use_fates_lupft'=>$nl->get_value('use_fates_lupft'),
Expand Down
10 changes: 10 additions & 0 deletions bld/namelist_files/namelist_defaults_ctsm.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2674,6 +2674,7 @@ lnd/clm2/surfdata_esmf/NEON/ctsm5.4.0/surfdata_1x1_NEON_TOOL_hist_2000_78pfts_c2
<fates_spitfire_mode use_fates=".true.">0</fates_spitfire_mode>
<fates_spitfire_mode use_fates=".true." use_fates_managed_fire=".true." >1</fates_spitfire_mode>
<fates_harvest_mode use_fates=".true.">no_harvest</fates_harvest_mode>
<fates_lu_transition_logic use_fates=".true.">4</fates_lu_transition_logic>
Copy link
Collaborator

@ekluzek ekluzek Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since, it's just an integer, it would be good to have a comment to explain that 4 means

"default value of ruleset 4 above means that plants are not cleared during land use change transitions to rangeland, whereas plants are cleared in transitions to pasturelands and croplands."

(taking language from the FATES PR)

Some of the other integer values I find more acceptable, because there's a smaller list, and for example fates_spitfire_mode has a natural progression. This one is more complex and needs an explaination.

Copy link
Author

@JessicaNeedham JessicaNeedham Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @ekluzek, good idea. I've added a comment explaining what the default value means.

<fates_stomatal_model use_fates=".true.">ballberry1987</fates_stomatal_model>
<fates_stomatal_assimilation use_fates=".true.">net</fates_stomatal_assimilation>
<fates_leafresp_model use_fates=".true.">ryan1991</fates_leafresp_model>
Expand All @@ -2697,6 +2698,15 @@ lnd/clm2/surfdata_esmf/NEON/ctsm5.4.0/surfdata_1x1_NEON_TOOL_hist_2000_78pfts_c2
<use_fates_luh use_fates=".true." use_fates_lupft=".true.">.true.</use_fates_luh>
<use_fates_luh use_fates=".true." use_fates_potentialveg=".true.">.true.</use_fates_luh>
<use_fates_luh use_fates=".true." >.false.</use_fates_luh>
<use_fates_luh use_fates=".true." fates_lu_transition_logic="1" >.true.</use_fates_luh>
<use_fates_luh use_fates=".true." fates_lu_transition_logic="2" >.true.</use_fates_luh>
<use_fates_luh use_fates=".true." fates_lu_transition_logic="3" >.true.</use_fates_luh>
<use_fates_luh use_fates=".true." fates_lu_transition_logic="4" >.true.</use_fates_luh>
<use_fates_luh use_fates=".true." fates_lu_transition_logic="5" >.true.</use_fates_luh>
<use_fates_luh use_fates=".true." fates_lu_transition_logic="6" >.true.</use_fates_luh>
<use_fates_luh use_fates=".true." fates_lu_transition_logic="7" >.true.</use_fates_luh>
<use_fates_luh use_fates=".true." fates_lu_transition_logic="8" >.true.</use_fates_luh>
<use_fates_luh use_fates=".true." fates_lu_transition_logic="9" >.true.</use_fates_luh>
Copy link
Collaborator

@glemieux glemieux Mar 9, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JessicaNeedham I think we need to remove setting the use_fates_luh to .true. for landuse transition logic setting, since this means by default, full fates will run in landuse mode, which I don't think we want. This would mean that the onus is on the user to set use_fates_luh to true.

Looking at the fates-side of the code, it appears we get the clearing matrix regardless of whether or not use_fates_luh is true (or the ruleset). Does the transition logic setting matter for non-landuse mode? The best I can tell it doesn't since the transition rates are zero in that case. If not, we could create and default to a 0 option for the transition logic that would not turn on landuse mode. We'd just need to add that as a viable case option on the fates side.

cc @ckoven

Copy link
Collaborator

@glemieux glemieux Mar 9, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking about this more, it may be simpler to flip this and make sure that there is a default setting when use_fates_luh is true since this is an option necessary for land use mode. I'll create a PR to this branch @JessicaNeedham.

Copy link
Collaborator

@ekluzek ekluzek Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@glemieux it's sounds like you'll make a PR to this branch, and we need to wait on that to bring this in. Just confirming I have that right.

Copy link
Author

@JessicaNeedham JessicaNeedham Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@glemieux - yes that does sound better. We want it so that if use_fates_luh is true, then this namelist option needs to be set to some default value. I will go ahead and merge your PR - thanks!

<fates_parteh_mode use_fates=".true.">1</fates_parteh_mode>
<fates_seeddisp_cadence use_fates=".true.">0</fates_seeddisp_cadence>
<use_fates_nocomp use_fates=".true." use_fates_sp=".true." >.true.</use_fates_nocomp>
Expand Down
7 changes: 7 additions & 0 deletions bld/namelist_files/namelist_definition_ctsm.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -945,6 +945,13 @@ which processes the raw land use data from the THEMIS tool data sets
(https://doi.org/10.5065/29s7-7b41)
</entry>

<entry id="fates_lu_transition_logic" type="integer" category="physics"
group="clm_inparm" valid_values="1,2,3,4,5,6,7,8,9">
Select the logic for land use class transitions.
Allowed values are 1-9. See the FATES user guide for an explanation of the options.
(Only relevant if FATES with land use is on)
</entry>
Copy link
Collaborator

@ekluzek ekluzek Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not currently in the FATES UG. And I didn't see documentation changes in the FATES PR for this (or is the FATES UG located in a different repo?).

The FATES PR does point to Table 1 in this paper:

https://gmd.copernicus.org/articles/13/3203/2020/

which does explain it. So pointing to that table might be the best thing here.

Copy link
Collaborator

@ekluzek ekluzek Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you are going for a principle of having the documentation in one place, which is a good goal. It's just that right now that place doesn't exist, so we need a source that can be looked up. It's also easier for users if it is in place and has more visibility. So it's more usable, but less maintainable. But, I also think this is a part that is unlikely to change -- except maybe on a future CMIP cycle. So even though it means duplicating some of this across HLM's the goal of making it easier for users might be OK

Although another thing that could be considered is to tell the user what FATES Fortran code file to look at. Although that's again something that can be changed out from under the documentation here. So I'm not sure the best way of doing this.

Copy link
Collaborator

@glemieux glemieux Mar 12, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think pointing the user to the FATES user's guide should be the most direct option. I added an issue to the FATES user's guide to make sure we get documentation on this there: NGEET/fates-users-guide#110

Copy link
Author

@JessicaNeedham JessicaNeedham Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @glemieux , I will add changes to FATES documentation to your PR.

Copy link
Collaborator

@glemieux glemieux Mar 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ekluzek we've updated the user's guide to describe the various options via NGEET/fates-users-guide#111. @JessicaNeedham added the table that corresponds to the valid values.


<entry id="use_luna" type="logical" category="physics"
group="clm_inparm" valid_values="" value=".false.">
Toggle to turn on the LUNA model, to effect Photosynthesis by leaf Nitrogen
Expand Down
1 change: 1 addition & 0 deletions src/main/clm_varctl.F90
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -332,6 +332,7 @@ module clm_varctl
! > 1 for external data (lightning and/or anthropogenic ignitions)
! see bld/namelist_files/namelist_definition_clm4_5.xml for details
logical, public :: use_fates_managed_fire = .false. ! true => turn on managed fire
integer, public :: fates_lu_transition_logic = -9 ! controls logic around transition between land use classes
Copy link
Collaborator

@ekluzek ekluzek Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the code check and make sure it was changed from the default value of -9? And that it's within the right range in the Fortran code? The namelist scripts ensure it's between 1 and 9, but the Fortran code should as well.

Copy link
Collaborator

@glemieux glemieux Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added a check in the CLMBuildNamelist to check for valid values: https://github.com/JessicaNeedham/ctsm/pull/4/changes#diff-c5398a7bf444c79516bff3ba46c0fcc5789d003af843d18b96448d2624d27b18

Is that accomplish what you're thinking about here @ekluzek?

logical, public :: use_fates_tree_damage = .false. ! true => turn on tree damage module
character(len=256), public :: fates_harvest_mode = '' ! five different harvest modes; see namelist definition
character(len=256), public :: fates_stomatal_model = '' ! stomatal conductance model, Ball-berry or Medlyn
Expand Down
7 changes: 5 additions & 2 deletions src/main/controlMod.F90
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,8 +258,9 @@ subroutine control_init(dtime)
use_fates_tree_damage, &
use_fates_daylength_factor, &
fates_photosynth_acclimation, &
fates_history_dimlevel, &
use_fates_managed_fire
use_fates_managed_fire, &
fates_lu_transition_logic, &
fates_history_dimlevel

! Ozone vegetation stress method
namelist / clm_inparm / o3_veg_stress_method
Expand Down Expand Up @@ -819,6 +820,7 @@ subroutine control_spmd()
call mpi_bcast (for_testing_allow_interp_non_ciso_to_ciso, 1, MPI_LOGICAL, 0, mpicom, ier)

call mpi_bcast (fates_spitfire_mode, 1, MPI_INTEGER, 0, mpicom, ier)
call mpi_bcast (fates_lu_transition_logic, 1, MPI_INTEGER, 0, mpicom, ier)
call mpi_bcast (fates_harvest_mode, len(fates_harvest_mode) , MPI_CHARACTER, 0, mpicom, ier)
call mpi_bcast (fates_stomatal_model, len(fates_stomatal_model) , MPI_CHARACTER, 0, mpicom, ier)
call mpi_bcast (fates_stomatal_assimilation, len(fates_stomatal_assimilation) , MPI_CHARACTER, 0, mpicom, ier)
Expand Down Expand Up @@ -1236,6 +1238,7 @@ subroutine control_print ()
if (use_fates) then
write(iulog, *) ' fates_spitfire_mode = ', fates_spitfire_mode
write(iulog, *) ' fates_harvest_mode = ', fates_harvest_mode
write(iulog, *) ' fates_lu_transition_logic = ', fates_lu_transition_logic
write(iulog, *) ' fates_stomatal_model = ', fates_stomatal_model
write(iulog, *) ' fates_stomatal_assimilation = ', fates_stomatal_assimilation
write(iulog, *) ' fates_leafresp_model = ', fates_leafresp_model
Expand Down
3 changes: 2 additions & 1 deletion src/utils/clmfates_interfaceMod.F90
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ module CLMFatesInterfaceMod
use clm_varctl , only : use_fates_ed_st3
use clm_varctl , only : use_fates_ed_prescribed_phys
use clm_varctl , only : fates_harvest_mode
use clm_varctl , only : fates_lu_transition_logic
use clm_varctl , only : fates_stomatal_model
use clm_varctl , only : fates_stomatal_assimilation
use clm_varctl , only : fates_leafresp_model
Expand Down Expand Up @@ -403,7 +404,6 @@ subroutine CLMFatesGlobals2()

integer :: pass_vertsoilc
integer :: pass_ch4
integer :: pass_spitfire
integer :: pass_ed_st3
integer :: pass_num_lu_harvest_cats
integer :: pass_lu_harvest
Expand Down Expand Up @@ -637,6 +637,7 @@ subroutine CLMFatesGlobals2()
end if
call set_fates_ctrlparms('num_luh2_states',ival=pass_num_luh_states)
call set_fates_ctrlparms('num_luh2_transitions',ival=pass_num_luh_transitions)
call set_fates_ctrlparms('fates_lu_transition_logic',ival=fates_lu_transition_logic)

if ( use_fates_potentialveg ) then
pass_use_potentialveg = 1
Expand Down