Skip to content

FATES JSON parameter files #3570

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
wants to merge 7 commits into
base: master
Choose a base branch
from
+73 −306
Open

FATES JSON parameter files #3570

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
71e5d91
initial work transitioning to a json FATES parameter file
rgknox Oct 27, 2025
4f88906
removed deprecated fates parameter interface
rgknox Oct 28, 2025
4a59e01
fates json parameter file overhaul.
rgknox Nov 4, 2025
96459bc
passing landroot to CLMBuildNamelist, setting fates parameter file to…
rgknox Nov 22, 2025
632c9bc
Updating build scripts to accommodate the fates json parameter file, …
rgknox Nov 25, 2025
4dbe613
Merge tag 'ctsm5.3.085' into fates-json-params
rgknox Nov 25, 2025
1942849
json updates, fixes to shell commands during testing
rgknox Nov 26, 2025
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
30 changes: 19 additions & 11 deletions bld/CLMBuildNamelist.pm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ SYNOPSIS
Create the namelist for CLM
REQUIRED OPTIONS
-cimeroot "directory" Path to cime directory
-landroot "directory" Path to the land models parent directory, ie <>/ctsm
Copy link
Collaborator

@ekluzek ekluzek Dec 4, 2025

Choose a reason for hiding this comment

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

We probably don't need to send landroot in, as we should be able to get it from information already in CLMBuildNamelist.pm

-config "filepath" Read the given CLM configuration cache file.
Default: "config_cache.xml".
-configuration "cfg" The overall configuration being used [ clm | nwp ]
Expand Down Expand Up @@ -259,6 +260,7 @@ sub process_commandline {
$nl_flags->{'cmdline'} = "@ARGV\n";

my %opts = ( cimeroot => undef,
landroot => undef,
config => "config_cache.xml",
configuration => undef,
csmdata => undef,
Expand Down Expand Up @@ -300,6 +302,7 @@ sub process_commandline {

GetOptions(
"cimeroot=s" => \$opts{'cimeroot'},
"landroot=s" => \$opts{'landroot'},
"driver=s" => \$opts{'driver'},
"clm_demand=s" => \$opts{'clm_demand'},
"co2_ppmv=f" => \$opts{'co2_ppmv'},
Expand Down Expand Up @@ -5509,17 +5512,22 @@ sub add_default {
# The default values for input pathnames are relative. If the namelist
# variable is defined to be an absolute pathname, then prepend
# the CESM inputdata root directory.
if (not defined $settings{'no_abspath'}) {
if (defined $settings{'set_abspath'}) {
$val = set_abs_filepath($val, $settings{'set_abspath'});
} else {
if ($is_input_pathname eq 'abs') {
$val = set_abs_filepath($val, $inputdata_rootdir);
if ( $test_files and ($val !~ /null|none/) and (! -f "$val") ) {
$log->fatal_error("file not found: $var = $val");
}
}
}
if ($is_input_pathname eq 'landroot') {
#my $landroot = $opts->{'landroot'};
$val = set_abs_filepath($val,$opts->{'landroot'});
} else {
if (not defined $settings{'no_abspath'}) {
if (defined $settings{'set_abspath'}) {
$val = set_abs_filepath($val, $settings{'set_abspath'});
} else {
if ($is_input_pathname eq 'abs') {
$val = set_abs_filepath($val, $inputdata_rootdir);
if ( $test_files and ($val !~ /null|none/) and (! -f "$val") ) {
$log->fatal_error("file not found: $var = $val");
}
}
}
}
}

# query the definition to find out if the variable takes a string value.
Expand Down
4 changes: 2 additions & 2 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 @@ -576,10 +576,10 @@ attributes from the config_cache.xml file (with keys converted to upper-case).

<!-- ================================================================== -->
<!-- FATES default parameter file -->
<!-- path is relative to the land root (ie the path to CTSM) -->
<!-- ================================================================== -->

<fates_paramfile>lnd/clm2/paramdata/fates_params_api.41.0.0_14pft_c250813.nc</fates_paramfile>

<fates_paramfile>src/fates/parameter_files/fates_params_default.json</fates_paramfile>
Copy link
Collaborator

@ekluzek ekluzek Dec 4, 2025

Choose a reason for hiding this comment

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

Hmmm. Interesting. Currently we assume that anything with a relative path is under $DIN_LOC_ROOT. But, here we need to point out that it's under LANDROOT. So we should probably add an attribute to say that here.


<!-- ================================================================== -->
<!-- Default surface roughness parameterization -->
Expand Down
2 changes: 1 addition & 1 deletion bld/namelist_files/namelist_definition_ctsm.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1016,7 +1016,7 @@ constants for biogeochem modules
</entry>

<entry id="fates_paramfile" type="char*512" category="datasets"
input_pathname="abs" group="clm_inparm" valid_values="" >
input_pathname="landroot" group="clm_inparm" valid_values="" >
Copy link
Collaborator

@ekluzek ekluzek Dec 4, 2025

Choose a reason for hiding this comment

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

Ahhh, here is where you are pointing out that it's under landroot.

Full pathname datafile with fates parameters
(Only relevant if FATES is on).
</entry>
Expand Down
3 changes: 2 additions & 1 deletion cime_config/buildnml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -386,14 +386,15 @@ def buildnml(case, caseroot, compname):
cmd = os.path.join(lnd_root, "bld", "build-namelist")

command = (
'%s -cimeroot %s -infile %s -csmdata %s -inputdata %s %s -namelist "&clm_inparm start_ymd=%s %s/ " '
'%s -cimeroot %s -landroot %s -infile %s -csmdata %s -inputdata %s %s -namelist "&clm_inparm start_ymd=%s %s/ " '
"%s %s -res %s %s -clm_start_type %s -envxml_dir %s "
"-configuration %s -structure %s "
"%s -glc_nec %s %s -co2_ppmv %s -co2_type %s -config %s -driver %s "
"%s %s %s %s"
% (
cmd,
_CIMEROOT,
lnd_root,
infile,
din_loc_root,
inputdata_file,
Expand Down
13 changes: 0 additions & 13 deletions cime_config/testdefs/ExpectedTestFails.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -418,17 +418,4 @@
<issue>#3494</issue>
</phase>
</test>

<test name="ERI_D_Ld9.f45_f45_mg37.I2000Clm60FatesSpCruRsGs.derecho_gnu.clm-FatesColdSatPhenCamLndTuningMode">
Copy link
Collaborator

@ekluzek ekluzek Dec 4, 2025

Choose a reason for hiding this comment

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

This fixes these two tests? Or is this something that was fixed with the nextsw change, that just didn't get these removed from ExpectedFails?

<phase name="COMPARE_base_rest">
<status>FAIL</status>
<issue>#3496</issue>
</phase>
</test>
<test name="ERI_D_Ld9.f45_f45_mg37.I2000Clm60FatesSpCruRsGs.derecho_intel.clm-FatesColdSatPhenCamLndTuningMode">
<phase name="RUN">
<status>FAIL</status>
<issue>#3507</issue>
</phase>
</test>
</expectedFails>
10 changes: 6 additions & 4 deletions cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2/shell_commands
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
SRCDIR=`./xmlquery SRCROOT --value`
CASEDIR=`./xmlquery CASEROOT --value`
FATESDIR=$SRCDIR/src/fates/
FATESPARAMFILE=$CASEDIR/fates_params_prt2_prescribed_np.nc

ncgen -o $FATESPARAMFILE $FATESDIR/parameter_files/fates_params_default.cdl
FATESPARAMFILE=$CASEDIR/fates_params_prt2_prescribed_np.json

$FATESDIR/tools/modify_fates_paramfile.py --O --fin $FATESPARAMFILE --fout $FATESPARAMFILE --var fates_cnp_prescribed_nuptake --val 1.0 --allpfts
cp $FATESDIR/parameter_files/fates_params_default.json $FATESPARAMFILE

$FATESDIR/tools/modify_fates_paramfile.py --O --fin $FATESPARAMFILE --fout $FATESPARAMFILE --var fates_cnp_prescribed_puptake --val 1.0 --allpfts
$FATESDIR/tools/modify_fates_paramfile.py --overwrite --fin $FATESPARAMFILE --param fates_cnp_prescribed_nuptake --values 1.0 --indices all

$FATESDIR/tools/modify_fates_paramfile.py --overwrite --fin $FATESPARAMFILE --param fates_cnp_prescribed_puptake --values 1.0 --indices all

echo "fates_paramfile = '$FATESPARAMFILE'" >> $CASEDIR/user_nl_clm
Copy link
Collaborator

@ekluzek ekluzek Dec 4, 2025

Choose a reason for hiding this comment

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

I'm a bit concerned about this bit about adding it to the end of the user_nl_clm. A small thing is that each time shell_commands is run it'll append it to the end again. It still works -- but looks a bit strange.

But, putting it here could conflict with what the user adds to a test case. Since, it is a test case that seems unlikely -- but I wonder about unintended consequences. This is a part that can be removed when we can move forward on the plan to move fates parameter file handling into buildnml. So it's likely fine to do as a first step.

1 change: 0 additions & 1 deletion cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2/user_nl_clm
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
fates_paramfile = '$CASEROOT/fates_params_prt2_prescribed_np.nc'
fates_parteh_mode = 2
hist_fincl1 = 'FATES_L2FR','FATES_L2FR_CANOPY_REC_PF','FATES_L2FR_USTORY_REC_PF',
'FATES_NH4UPTAKE_SZPF','FATES_NO3UPTAKE_SZPF','FATES_NEFFLUX_SZPF',
Expand Down
13 changes: 7 additions & 6 deletions cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/shell_commands
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
SRCDIR=`./xmlquery SRCROOT --value`
CASEDIR=`./xmlquery CASEROOT --value`
FATESDIR=$SRCDIR/src/fates/
FATESPARAMFILE=$CASEDIR/fates_params_seeddisp_4x5.nc

ncgen -o $FATESPARAMFILE $FATESDIR/parameter_files/fates_params_default.cdl
FATESPARAMFILE=$CASEDIR/fates_params_seeddisp_4x5.json

$FATESDIR/tools/modify_fates_paramfile.py --O --fin $FATESPARAMFILE --fout $FATESPARAMFILE --var fates_seed_dispersal_fraction --val 0.2 --allpfts
$FATESDIR/tools/modify_fates_paramfile.py --O --fin $FATESPARAMFILE --fout $FATESPARAMFILE --var fates_seed_dispersal_max_dist --val 2500000 --allpfts
$FATESDIR/tools/modify_fates_paramfile.py --O --fin $FATESPARAMFILE --fout $FATESPARAMFILE --var fates_seed_dispersal_pdf_scale --val 1e-05 --allpfts
$FATESDIR/tools/modify_fates_paramfile.py --O --fin $FATESPARAMFILE --fout $FATESPARAMFILE --var fates_seed_dispersal_pdf_shape --val 0.1 --allpfts
cp $FATESDIR/parameter_files/fates_params_default.json $FATESPARAMFILE

$FATESDIR/tools/modify_fates_paramfile.py --overwrite --fin $FATESPARAMFILE --param fates_seed_dispersal_fraction --values 0.2 --indices all
$FATESDIR/tools/modify_fates_paramfile.py --overwrite --fin $FATESPARAMFILE --param fates_seed_dispersal_max_dist --values 2500000 --indices all
$FATESDIR/tools/modify_fates_paramfile.py --overwrite --fin $FATESPARAMFILE --param fates_seed_dispersal_pdf_scale --values 1e-05 --indices all
$FATESDIR/tools/modify_fates_paramfile.py --overwrite --fin $FATESPARAMFILE --param fates_seed_dispersal_pdf_shape --values 0.1 --indices all

echo "fates_paramfile = '$FATESPARAMFILE'" >> $CASEDIR/user_nl_clm
3 changes: 0 additions & 3 deletions src/main/pftconMod.F90
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -537,7 +537,6 @@ subroutine InitRead(this)
use ncdio_pio , only : ncd_inqdid, ncd_inqdlen
use clm_varctl , only : paramfile, use_fates, use_flexibleCN, use_biomass_heat_storage, z0param_method
use spmdMod , only : masterproc
use CLMFatesParamInterfaceMod, only : FatesReadPFTs
use SoilBiogeochemDecompCascadeConType, only : mimics_decomp, decomp_method
!
! !ARGUMENTS:
Expand Down Expand Up @@ -1160,8 +1159,6 @@ subroutine InitRead(this)

call ncd_pio_closefile(ncid)

call FatesReadPFTs()

do i = 0, mxpft
if (.not. use_fates)then
if ( trim(adjustl(pftname(i))) /= trim(expected_pftnames(i)) )then
Expand Down
65 changes: 36 additions & 29 deletions src/utils/clmfates_interfaceMod.F90
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ module CLMFatesInterfaceMod
#include "shr_assert.h"
use PatchType , only : patch
use shr_kind_mod , only : r8 => shr_kind_r8
use shr_file_mod , only : shr_file_getUnit,shr_file_freeUnit
use decompMod , only : bounds_type, subgrid_level_column
use WaterStateBulkType , only : waterstatebulk_type
use WaterDiagnosticBulkType , only : waterdiagnosticbulk_type
Expand Down Expand Up @@ -128,12 +129,10 @@ module CLMFatesInterfaceMod
use shr_log_mod , only : errMsg => shr_log_errMsg
use clm_varcon , only : dzsoi_decomp
use FuncPedotransferMod, only: get_ipedof
use CLMFatesParamInterfaceMod, only: fates_param_reader_ctsm_impl
! use SoilWaterPlantSinkMod, only : Compute_EffecRootFrac_And_VertTranSink_Default

! Used FATES Modules
use FatesInterfaceMod , only : fates_interface_type
use FatesInterfaceMod, only : FatesInterfaceInit, FatesReportParameters
use FatesInterfaceMod, only : FatesInterfaceInit
use FatesInterfaceMod, only : SetFatesGlobalElements1
use FatesInterfaceMod, only : SetFatesGlobalElements2
use FatesInterfaceMod , only : allocate_bcin
Expand All @@ -145,10 +144,7 @@ module CLMFatesInterfaceMod
use FatesInterfaceMod , only : set_fates_ctrlparms
use FatesInterfaceMod , only : UpdateFatesRMeansTStep
use FatesInterfaceMod , only : InitTimeAveragingGlobals

use FatesParametersInterface, only : fates_param_reader_type
use FatesParametersInterface, only : fates_parameters_type

use clm_varctl , only : fates_paramfile
use FatesInterfaceMod , only : DetermineGridCellNeighbors
use FatesHistoryInterfaceMod, only : fates_hist
use FatesRestartInterfaceMod, only : fates_restart_interface_type
Expand Down Expand Up @@ -311,16 +307,16 @@ subroutine CLMFatesGlobals1(surf_numpft,surf_numcft,maxsoil_patches)
! in CTSM
! --------------------------------------------------------------------------------

integer,intent(in) :: surf_numpft
integer,intent(in) :: surf_numcft
integer,intent(out) :: maxsoil_patches
integer :: pass_use_fixed_biogeog
integer :: pass_use_nocomp
integer :: pass_use_sp
integer :: pass_masterproc
integer :: pass_use_luh2
logical :: verbose_output
type(fates_param_reader_ctsm_impl) :: var_reader
integer,intent(in) :: surf_numpft
integer,intent(in) :: surf_numcft
integer,intent(out) :: maxsoil_patches
integer :: pass_use_fixed_biogeog
integer :: pass_use_nocomp
integer :: pass_use_sp
integer :: pass_masterproc
integer :: pass_use_luh2
logical :: verbose_output
integer :: fates_paramfile_unit

call t_startf('fates_globals1')

Expand Down Expand Up @@ -369,10 +365,12 @@ subroutine CLMFatesGlobals1(surf_numpft,surf_numcft,maxsoil_patches)
pass_use_luh2 = 0
end if
call set_fates_ctrlparms('use_luh2',ival=pass_use_luh2)


call set_fates_ctrlparms('parteh_mode',ival=fates_parteh_mode)

end if


! The following call reads in the parameter file
! and then uses that to determine the number of patches
! FATES requires. We pass that to CLM here
Expand All @@ -381,8 +379,20 @@ subroutine CLMFatesGlobals1(surf_numpft,surf_numcft,maxsoil_patches)
! and allocations on the FATES side, which require
! some allocations from CLM (like soil layering)

call SetFatesGlobalElements1(use_fates,surf_numpft,surf_numcft,var_reader)

!------------------------------------------------------------------------

! It is FATES' job to open and close the file
! This step is simply to provide a unit number to use
fates_paramfile_unit = shr_file_getUnit()
Copy link
Collaborator

@ekluzek ekluzek Dec 4, 2025

Choose a reason for hiding this comment

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

shr_file_getUnit is actually deprecated now that Fortran has built-in file unit management. When you use open to open a file you can use newunit= to get a free unit. So it simplifies how this is done.


!call opnfil (locfn, iun, form)
!call getfil(fates_paramfile, locfn, 0)

call SetFatesGlobalElements1(use_fates,surf_numpft,surf_numcft,fates_paramfile,fates_paramfile_unit)

call shr_file_freeUnit(fates_paramfile_unit)

maxsoil_patches = fates_maxPatchesPerSite

call t_stopf('fates_globals1')
Expand Down Expand Up @@ -436,22 +446,15 @@ subroutine CLMFatesGlobals2()

if (use_fates) then



! Send parameters individually
call set_fates_ctrlparms('num_sw_bbands',ival=numrad)
call set_fates_ctrlparms('vis_sw_index',ival=ivis)
call set_fates_ctrlparms('nir_sw_index',ival=inir)

call set_fates_ctrlparms('num_lev_soil',ival=nlevsoi)
call set_fates_ctrlparms('hlm_name',cval='CLM')
call set_fates_ctrlparms('hio_ignore_val',rval=spval)
call set_fates_ctrlparms('soilwater_ipedof',ival=get_ipedof(0))

call set_fates_ctrlparms('parteh_mode',ival=fates_parteh_mode)
call set_fates_ctrlparms('seeddisp_cadence',ival=fates_seeddisp_cadence)


call set_fates_ctrlparms('hist_hifrq_dimlevel',ival=fates_history_dimlevel(1))
call set_fates_ctrlparms('hist_dynam_dimlevel',ival=fates_history_dimlevel(2))

Expand Down Expand Up @@ -1036,9 +1039,13 @@ subroutine init(this, bounds_proc, flandusepftdat)

call this%init_history_io(bounds_proc)

! Report Fates Parameters (debug flag in lower level routines)
call FatesReportParameters(masterproc)

! Check through FATES parameters
! THis step is performed after the parameter
! reads because we need to cross-reference
! these against namelist settings
!call FatesCheckParameters(masterproc)


! Fire data to send to FATES
call create_fates_fire_data_method( this%fates_fire_data_method )

Expand Down
Loading