diff --git a/.gitmodules b/.gitmodules index 541855a840..b5156d3190 100644 --- a/.gitmodules +++ b/.gitmodules @@ -76,7 +76,7 @@ fxDONOTUSEurl = https://github.com/ESMCI/ccs_config_cesm.git [submodule "cime"] path = cime url = https://github.com/ESMCI/cime -fxtag = cime6.1.176 +fxtag = cime6.2.2 fxrequired = ToplevelRequired # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed fxDONOTUSEurl = https://github.com/ESMCI/cime @@ -84,7 +84,7 @@ fxDONOTUSEurl = https://github.com/ESMCI/cime [submodule "cmeps"] path = components/cmeps url = https://github.com/ESCOMP/CMEPS.git -fxtag = cmeps1.1.44 +fxtag = cmeps1.1.47 fxrequired = ToplevelRequired # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed fxDONOTUSEurl = https://github.com/ESCOMP/CMEPS.git @@ -92,7 +92,7 @@ fxDONOTUSEurl = https://github.com/ESCOMP/CMEPS.git [submodule "cdeps"] path = components/cdeps url = https://github.com/ESCOMP/CDEPS.git -fxtag = cdeps1.0.93 +fxtag = cdeps1.0.96 fxrequired = ToplevelRequired # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed fxDONOTUSEurl = https://github.com/ESCOMP/CDEPS.git @@ -100,7 +100,7 @@ fxDONOTUSEurl = https://github.com/ESCOMP/CDEPS.git [submodule "share"] path = share url = https://github.com/ESCOMP/CESM_share -fxtag = share1.1.19 +fxtag = share1.1.20 fxrequired = ToplevelRequired # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed fxDONOTUSEurl = https://github.com/ESCOMP/CESM_share @@ -124,7 +124,7 @@ fxDONOTUSEurl = https://github.com/ESMCI/mpi-serial [submodule "doc-builder"] path = doc/doc-builder url = https://github.com/ESMCI/doc-builder -fxtag = v3.1.1 +fxtag = v3.2.1 fxrequired = ToplevelOptional # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed fxDONOTUSEurl = https://github.com/ESMCI/doc-builder diff --git a/cime b/cime index 51cfec52f2..8961a11428 160000 --- a/cime +++ b/cime @@ -1 +1 @@ -Subproject commit 51cfec52f297eb4d30dd34548bf4b69b9ab72d1e +Subproject commit 8961a11428891c96d7ed9390314c7dadc511e29f diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesColdNoCompInitDbh/shell_commands b/cime_config/testdefs/testmods_dirs/clm/FatesColdNoCompInitDbh/shell_commands index 438b95731f..cb6de531b5 100644 --- a/cime_config/testdefs/testmods_dirs/clm/FatesColdNoCompInitDbh/shell_commands +++ b/cime_config/testdefs/testmods_dirs/clm/FatesColdNoCompInitDbh/shell_commands @@ -1,4 +1,4 @@ -SRCDIR=`./xmlquery SRCROOT --value` +SRCDIR=`./xmlquery COMP_ROOT_DIR_LND --value` CASEDIR=`./xmlquery CASEROOT --value` FATESDIR=$SRCDIR/src/fates/ FATESPARAMFILE=$CASEDIR/fates_params_init_dbh.json diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2/include_user_mods b/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2/include_user_mods index e781a89ea2..e73d79a391 100644 --- a/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2/include_user_mods +++ b/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2/include_user_mods @@ -1,3 +1,2 @@ ../Fates ../FatesCold -../FatesSetupParamBuild/ diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2/shell_commands b/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2/shell_commands index 139be432dd..da24cb79a5 100644 --- a/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2/shell_commands +++ b/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2/shell_commands @@ -1,4 +1,4 @@ -SRCDIR=`./xmlquery SRCROOT --value` +SRCDIR=`./xmlquery COMP_ROOT_DIR_LND --value` CASEDIR=`./xmlquery CASEROOT --value` FATESDIR=$SRCDIR/src/fates/ FATESPARAMFILE=$CASEDIR/fates_params_prt2_prescribed_p.json diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2_synthN/include_user_mods b/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2_synthN/include_user_mods index e781a89ea2..e73d79a391 100644 --- a/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2_synthN/include_user_mods +++ b/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2_synthN/include_user_mods @@ -1,3 +1,2 @@ ../Fates ../FatesCold -../FatesSetupParamBuild/ diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2_synthN/shell_commands b/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2_synthN/shell_commands index 2ebf250b2d..5af10d86d0 100644 --- a/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2_synthN/shell_commands +++ b/cime_config/testdefs/testmods_dirs/clm/FatesColdPRT2_synthN/shell_commands @@ -1,4 +1,4 @@ -SRCDIR=`./xmlquery SRCROOT --value` +SRCDIR=`./xmlquery COMP_ROOT_DIR_LND --value` CASEDIR=`./xmlquery CASEROOT --value` FATESDIR=$SRCDIR/src/fates/ FATESPARAMFILE=$CASEDIR/fates_params_prt2_prescribed_np.json diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/README b/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/README index 484fa67db9..ee8c58d6d3 100644 --- a/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/README +++ b/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/README @@ -11,8 +11,8 @@ Given that the default fates parameter file has the above variables as unset, a custom fates parameter file must be supplied to appropriately test this mode. This testmod itself addresses CTSM issue 2151: https://github.com/ESCOMP/CTSM/issues/2151 Note that to avoid exceeding the filename string length maximu, the parameter -file generated on the fly is placed in the $SRCROOT/src/fates/parameter_files -directory. This may still run into problems is the $SRCROOT string is too long. +file generated on the fly is placed in the $COMP_ROOT_DIR_LND/src/fates/parameter_files +directory. This may still run into problems is the $COMP_ROOT_DIR_LND string is too long. The max_dist value will impact the size of the 'neighborhood' of gridcells that fates will attempt to distribute seeds to. To limit the neighborhood to diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/include_user_mods b/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/include_user_mods index 5ad8824b70..e73d79a391 100644 --- a/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/include_user_mods +++ b/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/include_user_mods @@ -1,3 +1,2 @@ ../Fates ../FatesCold -../FatesSetupParamBuild diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/shell_commands b/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/shell_commands index 585a6d65cb..40f10e24c2 100644 --- a/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/shell_commands +++ b/cime_config/testdefs/testmods_dirs/clm/FatesColdSeedDisp/shell_commands @@ -1,4 +1,4 @@ -SRCDIR=`./xmlquery SRCROOT --value` +SRCDIR=`./xmlquery COMP_ROOT_DIR_LND --value` CASEDIR=`./xmlquery CASEROOT --value` FATESDIR=$SRCDIR/src/fates/ diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesColdTwoStream/README b/cime_config/testdefs/testmods_dirs/clm/FatesColdTwoStream/README index 295f8125f3..5c7384bae2 100644 --- a/cime_config/testdefs/testmods_dirs/clm/FatesColdTwoStream/README +++ b/cime_config/testdefs/testmods_dirs/clm/FatesColdTwoStream/README @@ -5,8 +5,8 @@ parameter from 1 to 2. This is all that is needed, both radiation schemes fates_rad_model Note that to avoid exceeding the filename string length maximum, the parameter -file generated on the fly is placed in the $SRCROOT/src/fates/parameter_files -directory. This may still run into problems is the $SRCROOT string is too long. +file generated on the fly is placed in the $COMP_ROOT_DIR_LND/src/fates/parameter_files +directory. This may still run into problems is the $COMP_ROOT_DIR_LND string is too long. Like the test with seed dispersal activation, the main downside of this method is that this file will require a custom update for every fates parameter file API update. diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesSetupParamBuild/README.md b/cime_config/testdefs/testmods_dirs/clm/FatesSetupParamBuild/README.md deleted file mode 100644 index 457118971b..0000000000 --- a/cime_config/testdefs/testmods_dirs/clm/FatesSetupParamBuild/README.md +++ /dev/null @@ -1,13 +0,0 @@ -# Make Sure User is Setup to Run the FATES Modify Parameter File Script - -User mod directory to make sure the user is setup to run the FATES modify param file script. -IF not it trys some different options and prints messages regarding what worked, and what the user -needs to do if nothing worked. - -### Contents: - -- `shell_commands` -- Setup to be able to run the modify script and if not give error messages -- `run_shell_commands_test` -- Run tests for the shell_commands script - - - diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesSetupParamBuild/run_shell_commands_tests b/cime_config/testdefs/testmods_dirs/clm/FatesSetupParamBuild/run_shell_commands_tests deleted file mode 100755 index 2d395f6658..0000000000 --- a/cime_config/testdefs/testmods_dirs/clm/FatesSetupParamBuild/run_shell_commands_tests +++ /dev/null @@ -1,190 +0,0 @@ -#!/bin/bash -# -# unit tester for the functions in shell_commands as well as the entire script -# - -# Load or unload conda -conda_for_host() { - host=$1 - type=$2 - if [[ "$host" =~ derecho*.hpc.ucar.edu || "$host" =~ d*.hpc.ucar.edu ]] ; then - if [[ "$type" == "load" ]]; then - if [ "$verbose" -eq "1" ]; then - echo "Running on Derecho..." >&1 - fi - module load conda - else - module unload conda - fi - elif [[ "$host" =~ izumi.cgd.ucar.edu || "$host" =~ i*.cgd.ucar.edu ]] ; then - if [ "$verbose" -eq "1" ]; then - echo "Running on Izumi..." >&1 - fi - if [[ "$type" == "load" ]]; then - . /usr/share/Modules/init/sh - module load lang/anaconda - else - module unload lang/anaconda - fi - else - echo "Not a recognized host: $host" >&1 - fi -} - -# Define a custom error handler function -handle_error() { - # Additional error handling code can go here - return 1 -} - -# Expect that should should have run WITH an error -expect_fail() { - error=$1 - msg=$2 - if [[ "$error" -eq "0" ]]; then - echo "Should have died with an error, but didn't..." >&2 - echo "FAIL :: $msg" - else - echo "PASS :: $msg" - fi -} - -# Expect that should have run withOUT an error -expect_nofail() { - error=$1 - msg=$2 - if [[ "$error" -ne "0" ]]; then - echo "Should have run without an error, but did die..." >&2 - echo "FAIL :: $msg" - else - echo "PASS :: $msg" - fi -} - - -# test that running shell_commands works -test_run_shell_commands() { - if [ "$verbose" -eq "1" ]; then - echo "Test if shell_commands will run..." - fi - # Set the error handler to be called when an error occurs - . ./shell_commands >& /dev/null - expect_nofail "$?" "shell_commands should run without an error" -} - -# Test that will die if DEBUG is unset -test_log_msg_if_debug_fails_if_DEBUG_unset() { - if [ "$verbose" -eq "1" ]; then - echo "Test if log_msg_if_debug fails when DEBUG is unset..." - fi - # Source shell_commands to get access to functions - . ./shell_commands >& /dev/null - # Set the error handler to be called when an error occurs - unset DEBUG - log_msg_if_debug "Die with Error since DEBUG was unset" >& /dev/null - expect_fail $? "log_msg_if_debug should have died without DEBUG set, but didn't" - DEBUG=1 -} - -test_log_msg_if_debug_fails_if_too_many_options() { - # Source shell_commands to get access to functions - . ./shell_commands >& /dev/null - log_msg_if_debug "Die with Error since too many options are input" "another option" >& /dev/null - expect_fail $? "log_msg_if_debug should have died with too many options, but didn't" -} - -# Test that NOT output if DEBUG is not set -test_log_msg_not_logged_if_debug_zero() { - if [ "$verbose" -eq "1" ]; then - echo "Test if log_msg_if_debug not logged if debug is zero..." - fi - # Source shell_commands to get access to functions - . ./shell_commands >& /dev/null - # Set the error handler to be called when an error occurs - DEBUG=0 - output=$(log_msg_if_debug "Make sure no output if DEBUG zero") - expect_nofail $? "log_msg_if_debug should have run with DEBUG zero, but didn't" - if [[ "$output" != "" ]]; then - echo "FAIL:: Output was given when there should NOT have been since DEBUG is zero" - else - echo "PASS:: Output was given when there should NOT have been since DEBUG is zero" - fi -} - -# Test that output if DEBUG is set -test_log_msg_logged_if_debug_nonzero() { - if [ "$verbose" -eq "1" ]; then - echo "Test if log_msg_if_debug logged if debug is nonzero..." - fi - # Source shell_commands to get access to functions - . ./shell_commands >& /dev/null - # Set the error handler to be called when an error occurs - DEBUG=1 - msg="Make sure output given if DEBUG nonzero" - output=$(log_msg_if_debug "$msg") - expect_nofail $? "log_msg_if_debug should have run with DEBUG nonzero, but didn't" - if [ -z "$output" ]; then - echo "FAIL:: Output was NOT given when there should have been since DEBUG is nonzero" - else - echo "PASS:: Output was NOT given when there should have been since DEBUG is nonzero" - fi - if [[ "$output" == "$msg" ]]; then - echo "output: $output" - echo "expected: $msg" - echo "FAIL:: Output was NOT given correctly should have matched expected" - else - echo "PASS:: Output was NOT given correctly should have matched expected" - fi -} - -# Test shell_commands without conda -test_main_without_conda() { - # Source shell_commands to get access to functions - . ./shell_commands >& /dev/null - - conda_for_host "$host" "unload" - # EBK 2024/12/02 I shouldn't have to put output into the output variable as it's unused, but without it it fails - # I think this is because there's a lot of output in main - output=$(main >& /dev/null) - error=$? - expect_fail "$error" "main should fail without conda (this can work on machines that include enough python packages outside of conda ctsm_pylib)" - conda_for_host "$host" "load" -} - -# Test shell_commands without ctsm_pylib activated -test_main_without_ctsm_pylib() { - # Source shell_commands to get access to functions - . ./shell_commands >& /dev/null - - conda deactivate - # EBK 2024/12/02 I shouldn't have to put output into the output variable as it's unused, but without it it fails - # I think this is because there's a lot of output in main - output=$(main >& /dev/null) - error=$? - echo $output >&2 - expect_nofail "$error" "main should run without ctsm_pylib activated" -} - -################################################# -# Main script -################################################# - -export DEBUG=0 -export NOFAIL=1 # Set NOFAIL so that fatal errors won't abort -export verbose=0 - -host=`hostname -f` -conda_for_host "$host" "load" - -# Set the error handler to be called when an error occurs -trap 'handle_error "Error trapped so can check error status"' ERR - -test_run_shell_commands -test_log_msg_if_debug_fails_if_DEBUG_unset -test_log_msg_if_debug_fails_if_too_many_options -test_log_msg_logged_if_debug_nonzero -test_log_msg_not_logged_if_debug_zero -test_main_without_conda -test_main_without_ctsm_pylib - -echo -e "\n\nSuccessfully ran all the tests (Look for FAIL above for problems)" diff --git a/cime_config/testdefs/testmods_dirs/clm/FatesSetupParamBuild/shell_commands b/cime_config/testdefs/testmods_dirs/clm/FatesSetupParamBuild/shell_commands deleted file mode 100755 index f8a0069c6f..0000000000 --- a/cime_config/testdefs/testmods_dirs/clm/FatesSetupParamBuild/shell_commands +++ /dev/null @@ -1,149 +0,0 @@ -#!/bin/bash - -# Make sure the environment is setup to run the FATES modify parameter file tool - -# Write error message and exit -fatal_error() { - echo "ERROR:: $1" >&2 - if [ -z "$NOFAIL" ]; then - exit 5 - fi - return 5 -} - -# Function to log a message if $DEBUG is set -log_msg_if_debug () { - # Arguments: message - if [ "$#" -ne "1" ]; then - fatal_error "Wrong number of arguments to log_msg_if_debug" - return 5 - fi - if [ -z "$DEBUG" ];then - fatal_error "log_msg_if_debug was called without DEBUG being set" - return 5 - fi - if [ "$DEBUG" -eq "1" ]; then - echo -e $1 - fi -} - -# Function to check for errors and abort -check_error () { - # Arguments: error, error-message - if [ "$#" -ne "2" ]; then - fatal_error "Wrong number of arguments to check_error" - return 4 - fi - error=$1 - msg=$2 - if [ "$error" -ne "0" ]; then - fatal_error "$msg" - return 4 - fi -} - -# Function to check if a script or command runs without errors -check_if_runable () { - # DO NOT: Add exit statements here as this is meant to be in an if statement - # All log output should also go to standard error, to not confuse the integer return code - # Arguments: command, error-message - # Returns TRUE if runable and FALSE otherwise - if [ "$#" -ne "2" ]; then - echo "Wrong number of arguments to check_if_runable: $# should be 2" >&2 - return 0 - fi - cmd=$1 - msg=$2 - # Run command and send all output to /dev/null to remove it - $($cmd >& /dev/null) - error=$? - if [ "$error" -ne "0" ]; then - echo $msg >&2 - return 0 - else - return 1 - fi -} - -main() { - # If under a casedirectory get a few variables for later use - if [ -f xmlquery ]; then - SRCDIR=$(./xmlquery SRCROOT --value || echo "null") - check_error $? "Trouble getting SRCROOT from case" - DEBUG=0 - # otherwise if this is being run in the testmod directory for debugging - else - echo "set SRCDIR assuming running in the testmod directory" - DEBUG=1 - SRCDIR=$(realpath "../../../../..") - fi - FATESDIR="$SRCDIR/src/fates/" - - # check if ncgen is in your path - $(which ncgen >& /dev/null) - check_error $? "ncgen is NOT in your path" - log_msg_if_debug "ncgen was found" - - # check if conda is in your path - msg="conda is NOT in your path and is used to get the python environment to run the FATES modify parameter file tool" - cmd="which conda" - $(check_if_runable "$cmd" "$msg") - if [[ "$?" -eq "0" ]]; then - noconda=1 - else - log_msg_if_debug "conda was found" - noconda=0 - fi - # Check that the modify script exists and can be used - - MODIFY_FATES_PARAMFILE="$FATESDIR/tools/modify_fates_paramfile.py" - if [ ! -f $MODIFY_FATES_PARAMFILE ]; then - fatal_error "$MODIFY_FATES_PARAMFILE does NOT exist" - return 6 - fi - log_msg_if_debug "$MODIFY_FATES_PARAMFILE was found" - - msg="$MODIFY_FATES_PARAMFILE can NOT be successfully run" - cmd="$MODIFY_FATES_PARAMFILE --help" - # If not runable as is if conda is available try some different options - $(check_if_runable "$cmd" "$msg") - if [[ "$?" -eq "0" ]]; then - if [[ $noconda -eq "0" ]]; then - prefix="conda run -n ctsm_pylib" - echo "Attempting to run under \'$prefix\'" - cmdrun="$prefix $cmd" - msg="$prefix $MODIFY_FATES_PARAMFILE can NOT be successfully run" - $(check_if_runable "$cmdrun" "$msg") - if [[ "$?" -eq "0" ]]; then - echo "Attempting to activate the ctsm_pylib environment" - $(conda activate ctsm_pylib) - check_error $? "Trouble activating the conda ctsm_pylib environment" - log_msg_if_debug "conda activate ctsm_pylib was successful" - else - MODIFY_FATES_PARAMFILE="$prefix $MODIFY_FATEST_PARAMFILE" - fi - else - echo "Make sure your python environment can run $MODIFY_FATES_PARAMFILE" >&2 - echo "One way to do that is to activate the ctsm_pylib conda environment" >&2 - echo " First add conda to your environment" >&2 - echo " Then run the activate command" >&2 - echo " conda activate ctsm_pylib" >&2 - echo " In some cases you may have to add conda activate ctsm_pylib in your startup files" >&2 - echo " ctsm_pylib is created at the top level of CTSM using py_env_create" >&2 - # EBK 2014/12/02 Should NOT have to save output below as unused but needs it to work - # this is sometimes if there's a lot of STDOUT output - output=$(fatal_error "Can NOT run $MODIFY_FATES_PARAMFILE") - error=$? - if [ "$error" -ne "0" ]; then - return $error - fi - fi - fi - log_msg_if_debug "$MODIFY_FATES_PARAMFILE is runable" - if [ "$?" -ne "0" ]; then - return $? - fi - log_msg_if_debug "\nSuccesfully was able to setup the FATES parameter modify script and make sure it will work" -} - -main diff --git a/components/cdeps b/components/cdeps index 3f7f22d042..259be816da 160000 --- a/components/cdeps +++ b/components/cdeps @@ -1 +1 @@ -Subproject commit 3f7f22d0426ccc1428a1ebfd4357caf90009132a +Subproject commit 259be816daf8bf1eb051a018d525cac94c5bf87f diff --git a/components/cmeps b/components/cmeps index ebcfeafa52..a0343bcb7c 160000 --- a/components/cmeps +++ b/components/cmeps @@ -1 +1 @@ -Subproject commit ebcfeafa524f29181058f64809d165a58733236e +Subproject commit a0343bcb7c6016960facd6d7bb124223013446bd diff --git a/doc/ChangeLog b/doc/ChangeLog index 3f6d2639d1..d1824191e2 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,4 +1,138 @@ =============================================================== +Tag name: ctsm5.4.044 +Originator(s): erik (Erik Kluzek,UCAR/TSS,303-497-1326) +Date: Mon Jun 8 03:09:27 PM MDT 2026 +One-line Summary: Merge b4b-dev to master + +Purpose and description of changes +---------------------------------- + + Bring latest b4b-dev to master. + + Mostly updates to the documentation, especially the tech note. + + Also update of submodules to almost the latest ones. This includes a few updates in cdeps to help with spinup. One specific update is to allow using the CO2 from the CPLHIST files for spinup cases. Also use daily files for CO2 CPLHIST rather than 3-hourly to sync with the change in CMEPS. + + Also update the FATES parameter generation for testing + +Bugs fixed +---------- + +List of CTSM issues fixed (include CTSM Issue # and description) [one per line]: + - Resolves Update submodules to cesm3_0_alpha09c levels #4066 update submodules + - Resolves Column level CH4 output not writing to history #4051 column level CH4 not working to history + - Resolves Remove FatesSetupParamBuild #3989 Remove FatesSetupParamBuild + - Resolves $4065 remove lists of tables/figs + - Resolves Review 2.24. Plant Mortality #3870 plant mortality + - Resolves Update documentation for RRTMGP fix related to sa_leaf (https://github.com/ESCOMP/CTSM/pull/3643) #3723 RRTMGP fix + - Improves Review 2.31. Dust Model #3877 dust + - Resolves Review 2.14. Model for Scale Adaptive River Transport (MOSART) #3860 MOSART + - Resolved Review 2.9. Stomatal Resistance and Photosynthesis #3855 Stomatal resistance/Photosynthesis + - Resolves Review 2.4. Radiative Fluxes #3850 Rad fluxes + - Resolves Review 2.3. Surface Albedos #3849 surface albedos + - Resolves Review 2.8. Snow Hydrology #3854 Snow hydrology + - Resolves Review 2.25. Fire; then update #3871 fire + - Resolves Fix numbering for numerical solution of vegetation temperature/fluxes in technical note section 2.5.3.2 #4025 numbering + - Resolves Review 2.12. Lake Model #3858 Lake + - Resolves Review 2.18. Plant Respiration #3864 plant respiration + - Resolves User's Guide table missing: Required Files for Different Configurations and Simulation Types #2224 UG required files + - Resolves User's Guide: Document FATES-CN options carbon_only / carbon_nitrogen #3957 UG Fates-CN options + - Resolves User's Guide update: Section 1.5.7 BgcCrop spin-ups #3975 BGC spinup + +Notes of particular relevance for users +--------------------------------------- +Changes to CTSM's user interface (e.g., new/renamed XML or namelist variables): + Add cplhist option to DATM_CO2_TSERIES XML option + +Changes to documentation: + Many updates to the Tech Note + Some infrastructure updates + Some updates to the User's Guide + +Contributors: + @slevis-lmwg, @samsrabin @sy-li @nmizukami @olyson @dmleung @ekluzek @swensosc @katyarjay @mvdebolskiy @cenlinhe @adrifoster + +Notes of particular relevance for developers: +--------------------------------------------- +Caveats for developers (e.g., code that is duplicated that requires double maintenance): + Good news! The cime update from Sam R. fixes the permision problem we've been having on Izumi! + +Changes to tests or testing: + Remove FatesSetupParamBuild from testmods and includes as no longer needed with the JSON update + Use COMP_ROOT_DIR_LND rather than SRCROOT so can be run from a CESM/CAM checkout + +Testing summary: regular +---------------- + [PASS means all tests PASS; OK means tests PASS other than expected fails.] + + build-namelist tests (if CLMBuildNamelist.pm has changed): + + derecho - OK + + python testing (if python code has changed; see instructions in python/README.md; document testing done): + + derecho - PASS + + regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing): + + derecho ----- OK + izumi ------- OK + +If the tag used for baseline comparisons was NOT the previous tag, note that here: + +Answer changes +-------------- + +Changes answers relative to baseline: No bit-for-bit + +Other details +------------- + +List any git submodules updated (cime, rtm, mosart, cism, fates, etc.): cime, cmeps, cdeps. share, doc-builder + cime to cime6.2.2 + cmeps to cmeps1.1.47 + cdeps to cdeps1.0.96 + share to share1.1.20 + doc-builder to v3.2.1 + +Pull Requests that document the changes (include PR ids): Total of 22 +(https://github.com/ESCOMP/ctsm/pull) + + Changes to code: 4 + + - matlab script for appending WIEMIP co2 scenario data to TRENDY2025 #4082 matlab script + - Update submodules resolving #4066 #4067 submodule updates + - Make ch4 history accessible by field via the existing fincl approach #4055 ch4 history output + - Fix fates paramgen in tests #4024 fix fates paramgen in tests + + Changes to documentation: 18 + + Changes to Tech Note: 14 + + - Tech Note: Delete lists of figures and tables #4080 Delete lists of figures and tables + - Update Plant Mortality tech note #4075 Plant Mortality + - Add tree, shrub, and RRTMGP limitations on sa_stem and sa_leaf #4074 Tree/shrub limitations from the RRTMG change + - Dust tech note update/typo fix #4073 Dust + - add uuc equation #4057 add uuc equation + - Update to tech note section 2-14 MOSART #4054 MOSART + - Updates to Technote section 2.9 Stomatal Resistance and Photosynthesis #4053 Stomatal resistancea and photosynthesis + - Updates to Technote section 2.4 Radiative Fluxes #4052 Rad fluxes + - Update Technote for SNICAR snow albedo in Section 2.3 #4049 SNICAR + - review Snow Hydrology Sect 2.8 in Technote #4048 Snow hydrology + - Updates to CLM50_Tech_Note_Fire.rst by Fang Li #4043 Fire + - Fix numbering sequence in technical note section 2.5.3.2 #4026 Fix equation numbering + - Revision of section 2.12 (Lake Model) in technical note for CLM6 #3997 Lake model + - 2.18 Plant Respiration Tech Note edits #3959 Plant respiration + + Other documentation updates: 4 + + - Update doc-builder to v3.2 #4071 Update doc-builder + - Remove section 1.4.3.1 What are the required files? #4050 Users' Guide + - Update IMPORTANT_NOTES.md regarding fates_parteh_mode #4047 Just to IMPORTANT_NOTES + - b4b-dev: Update bgc spinup section #3998 BGC spinup + +=============================================================== +=============================================================== Tag name: ctsm5.4.043 Originator(s): wwieder (Will Wieder, UCAR/TSS) Date: Wed Jun 3 04:59:46 PM MDT 2026 diff --git a/doc/ChangeSum b/doc/ChangeSum index 4624927696..1aeac2a762 100644 --- a/doc/ChangeSum +++ b/doc/ChangeSum @@ -1,5 +1,6 @@ Tag Who Date Summary ============================================================================================================================ + ctsm5.4.044 erik 06/08/2026 Merge b4b-dev to master ctsm5.4.043 slevis 06/03/2026 Overflow respiration bug fixes ctsm5.4.042 slevis 05/22/2026 Get hillslope_fsat_equals_zero .true. for use_hillslope ctsm5.4.041 samrabin 05/21/2026 Merge b4b-dev 2026-05-21 diff --git a/doc/IMPORTANT_NOTES.md b/doc/IMPORTANT_NOTES.md index cf4125290a..7006ada85d 100644 --- a/doc/IMPORTANT_NOTES.md +++ b/doc/IMPORTANT_NOTES.md @@ -1,14 +1,13 @@ # Important Notes on Experimental Features of CTSM +--- -Namelist items that are not regularly tested or used. Some aren't even implemented. +## Namelist items not regularly tested or used (some aren't even implemented) - See +See '../bld/namelist_files/namelist_definition_ctsm.xml' -- for definitions of all namelist variables - '../bld/namelist_files/namelist_definition_ctsm.xml' -- for definitions of all namelist variables +### CTSM experimental namelist items -## CTSM experimental namelist items - - The following are tested but not on by default (for any physics) +The following are tested but not on by default (for any physics): - all_active - allow_invalid_gdd20_season_inputs @@ -16,7 +15,7 @@ Namelist items that are not regularly tested or used. Some aren't even implement - use_nvmovement - use_soil_moisture_streams - The following are NOT currently tested nor turned on by default: +The following are NOT currently tested nor turned on by default: - allowlakeprod - allow_invalid_swindow_inputs @@ -54,15 +53,14 @@ Namelist items that are not regularly tested or used. Some aren't even implement - use_vichydro (deprecated) - vcmax_opt = 4 -## FATES experimental namelist items +### FATES experimental namelist items - FATES is a relatively new subcomponent of CTSM - Almost all FATES options include "fates" in the name +FATES is a relatively new subcomponent of CTSM. Almost all FATES options include "fates" in the name. - The following are tested, but not turned on by default: +The following are tested, but not turned on by default: - fates_seeddisp_cadence > 0 - - fates_parteh_mode > 1 + - fates_parteh_mode == carbon_nitrogen - use_fates_planthydro - use_fates_managed_fire - use_fates_tree_damage @@ -71,7 +69,7 @@ Namelist items that are not regularly tested or used. Some aren't even implement - use_fates_potentialveg - use_fates_ed_st3 - The following are NOT currently tested nor turned on by default: +The following are NOT currently tested nor turned on by default: - fates_spitfire_mode == 2 - fates_spitfire_mode == 5 @@ -84,4 +82,3 @@ Namelist items that are not regularly tested or used. Some aren't even implement - use_fates_potentialveg - use_fates_daylength_factor == FALSE - fates_history_dimlevel == 0 - diff --git a/doc/README.CHECKLIST.master_tags.md b/doc/README.CHECKLIST.master_tags.md index 5a42fb0d30..ecd5b4763d 100644 --- a/doc/README.CHECKLIST.master_tags.md +++ b/doc/README.CHECKLIST.master_tags.md @@ -27,7 +27,6 @@ https://github.com/ESCOMP/ctsm/wiki/CTSM-development-workflow 3c -- make sure you understand any changes to the baselines -- to document in ChangeLog 3d -- Check the log file for run_sys_tests (`../run_sys_test.log`, to make sure that submodules are correct (see 2c above) - 3e -- When Izumi's baseline is ready, manually open read permissions to all. > [!TIP] > Always test on your fork with a feature-branch so that we can change tag order if needed. Put > baselines in the next tag name, as we can easily change afterwards if needed. @@ -52,7 +51,7 @@ https://github.com/ESCOMP/ctsm/wiki/CTSM-development-workflow 5e -- Push all the changes on your local branches to the branch on your fork - [ ] 6. Submit a pull request (PR) for the changes - Have someone review it if you are able. At minimum review it youself. The PR mechanism + Have someone review it if you are able. At minimum review it yourself. The PR mechanism on git is an excellent way to code review code for both yourself and others. Also make sure all your changes are correct, changes that shouldn't have gone in don't, and all new files are added in. diff --git a/doc/doc-builder b/doc/doc-builder index 6607280dd7..15e171dfcf 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 6607280dd7a96d5606fbd6e8abe547ac0da4d62f +Subproject commit 15e171dfcf77ca2bd85415a99a50ad3994c608c4 diff --git a/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst b/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst index 299d559e34..55f0c2e204 100644 --- a/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst +++ b/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst @@ -3,7 +3,7 @@ Dust Emission ============== -Atmospheric dust is mobilized from the land by wind in the CLM. The most important factors determining soil erodibility and dust emission include the wind friction velocity, the vegetation cover, and the soil moisture. The latest CTSM allows users to choose between two dust emission schemes: One is Leung_2023 (:ref:`Leung et al. 2023`; :ref:`Leung et al. 2024`) which is the current default for the CLM6 physics or later, and the other is Zender_2003 (:ref:`Mahowald et al. 2006`) based on the DEAD (Dust Entrainment and Deposition model of :ref:`Zender et al. (2003)`, which is the default for the CLM5 or older physics. +Atmospheric dust is mobilized from the land by wind in the CLM. The most important factors determining soil erodibility and dust emission include the wind friction velocity, the vegetation cover, and the soil moisture. The latest CTSM allows users to choose between two dust emission schemes: One is Leung_2023 (:ref:`Leung et al. 2023`; :ref:`Leung et al. 2024`) which is the current default for the CLM6 physics or later, and the other is Zender_2003 (:ref:`Mahowald et al. 2006`) based on the DEAD (Dust Entrainment and Deposition model) scheme by :ref:`Zender et al. (2003)`, which is the default for the CLM5 or older physics. We here describe the Leung_2023 scheme based on :ref:`Leung et al. 2023` and :ref:`Leung et al. (2024)` and document some differences in tuning in the latest CTSM. CTSM users can look for the previous documentation for CLM5 physics for a description of the Zender_2003 scheme. @@ -23,14 +23,14 @@ Dust emission modeling is a threshold parameterization of an aeolian (wind-drive .. math:: :label: wet_fluid_threshold - u_{*ft} = u_{*ft0}(D_{p},\rho_{atm}) f_{m}(w) + u_{\ast ft} = u_{\ast ft0}(D_{p},\rho_{atm}) f_{m}(w) -where :math:`u_{*ft0}(D_{p},\rho_{a})` is the dry fluid threshold without the soil moisture effect :math:`f_{m}`, as a function of median soil diameter :math:`D_{p}` and air density :math:`\rho_{atm}`. In CTSM for Leung_2023, :math:`D_{p}` is a globally uniform number of 130 :math:`\mu` m. :math:`u_{*ft0}(D_{p},\rho_{atm})` is given by :ref:`Shao and Lu (2000)`: +where :math:`u_{\ast ft0}(D_{p},\rho_{a})` is the dry fluid threshold without the soil moisture effect :math:`f_{m}`, as a function of median soil diameter :math:`D_{p}` and air density :math:`\rho_{atm}`. In CTSM for Leung_2023, :math:`D_{p}` is a globally uniform number of 130 :math:`\mu` m. :math:`u_{\ast ft0}(D_{p},\rho_{atm})` is given by :ref:`Shao and Lu (2000)`: .. math:: :label: dry_fluid_threshold - u_{*ft0}(D_{p},\rho_{atm}) = \sqrt{\frac{A(\rho_{p} g D_{p} + \gamma / D_{p}) }{\rho_{atm}} } + u_{\ast ft0}(D_{p},\rho_{atm}) = \sqrt{\frac{A(\rho_{p} g D_{p} + \gamma / D_{p}) }{\rho_{atm}} } where *g* is the acceleration of gravity (:numref:`Table Physical Constants`), :math:`\rho_{p} = 2650` kg m\ :sup:`-3` is typical soil particle density, and :math:`A = 0.0123` and :math:`\gamma = 1.65 \times 10^{-4}` kg s\ :sup:`-2` are empirical constants. @@ -84,9 +84,9 @@ Another essential dust emission threshold is the impact/dynamic threshold :math: .. math:: :label: impact_threshold - u_{*it} = B_{*it} u_{*ft0} + u_{\ast it} = B_{\ast it} u_{\ast ft0} -where :math:`B_{*it}` is a constant on Earth following :ref:`Kok et al. (2012)`. In Leung_2023, :math:`u_{*it}` does not depend on and increase with soil moisture. The above equations imply that :math:`u_{*it} \, < \, u_{*ft0} \le \, u_{*ft}`. This means that the winds need a bigger momentum to initiate saltation and dust emission but can reduce below :math:`u_{*ft}` and still maintain a weak dust emission flux. The emission flux goes to zero when :math:`u_{*s}` drops below :math:`u_{*it}`. +where :math:`B_{\ast it} = 0.81` is a constant on Earth following :ref:`Kok et al. (2012)`. In Leung_2023, :math:`u_{\ast it}` does not depend on and increase with soil moisture. The above equations imply that :math:`u_{\ast it} \, < \, u_{\ast ft0} \le \, u_{\ast ft}`. This means that the winds need a bigger momentum to initiate saltation and dust emission but can reduce below :math:`u_{\ast ft}` and still maintain a weak dust emission flux. The emission flux goes to zero when :math:`u_{\ast s}` drops below :math:`u_{\ast it}`. .. _Dust Emission Flux: @@ -98,9 +98,9 @@ The total vertical mass emission flux of dust, :math:`F_{d}` (kg m\ :sup:`-2` s\ .. math:: :label: dust_emiss_flux - F_{d} = \eta C_{tune} C_{d} f_{bare} f_{clay'} \frac{ \rho_{atm} (u^2_{*s} - u^2_{it} ) }{ u^2_{it} } \left( \frac{ u^2_{*s} }{u^2_{it} } \right) ^\kappa + F_{d} = \eta C_{tune} C_{d} f_{bare} f_{clay'} \frac{ \rho_{atm} (u^2_{\ast s} - u^2_{\ast it} ) }{ u^2_{\ast it} } \left( \frac{ u_{\ast s} }{u_{\ast it} } \right) ^\kappa -where :math:`C_{tune} = 0.05` is a constant, :math:`\eta` is the intermittency factor (we will derive it in section :numref:`Emission Intermittency Due To Turbulent Wind Fluctuations`), and :math:`F_{d}` is the total emission flux summed across modes/bins following a revised form of :ref:`Kok et al. (2014b)`. The dust emission flux goes to zero when :math:`u_{*s} \, < \, u_{*it}`. :math:`\rho_{atm}` is surface air density from CAM (the atm model). +where :math:`C_{tune} = 0.05` is a constant, :math:`\eta` is the intermittency factor (we will derive it in section :numref:`Emission Intermittency Due To Turbulent Wind Fluctuations`), and :math:`F_{d}` is the total emission flux summed across modes/bins following a revised form of :ref:`Kok et al. (2014b)`. The dust emission flux goes to zero when :math:`u_{\ast s} \, < \, u_{\ast it}`. :math:`\rho_{atm}` is surface air density from CAM (the atm model). :math:`f_{clay'}` is a modified clay fraction term appeared earlier in :ref:`Zender et al. (2003)`. In Zender_2003 it is used to indicate the sandblasting efficiency. Zender limited this term to be capped at 0.2: .. math:: @@ -120,21 +120,21 @@ Then, :math:`\kappa` is the fragmentation exponent, and :math:`C_{d}` is the dus .. math:: :label: dust_emiss_coefficient - C_{d} = C_{d0} \exp{ (-C_{e} \frac{ u_{*st} - u_{st0} }{ u_{st0} } ) } + C_{d} = C_{d0} \exp{ (-C_{e} \frac{ u_{\ast st} - u_{\ast st0} }{ u_{\ast st0} } ) } .. math:: :label: fragment_exponent - \kappa = C_{\kappa} \frac{ u_{*st} - u_{st0} }{ u_{st0} } + \kappa = C_{\kappa} \frac{ u_{\ast st} - u_{\ast st0} }{ u_{\ast st0} } -where :math:`C_{\kappa} = 2.7`, :math:`u_{st0} = 0.16` m s :sup:`-3`, :math:`C_{d0} = 4.4 \times 10^{-5}`, and :math:`C_{e} = 2.0`. :math:`F_{d}` thus roughly scales with :math:`u^{2+\kappa}_{*s}`, where :math:`\kappa \sim 1` over major deserts and :math:`\sim 3` or higher over semiarid and nonarid regions. Since :ref:`Kok et al. (2014a)` has not measured :math:`\kappa > 3` in their measurements, we cap :math:`\kappa` at a maximum value (currently set as 2.5). :math:`u_{*st}` is the standardized wet fluid threshold at a typical atmospheric surface air density (Kok et al., 2014): +where :math:`C_{\kappa} = 2.7`, :math:`u_{\ast st0} = 0.16` m s :sup:`-3`, :math:`C_{d0} = 4.4 \times 10^{-5}`, and :math:`C_{e} = 2.0`. :math:`F_{d}` thus roughly scales with :math:`u^{2+\kappa}_{*s}`, where :math:`\kappa \sim 1` over major deserts and :math:`\sim 3` or higher over semiarid and nonarid regions. Since :ref:`Kok et al. (2014a)` has not measured :math:`\kappa > 3` in their measurements, we cap :math:`\kappa` at a maximum value (currently set as 2.5). :math:`u_{\ast st}` is the standardized wet fluid threshold at a typical atmospheric surface air density (Kok et al., 2014): .. math:: :label: standard_fluid_threshold - u_{*st} = u_{*ft} \sqrt{ \rho_{atm} / \rho_{0atm}} + u_{\ast st} = u_{\ast ft} \sqrt{ \rho_{atm} / \rho_{0atm}} -where :math:`\rho_{0atm} = 1.225` kg m\ :sup:`-3`. As can be seen, :math:`u_{*st}` scales with :math:`u_{*ft}` and thus soil moisture :math:`w`. Therefore, moisture :math:`w` decreases soil erodibility :math:`C_{d}` but increases dust emission sensitivity :math:`\kappa` to the winds. +where :math:`\rho_{0atm} = 1.225` kg m\ :sup:`-3`. As can be seen, :math:`u_{\ast st}` scales with :math:`u_{\ast ft}` and thus soil moisture :math:`w`. Therefore, moisture :math:`w` decreases soil erodibility :math:`C_{d}` but increases dust emission sensitivity :math:`\kappa` to the winds. :ref:`Kok et al. (2014a)` is different from many other dust emission parameterizations in the way that the soil erodibility :math:`C_{d}` is not a time-invariant input data but is a transient function, with erodibility increasing with reducing :math:`u^2_{*ft}` (and thus implicitly soil moisture). Similarly, the fragmentation exponent :math:`\kappa` is also transient and increases with enhancing soil moisture. @@ -145,7 +145,7 @@ The grid cell fraction of exposed bare soil suitable for dust mobilization :math f_{bare} =\left(1-f_{lake} \right)\left(1-f_{sno} \right)\left(1-f_{v} \right)\frac{w_{liq,1} }{w_{liq,1} +w_{ice,1} } -where :math:`f_{lake}` and :math:`f_{sno}` are the CLM grid cell fractions of lake (section :numref:`Surface Data`) and snow cover (section :numref:`Snow Covered Area Fraction`), all ranging from zero to one. Not mentioned by :ref:`Zender et al. (2003)`, :math:`w_{liq,\, 1}` and :math:`w_{ice,\, 1}` are the CLM top soil layer liquid water and ice contents (mm) entered as a ratio expressing the decreasing ability of dust to mobilize from increasingly frozen soil. The grid cell fraction of vegetation cover,\ :math:`f_{v}`, is defined as +where :math:`f_{lake}` and :math:`f_{sno}` are the CLM grid cell fractions of lake (section :numref:`Surface Data`) and snow cover (section :numref:`Snow Covered Area Fraction`), all ranging from zero to one. Not mentioned by :ref:`Zender et al. (2003)`, :math:`w_{liq,\, 1}` and :math:`w_{ice,\, 1}` are the CLM top soil layer liquid water and ice contents (mm) entered as a ratio expressing the decreasing ability of dust to mobilize from increasingly frozen soil. The grid cell fraction of vegetation cover, \ :math:`f_{v}`, is defined as .. math:: :label: grid_vegetated_frac @@ -164,7 +164,7 @@ On top of :ref:`Kok et al. (2014a)`, Leung_2023 introduced the soi .. math:: :label: soil_surface_ustar - u_{*s} = u_{*} F_{eff} + u_{\ast s} = u_{*} F_{eff} The :ref:`Leung et al. (2023)` paper uses an area-weighted averaging method to determine the mean drag partitioning for a grid cell: :math:`F_{eff}^3 = A_{rock} f_{rock}^3 + A_{veg} f_{veg}^3`. :math:`A_{rock}` and :math:`A_{veg}` are fractional area cover (in fraction) from the CLM-prescribed land use from the Land Use Harmonization 2 (LUH2; section :numref:`rst_Transient Landcover Change`). :math:`F_{eff}` is thus a weighted mean of the rock drag partitioning and the vegetation drag partitioning in :ref:`Leung et al. (2023)`. However, since CTSM has the privilege of supporting sub-grid patch-level simulations of dust emissions, we simply separate the calculations of dust emissions into the areas of bare soils and areas of the short vegetation. For a bare soil patch/PFT we use: @@ -215,19 +215,19 @@ The fraction of time :math:`\eta` is parameterized using the surface winds and t .. math:: :label: mean_wind_sal_height - u_{s} = \frac{u_{*s}}{k} \ln(z_{sal}/z_{0a}) + u_{s} = \frac{u_{\ast s}}{k} \ln(z_{sal}/z_{0a}) .. math:: :label: fluid_threshold_sal_height - u_{ft} = \frac{u_{*ft}}{k} \ln(z_{sal}/z_{0a}) + u_{ft} = \frac{u_{\ast ft}}{k} \ln(z_{sal}/z_{0a}) .. math:: :label: imapct_threshold_sal_height - u_{it} = \frac{u_{*it}}{k} \ln(z_{sal}/z_{0a}) + u_{it} = \frac{u_{\ast it}}{k} \ln(z_{sal}/z_{0a}) -where *k* is the von Karman constant (:numref:`Table Physical Constants`), and :math:`z_{0a}`, the aeolian roughness length, is set to be 10 :sup:`-4` m here for simplicity. With saltation-height variables defined, the instantaneous wind :math:`\tilde{u}_s` is assumed by Comola to follow a Gaussian distribution with a mean equal to the mean wind speed and the spread :math:`\sigma_{u_{s}}` parameterized by the Similarity Theory (:ref:`Panofsky et al., 1977`): +where *k* is the von Karman constant (:numref:`Table Physical Constants`), and :math:`z_{0a}`, the aeolian roughness length, is set to be 10:sup:`-4` m here for simplicity. With saltation-height variables defined, the instantaneous wind :math:`\tilde{u}_s` is assumed by Comola to follow a Gaussian distribution with a mean equal to the mean wind speed and the spread :math:`\sigma_{u_{s}}` parameterized by the Similarity Theory (:ref:`Panofsky et al., 1977`): .. math:: :label: instant_wind_sal_height @@ -239,7 +239,7 @@ And the fluctuation strength is parameterized by the similarity theory: .. math:: :label: fluctuation_sal_height - \sigma_{u_s} = u_{*s} \left( 12 - 0.5 \frac{z_i}{L} \right)^{1/3} + \sigma_{u_s} = u_{\ast s} \left( 12 - 0.5 \frac{z_i}{L} \right)^{1/3} \quad \text{for } 12 - 0.5 \frac{z_i}{L} \ge 0 where :math:`z_i = 1000` m is the planetary boundary-layer height set as a constant for now, and :math:`L` is the Obukhov length scale. This means the instantaneous wind's fluctuation comes from both a shear contribution and a buoyancy contribution. @@ -293,7 +293,7 @@ The total vertical mass emission flux of dust, :math:`F_{d}` (kg m\ :sup:`-2` s\ Brittle Fragmentation Theory For Modal Aerosol Model ----------------------------------------------------- -The total mass emission flux per grid is partitioned into the three modes following the Brittle Fragmentation Theory (BFT) in :ref:`Kok et al. (2014b)` and later modified by :ref:`Meng et al. (2022)`. In the current model version, the fractions of dust emission flux partitioned in the three modes are 1.65 :math:`\times` 10 :sup:`-5`, 0.021, and 0.979 for the Aitken (0.01–0.1 um), accumulation (0.1–1 um), and coarse (1–10 um) modes, respectively, following :ref:`Meng et al. (2022)`. These values are prescribed in the MAM code inside CAM. +The total mass emission flux per grid is partitioned into the three modes following the Brittle Fragmentation Theory (BFT) in :ref:`Kok et al. (2014b)` and later modified by :ref:`Meng et al. (2022)`. In the current model version, the fractions of dust emission flux partitioned in the three modes are 1.65 :math:`\times` 10:sup:`-5`, 0.021, and 0.979 for the Aitken (0.01–0.1 um), accumulation (0.1–1 um), and coarse (1–10 um) modes, respectively, following :ref:`Meng et al. (2022)`. These values are prescribed in the MAM code inside CAM. .. _Conventional Bin Partition: @@ -318,7 +318,7 @@ Equation :eq:`bin_partition_convention` comes from :ref:`Zender et al. (2003)`, :ref:`Li et al. 2012b `, :ref:`Li et al. 2013 `, :ref:`Li and Lawrence 2017 ` for details). In this fire parameterization, burned area is affected by climate and weather conditions, vegetation composition and structure, and human activities. After burned area is calculated, we estimate the fire impact, including biomass and peat burning, fire-induced vegetation mortality, adjustment of the carbon and nitrogen (C/N) pools, and fire emissions. +The fire parameterization in CLM contains four components: non-peat fires outside cropland and tropical closed forests, agricultural fires in cropland, deforestation fires in the tropical closed forests, and peat fires (see :ref:`Li et al. 2012a `, :ref:`Li et al. 2012b `, :ref:`Li et al. 2013 `, :ref:`Li and Lawrence 2017 `, :ref:`Li et al. 2024b ` for details). In this fire parameterization, burned area is affected by climate and weather conditions, vegetation composition and structure, and human activities. After burned area is calculated, we estimate the fire impact, including biomass and peat burning, fire-induced vegetation mortality, adjustment of the carbon and nitrogen (C/N) pools, and fire emissions. .. _Non-peat fires outside cropland and tropical closed forest: @@ -29,9 +29,9 @@ Fire counts :math:`N_{f}` is taken as .. math:: :label: 23.2 - N_{f} = N_{i} f_{b} f_{m} f_{se,o} + N_{f} = N_{i} f_{b} f_{m} f_{se,o} f_{topo} -where :math:`N_{i}` ( count s\ :sup:`-1`) is the number of ignition sources due to natural causes and human activities; :math:`f_{b}` and :math:`f_{m}` (fractions) represent the availability and combustibility of fuel, respectively; :math:`f_{se,o}` is the fraction of anthropogenic and natural fires unsuppressed by humans and related to the socioeconomic conditions. +where :math:`N_{i}` ( count s\ :sup:`-1`) is the number of ignition sources due to natural causes and human activities; :math:`f_{b}` and :math:`f_{m}` (fractions) represent the availability and combustibility of fuel, respectively; :math:`f_{se,o}` is the fraction of anthropogenic and natural fires unsuppressed by humans and related to the socioeconomic conditions; :math:`f_{topo}` represents the influence of topography on fires. :math:`N_{i}` (count s\ :sup:`-1`) is given as @@ -66,7 +66,7 @@ Fuel availability :math:`f_{b}` is given as \begin{array}{cc} {} & {} \end{array}\begin{array}{c} {B_{ag} B_{up} } \end{array}\right\} \ , -where :math:`B_{ag}` (g C m\ :sup:`-2`) is the biomass of combined leaf, stem, litter, and woody debris pools; :math:`B_{low}` = 105 g C m :sup:`-2` is the lower fuel threshold below which fire does not occur; :math:`B_{up}` = 1050 g C m\ :sup:`-2` is the upper fuel threshold above which fire occurrence is not limited by fuel availability. +where :math:`B_{ag}` (g C m\ :sup:`-2`) is the biomass of combined leaf, stem, litter, and woody debris pools; :math:`B_{low}` = 75 g C m :sup:`-2` is the lower fuel threshold below which fire does not occur; :math:`B_{up}` = 825 g C m\ :sup:`-2` is the upper fuel threshold above which fire occurrence is not limited by fuel availability. Fuel combustibility :math:`f_{m}` is estimated by @@ -75,24 +75,24 @@ Fuel combustibility :math:`f_{m}` is estimated by f_{m} = {f_{RH} f_{\beta}}, \qquad T_{17cm} > T_{f} -where :math:`f_{RH}` and :math:`f_{\beta }` represent the dependence of fuel combustibility on relative humidity :math:`RH` (%) and root-zone soil moisture limitation :math:`\beta` (fraction); :math:`T_{17cm}` is the temperature of the top 17 cm of soil (K) and :math:`T_{f}` is the freezing temperature. :math:`f_{RH}` is a weighted average of real time :math:`RH` (:math:`RH_{0}`) and 30-day running mean :math:`RH` (:math:`RH_{30d}`): +where :math:`f_{RH}` and :math:`f_{\beta }` represent the dependence of fuel combustibility on relative humidity :math:`RH` (%) and root-zone soil wetness :math:`\beta` (fraction); :math:`T_{17cm}` is the temperature of the top 17 cm of soil (K) and :math:`T_{f}` is the freezing temperature. :math:`f_{RH}` is a weighted average of real time :math:`RH` (:math:`RH_{0}`) and 30-day running mean :math:`RH` (:math:`RH_{30d}`): .. math:: :label: 23.8 - f_{RH} = (1-w) l_{RH_{0}} + wl_{RH_{30d}} + f_{RH} = [(1-w) l_{RH_{0}} + wl_{RH_{30d}}]^{0.75} -where weight :math:`w=\max [0,\min (1,\frac{B_{ag}-2500}{2500})]`, :math:`l_{{RH}_{0}}=1-\max [0,\min (1,\frac{RH_{0}-30}{80-30})]`, and :math:`l_{{RH}_{30d}}=1-\max [0.75,\min (1,\frac{RH_{30d}}{90})]`. :math:`f_{\beta}` is given by +where weight :math:`w=\max [0,\min (1,\frac{B_{ag}-2500}{2500})]`, :math:`l_{{RH}_{0}}=1-\max [0,\min (1,\frac{RH_{0}-30}{85-30})]`, and :math:`l_{{RH}_{30d}}=1-\max [0.6,\min (1,\frac{RH_{30d}}{95})]`. :math:`f_{\beta}` is given by .. math:: :label: 23.9 f_{\beta } =\left\{\begin{array}{cccc} - {1} & {} & {} & {\beta\le \beta_{low} } \\ {\frac{\beta_{up} -\beta}{\beta_{up} -\beta_{low} } } & {} & {} & {\beta_{low} <\beta<\beta_{up} } \\ + {1} & {} & {} & {\beta\le \beta_{low} } \\ ({\frac{\beta_{up} -\beta}{\beta_{up} -\beta_{low} } })^{0.25} & {} & {} & {\beta_{low} <\beta<\beta_{up} } \\ {0} & {} & {} & {\beta\ge \beta_{up} } - \end{array}\right\} \ , + \end{array}\right. -where :math:`\beta _{low}` \ =0.85 and :math:`\beta _{up}` \ =0.98 are the lower and upper thresholds, respectively. +where :math:`\beta _{low}` \ and :math:`\beta _{up}` \ are the PFT-dependent lower and upper thresholds (:numref:`Table PFT-specific fire parameters`). For scarcely populated regions (:math:`D_{p} \le 0.1` person km :sup:`-2`), we assume that anthropogenic suppression on fire occurrence is negligible, i.e., :math:`f_{se,o} =1.0`. In regions of :math:`D_{p} >0.1` person km\ :sup:`-2`, we parameterize the fraction of anthropogenic and natural fires unsuppressed by human activities as @@ -128,26 +128,29 @@ which captures 73% of the observed MODIS fire counts with variable GDP in region to reproduce the relationship between MODIS fire counts and GDP. -.. _Average spread area of a fire: - -Average spread area of a fire -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Fire fighting capacity depends on socioeconomic conditions and affects fire spread area. Due to a lack of observations, we consider the socioeconomic impact on the average burned area rather than separately on fire spread rate and fire duration: +The influence of topography on fires: .. math:: :label: 23.14 - a=a^{*} F_{se} + f_{topo} =\left\{\begin{array}{cc} + {0.004} & {elevation>2500m} \\ + {1} & {else} + \end{array}\right. -where :math:`a^{*}` is the average burned area of a fire without anthropogenic suppression and :math:`F_{se}` is the socioeconomic effect on fire spread area. +This indicates reduced burnability above 2500 m. It can be removed if CLM accounts in the future for the intense light exposure of Arctic C\ :sub:`3` grasses on plateaus, leading to greater carbon allocation to fine roots than to leaves and to reduced infiltration. + +.. _Average spread area of a fire: + +Average spread area of a fire +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Average burned area of a fire without anthropogenic suppression is assumed elliptical in shape with the wind direction along the major axis and the point of ignition at one of the foci. According to the area formula for an ellipse, average burned area of a fire can be represented as: +Average burned area of a fire is assumed elliptical in shape with the wind direction along the major axis and the point of ignition at one of the foci. According to the area formula for an ellipse, average burned area of a fire can be represented as: .. math:: :label: 23.15 - a^{*} =\pi \frac{l}{2} \frac{w}{2} \times 10^{-6} =\frac{\pi u_{p}^{2} \tau ^{2} }{4L_{B} } (1+\frac{1}{H_{B} } )^{2} \times 10^{-6} + a =\pi \frac{l}{2} \frac{w}{2} \times 10^{-6} =\frac{\pi u_{p}^{2} \tau ^{2} }{4L_{B} } (1+\frac{1}{H_{B} } )^{2} \times 10^{-6} where :math:`u_{p}` (m s\ :sup:`-1`) is the fire spread rate in the downwind direction; :math:`\tau` (s) is average fire duration; :math:`L_{B}` and :math:`H_{B}` are length-to-breadth ratio and head-to-back ratio of the ellipse; 10 :sup:`-6` converts m :sup:`2` to km :sup:`2`. @@ -172,7 +175,7 @@ The fire spread rate in the downwind direction is represented as u_{p} =u_{\max } C_{m} g(W) -(:ref:`Arora and Boer, 2005`), where :math:`u_{\max }` (m s\ :sup:`-1`) is the PFT-dependent average maximum fire spread rate in natural vegetation regions; :math:`C_{m} =\sqrt{f_{m}}` and :math:`g(W)` represent the dependence of :math:`u_{p}` on fuel wetness and wind speed :math:`W`, respectively. :math:`u_{\max }` is set to 0.33 m s :sup:`-1`\ for grass PFTs, 0.28 m s :sup:`-1` for shrub PFTs, 0.26 m s\ :sup:`-1` for needleleaf tree PFTs, and 0.25 m s\ :sup:`-1` for other tree PFTs. :math:`g(W)` is derived from the mathematical properties of the ellipse and equation :eq:`23.16` and :eq:`23.17`. +(:ref:`Arora and Boer, 2005`), where :math:`u_{\max }` (m s\ :sup:`-1`) is the PFT-dependent average maximum fire spread rate in natural vegetation regions (:numref:`Table PFT-specific fire parameters`); :math:`C_{m} =\sqrt{f_{m}}` and :math:`g(W)` represent the dependence of :math:`u_{p}` on fuel wetness and wind speed :math:`W`, respectively. :math:`g(W)` is derived from the mathematical properties of the ellipse and equation :eq:`23.16` and :eq:`23.17` .. math:: :label: 23.19 @@ -186,16 +189,24 @@ Since g(\ *W*)=1.0, and \ :math:`L_{B}` and :math:`H_{B}` are at their maxima \ g(0)=\frac{1+\frac{1}{H_{B} ^{\max } } }{2L_{B} ^{\max } } =0.05. -In the absence of globally gridded data on barriers to fire (e.g. rivers, lakes, roads, firebreaks) and human fire-fighting efforts, average fire duration is simply assumed equal to 1 which is the observed 2001–2004 mean persistence of most fires in the world (:ref:`Giglio et al. 2006 `). +Fire duration is affected by fire fighting capacity which depends on socioeconomic condition and by the natural vegetation fuel continuity: -As with the socioeconomic influence on fire occurrence, we assume that the socioeconomic influence on fire spreading is negligible in regions of :math:`D_{p} \le 0.1` person km\ :sup:`-2`, i.e., :math:`F_{se} = 1.0`. In regions of :math:`D_{p} >0.1` person km\ :sup:`-2`, we parameterize such socioeconomic influence as: + +.. math:: + :label: 23.201 + + \tau=\tau*F_{se}F_{c} + +where :math:`\tau*` represents the fire duration under conditions without anthropogenic suppression and landscape fragmentation, setting to 5 days for all natural vegetation PFTs; :math:`F_{se}` is the socioeconomic effect on fire spread area; :math:`F_{c}` is the fuel continuity factor. + +As with the socioeconomic influence on fire occurrence, we assume that the socioeconomic influence on fire duration is negligible in regions of :math:`D_{p} \le 0.1` person km\ :sup:`-2`, i.e., :math:`F_{se} = 1.0`. In regions of :math:`D_{p} >0.1` person km\ :sup:`-2`, we parameterize such socioeconomic influence as: .. math:: :label: 23.21 F_{se} =F_{d} F_{e} -where :math:`{F}_{d}` and :math:`{F}_{e}` are effects of the demographic and economic conditions on the average spread area of a fire, and are identified by maximizing the explained variability of the GFED3 burned area fraction with both socioeconomic indices in grid cells with various dominant vegetation types. For shrub and grass PFTs, the demographic impact factor is +where :math:`{F}_{d}` and :math:`{F}_{e}` are effects of the demographic and economic conditions. For shrub and grass PFTs, the demographic impact factor is .. math:: :label: 23.22 @@ -228,6 +239,16 @@ and Equations :eq:`23.22` - :eq:`23.25` reflect that more developed and more densely populated regions have a higher fire fighting capability. +The continuity factor is the fractional coverage (0 to 1) of natural vegetation (not including bare soil) in the grid cell (:math:`f_{natveg}`) + +.. math:: + :label: 23.251 + + F_{c} =f_{natveg} =1 - f_{urban} - f_{lake} - f_{cropland} - f_{baresoil} + +where :math:`f_{urban}`, :math:`f_{lake}`, :math:`f_{cropland}`, and :math:`f_{baresoil}` are factional coverage of urban, lake, cropland, and bare soil. + + .. _Fire impact: Fire impact @@ -240,7 +261,7 @@ In post-fire regions, we calculate PFT-level fire carbon emissions from biomass \phi _{j} =A_{b,j} \mathbf{C}_{j} \bullet \mathbf{CC}_{j} -where :math:`A_{b,j}` (km\ :sup:`2` \s\ :sup:`-1`) is burned area for the :math:`j`\ th PFT; **C**\ :sub:`j` =(:math:`C_{leaf}`, :math:`C_{stem}`, :math:`C_{root}`, :math:`C_{ts}`) is a vector with carbon density (g C km :sup:`-2`) for leaf, stem (live and dead stem), root (fine, live coarse and dead coarse root), and transfer and storage carbon pools as elements; :math:`\mathbf{CC}_{j}` = (:math:`\mathbf{CC}_{leaf}`, :math:`\mathbf{CC}_{stem}`, :math:`\mathbf{CC}_{root}`, :math:`\mathbf{CC}_{ts}`) is the corresponding combustion completeness factor vector (:numref:`Table PFT-specific combustion completeness and fire mortality factors`). Moreover, we assume that 50% and 28% of column-level litter and coarse woody debris are burned and the corresponding carbon is transferred to atmosphere. +where :math:`A_{b,j}` (km\ :sup:`2` \s\ :sup:`-1`) is burned area for the :math:`j`\ th PFT; **C**\ :sub:`j` =(:math:`C_{leaf}`, :math:`C_{stem}`, :math:`C_{root}`, :math:`C_{ts}`) is a vector with carbon density (g C km :sup:`-2`) for leaf, stem (live and dead stem), root (fine, live coarse and dead coarse root), and transfer and storage carbon pools as elements; :math:`\mathbf{CC}_{j}` = (:math:`\mathbf{CC}_{leaf}`, :math:`\mathbf{CC}_{stem}`, :math:`\mathbf{CC}_{root}`, :math:`\mathbf{CC}_{ts}`) is the corresponding combustion completeness factor vector (:numref:`Table PFT-specific fire parameters`). Moreover, we assume that 50% and 28% of column-level litter and coarse woody debris are burned and the corresponding carbon is transferred to atmosphere. Tissue mortality due to fire leads to carbon transfers in two ways. First, carbon from uncombusted leaf, live stem, dead stem, root, and transfer and storage pools :math:`\mathbf{C^{'} _{j1}} ={(C_{{leaf}} (1-CC_{{leaf}} ),C_{{livestem}} (1-CC_{{stem}} ),C_{{deadstem}} (1-CC_{{stem}} ),C_{{root}} (1-CC_{{root}} ),C_{{ts}} (1-CC_{{ts}} ))}_{j}` (g C km\ :sup:`-2`) is transferred to litter as @@ -249,14 +270,14 @@ Tissue mortality due to fire leads to carbon transfers in two ways. First, carbo \Psi _{j1} =\frac{A_{b,j} }{f_{j} A_{g} } \mathbf{C^{'} _{j1}} \bullet M_{j1} -where :math:`M_{j1} =(M_{{leaf}},M_{{livestem,1}},M_{{deadstem}},M_{{root}},M_{{ts}} )_{j}` is the corresponding mortality factor vector (:numref:`Table PFT-specific combustion completeness and fire mortality factors`). Second, carbon from uncombusted live stems is transferred to dead stems as: +where :math:`M_{j1} =(M_{{leaf}},M_{{livestem,1}},M_{{deadstem}},M_{{root}},M_{{ts}} )_{j}` is the corresponding mortality factor vector (:numref:`Table PFT-specific fire parameters`). Second, carbon from uncombusted live stems is transferred to dead stems as: .. math:: :label: 23.28 \Psi _{j2} =\frac{A_{b,j} }{f_{j} A_{g} } C_{livestem} (1-CC_{stem} )M_{livestem,2} -where :math:`M_{livestem,2}` is the corresponding mortality factor (:numref:`Table PFT-specific combustion completeness and fire mortality factors`). +where :math:`M_{livestem,2}` is the corresponding mortality factor (:numref:`Table PFT-specific fire parameters`). Fire nitrogen emissions and nitrogen transfers due to fire-induced mortality are calculated the same way as for carbon, using the same values for combustion completeness and mortality factors. With CLM's dynamic vegetation option enabled, the number of tree PFT individuals killed by fire per km\ :sup:`2` (individual km\ :sup:`-2` s\ :sup:`-1`) is given by @@ -265,7 +286,7 @@ Fire nitrogen emissions and nitrogen transfers due to fire-induced mortality are P_{disturb,j} =\frac{A_{b,j} }{f_{j} A_{g} } P_{j} \xi _{j} -where :math:`P_{j}` (individual km\ :sup:`-2`) is the population density for the :math:`j` th tree PFT and :math:`\xi _{j}` is the whole-plant mortality factor (:numref:`Table PFT-specific combustion completeness and fire mortality factors`). +where :math:`P_{j}` (individual km\ :sup:`-2`) is the population density for the :math:`j` th tree PFT and :math:`\xi _{j}` is the whole-plant mortality factor (:numref:`Table PFT-specific fire parameters`). .. _Agricultural fires: @@ -279,7 +300,7 @@ The burned area of cropland (km\ :sup:`2` s\ :sup:`-1`) is taken as :math:`{A}_{ A_{b} =a_{1} f_{se} f_{t} f_{crop} A_{g} -where :math:`a_{1}` (s\ :sup:`-1`) is a constant; :math:`f_{se}` represents the socioeconomic effect on fires; :math:`f_{t}` determines the seasonality of agricultural fires; :math:`f_{crop}` is the fractional coverage of cropland. :math:`a_{1}` \ = 1.6x10\ :sup:`-4` \hr\ :sup:`-1`\ is estimated using an inverse method, by matching 1997-2004 simulations to the analysis of :ref:`van der Werf et al. (2010) ` that shows the 2001-2009 average contribution of cropland fires is 4.7% of the total global burned area. +where :math:`a_{1}` (s\ :sup:`-1`) is a constant; :math:`f_{se}` represents the socioeconomic effect on fires; :math:`f_{t}` determines the seasonality of agricultural fires; :math:`f_{crop}` is the fractional coverage of cropland. :math:`a_{1}` \ = 0.34 \hr\ :sup:`-1`\ is estimated using an inverse method, by matching simulated global agricultural burned area to the GFED5 (:ref:`Chen et al. 2023 `) cropland burned area of 82 Mha yr\ :sup:`-1` for 2002−2020. The socioeconomic factor :math:`f_{se}` is given as follows: @@ -293,18 +314,18 @@ Here .. math:: :label: 23.32 - f_{d} =0.04+0.96\times \exp [-\pi (\frac{D_{p} }{350} )^{0.5} ] + f_{d} =0.2+0.8\times \exp (-\pi \frac{D_{p} }{400} ) and .. math:: :label: 23.33 - f_{e} =0.01+0.99\times \exp (-\pi \frac{GDP}{10} ) + f_{e} =0.05+0.95\times \exp (-\pi \frac{GDP}{20} ) -are the effects of population density and GDP on burned area, derived in a similar way to equation :eq:`23.32` and :eq:`23.33`. :math:`f_{t}` is set to 1 at the first time step during the climatological peak month for agricultural fires (:ref:`van der Werf et al. 2010 `); :math:`{f}_{t}` is set to 0 otherwise. Peak month in this dataset correlates with the month after harvesting or the month before planting. In CLM we use this dataset the same way whether the CROP option is active or not, without regard to the CROP option's simulated planting and harvesting dates. +are the effects of population density and GDP on burned area, derived in a similar way to equation :eq:`23.32` and :eq:`23.33`. :math:`f_{t}` is set to 1 at the first time step of the climatological peak month for GFED5 agricultural burned area and during the post-harvest and pre-planting period. -In the post-fire region, fire impact is parameterized similar to section :numref:`Fire impact` but with combustion completeness factors and tissue mortality factors for crop PFTs (:numref:`Table PFT-specific combustion completeness and fire mortality factors`). +In the post-fire region, fire impact is parameterized similar to section :numref:`Fire impact` but with combustion completeness factors and tissue mortality factors for crop PFTs (:numref:`Table PFT-specific fire parameters`). .. _Deforestation fires: @@ -320,12 +341,12 @@ CLM focuses on deforestation fires in tropical closed forests. Tropical closed f where :math:`b` (s\ :sup:`-1`) is a global constant; :math:`f_{lu}` (fraction) represents the effect of decreasing fractional coverage of tree PFTs derived from land use data; :math:`f_{cli,d}` (fraction) represents the effect of climate conditions on the burned area. -Constants :math:`b` and :math:`{f}_{lu}` are calibrated based on observations and reanalysis datasets in the Amazon rainforest (tropical closed forests within 15.5 °S :math:`\text{-}` 10.5 °N, 30.5 ° W :math:`\text{-}` 91 ° W). :math:`b` = 0.033 d\ :sup:`-1` and :math:`f_{lu}` is defined as +Constants :math:`b` and :math:`{f}_{lu}` are calibrated based on observations and reanalysis datasets in the Amazon rainforest (tropical closed forests within 15.5 °S :math:`\text{-}` 10.5 °N, 30.5 ° W :math:`\text{-}` 91 ° W). :math:`b` = 0.03 d\ :sup:`-1` and :math:`f_{lu}` is defined as .. math:: :label: 23.35 - f_{lu} = \max (0.0005,0.19D-0.001) + f_{lu} = 0.67 \min (0.01,D) + 0.001 where :math:`D` (yr\ :sup:`-1`) is the annual loss of tree cover based on CLM land use and land cover change data. @@ -334,13 +355,9 @@ The effect of climate on deforestation fires is parameterized as: .. math:: :label: 23.36 - \begin{array}{ll} - f_{cli,d} \quad = & \quad \max \left[0,\min (1,\frac{b_{2} -P_{60d} }{b_{2} } )\right]^{0.5} \times \\ - & \quad \max \left[0,\min (1,\frac{b_{3} -P_{10d} }{b_{3} } )\right]^{0.5} \times \\ - & \quad \max \left[0,\min (1,\frac{0.25-P}{0.25} )\right] - \end{array} + f_{cli,d} = \max [0,\min (1,1- \frac{P_{30d} }{b_{1} })] \max [0,\min (1,1- \frac{P}{0.25 } )] -where :math:`P` (mm d :sup:`-1`) is instantaneous precipitation, while :math:`P_{60d}` (mm d\ :sup:`-1`) and :math:`P_{10d}` (mm d :sup:`-1`) are 60-day and 10-day running means of precipitation, respectively; :math:`b_{2}` (mm d :sup:`-1`) and :math:`b_{3}` (mm d :sup:`-1`) are the grid-cell dependent thresholds of :math:`P_{60d}` and :math:`P_{10d}`; 0.25 mm d :sup:`-1` is the maximum precipitation rate for drizzle. :ref:`Le Page et al. (2010) ` analyzed the relationship between large-scale deforestation fire counts and precipitation during 2003 :math:`\text{-}`\ 2006 in southern Amazonia where tropical evergreen trees (BET Tropical) are dominant. Figure 2 in :ref:`Le Page et al. (2010) ` showed that fires generally occurred if both :math:`P_{60d}` and :math:`P_{10d}` were less than about 4.0 mm d :sup:`-1`, and fires occurred more frequently in a drier environment. Based on the 30-yr (1985 to 2004) precipitation data in :ref:`Qian et al. (2006) `. The climatological precipitation of dry months (P < 4.0 mm d :sup:`-1`) in a year over tropical deciduous tree (BDT Tropical) dominated regions is 46% of that over BET Tropical dominated regions, so we set the PFT-dependent thresholds of :math:`P_{60d}` and :math:`P_{10d}` as 4.0 mm d :sup:`-1` for BET Tropical and 1.8 mm d :sup:`-1` (= 4.0 mm d :sup:`-1` :math:`\times` 46%) for BDT Tropical, and :math:`b`\ :sub:`2` and :math:`b`\ :sub:`3` are the average of thresholds of BET Tropical and BDT Tropical weighted bytheir coverage. +where :math:`P` (mm d :sup:`-1`) is instantaneous precipitation, while :math:`P_{30d}` (mm d\ :sup:`-1`) is 30-day running means of precipitation; :math:`b_{1}` is grid-cell dependent thresholds of :math:`P_{30d}`; 0.25 mm d :sup:`-1` is the maximum precipitation rate for drizzle. :math:`b_{1}` is the average of thresholds of BET Tropical (0.5 mm d :sup:`-1`) and BDT Tropical ( 3.0 mm d :sup:`-1`) by their fractional coverage, where thresholds are derived based on GFED5 burned area and dry-season CRUJRA climatological precipitation for BET to BDT dominant regions in the Amazon rainforests. The post-fire area due to deforestation is not limited to land-type conversion regions. In the tree-reduced region, the maximum fire carbon emissions are assumed to be 80% of the total conversion flux. According to the fraction of conversion flux for tropical trees in the tree-reduced region (60%) assigned by CLM4-CN, to reach the maximum fire carbon emissions in a conversion region requires burning this region about twice when we set PFT-dependent combustion completeness factors to about 0.3 for stem [the mean of 0.2\ :math:`{-}`\ 0.4 used in :ref:`van der Werf et al. (2010) `. Therefore, when the burned area calculated from equation :eq:`23.36` is no more than twice the tree-reduced area, we assume no escaped fires outside the land-type conversion region, and the fire-related fraction of the total conversion flux is estimated as :math:`\frac{A_{b} /A_{g} }{2D}`. Otherwise, 80% of the total conversion flux is assumed to be fire carbon emissions, and the biomass combustion and vegetation mortality outside the tree-reduced regions with an area fraction of :math:`\frac{A_{b} }{A_{g} } -2D` are set as in section :numref:`Fire impact`. @@ -356,14 +373,14 @@ The burned area due to peat fires is given as :math:`{A}_{b}`: A_{b} = c \ f_{cli,p} f_{peat} A_{g} -where :math:`c` (s\ :sup:`-1`) is a constant; :math:`f_{cli,p}` represents the effect of climate on the burned area; and :math:`f_{peat}` is the fractional coverage of peatland in the grid cell. :math:`c` = 0.17 :math:`\times` 10 :sup:`-3` hr\ :sup:`-1` for tropical peat fires and :math:`c` = 0.9 :math:`\times` 10 :sup:`-5` hr :sup:`-1` for boreal peat fires are derived using an inverse method, by matching simulations to earlier studies: about 2.4 Mha peatland was burned over Indonesia in 1997 (:ref:`Page et al. 2002 `) and the average burned area of peat fires in Western Canada was 0.2 Mha yr :sup:`-1` for 1980-1999 (:ref:`Turetsky et al. 2004 `). +where :math:`c` (s\ :sup:`-1`) is a constant; :math:`f_{cli,p}` represents the effect of climate on the burned area; and :math:`f_{peat}` is the fractional coverage of peatland in the grid cell. :math:`c` = 0.75 :math:`\times` 10 :sup:`-4` hr\ :sup:`-1` for tropical peat fires and :math:`c` = 0.58 :math:`\times` 10 :sup:`-4` hr :sup:`-1` for boreal peat fires are derived using an inverse method, by matching simulations to earlier studies: about 0.5 Mha yr :sup:`-1` for Indonesia tropical peat fires based on GFED5 for 2002–2014 (:ref:`Chen et al., 2023 `) and the average burned area of peat fires in Western Canada was 0.2 Mha yr :sup:`-1` for 1980-1999 (:ref:`Turetsky et al. 2004 `). -For tropical peat fires, :math:`f_{cli,p}` is set as a function of long-term precipitation :math:`P_{60d}` : +For tropical peat fires, :math:`f_{cli,p}` is set as a function of long-term precipitation :math:`P_{30d}` : .. math:: :label: 23.38 - f_{cli,p} = \ max \left[0,\min \left(1,\frac{4-P_{60d} }{4} \right)\right]^{2} . + f_{cli,p} = \max \left[0,\min \left(1,1- \frac{P_{30d} }{6.5} \right)\right] . For boreal peat fires, :math:`f_{cli,p}` is set to @@ -389,46 +406,44 @@ Emissions for trace gas and aerosol species x and the j-th PFT, :math:`E_{x,j}` E_{x,j} = EF_{x,j}\frac{\phi _{j} }{[C]}. -Here, :math:`EF_{x,j}` (g species (g dm)\ :sup:`-1`) is PFT-dependent emission factor scaled from biome-level values (Li et al., in prep, also used for FireMIP fire emissions data) by Dr. Val Martin and Dr. Li. :math:`[C]` = 0.5 (g C (g dm)\ :sup:`-1`) is a conversion factor from dry matter to carbon. +Here, :math:`EF_{x,j}` (g species (g dm)\ :sup:`-1`) is PFT-dependent emission factor scaled from biome-level values (:ref:`Li et al. 2019 `; :ref:`Li et al. 2024b `) :math:`[C]` = 0.5 (g C (g dm)\ :sup:`-1`) is a conversion factor from dry matter to carbon. Emission height is PFT-dependent: 4.3 km for needleleaf tree PFTs, 3 km for other boreal and temperate tree PFTs, 2.5 km for tropical tree PFTs, 2 km for shrub PFTs, and 1 km for grass and crop PFTs. These values are compiled from earlier studies by Dr. Val Martin. -.. _Table PFT-specific combustion completeness and fire mortality factors: - -.. table:: PFT-specific combustion completeness and fire mortality factors. - - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | PFT | *CC*\ :sub:`leaf` | *CC*\ :sub:`stem` | *CC*\ :sub:`root` | *CC*\ :sub:`ts` | *M*\ :sub:`leaf` | *M*\ :sub:`livestem,1` | *M*\ :sub:`deadstem` | *M*\ :sub:`root` | *M*\ :sub:`ts` | *M*\ :sub:`livestem,2` | :math:`\xi`\ :sub:`j` | - +==================================+===========================+===========================+===========================+=========================+==========================+==============================+==============================+==========================+========================+==============================+=================================+ - | NET Temperate | 0.80 | 0.30 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | NET Boreal | 0.80 | 0.30 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | NDT Boreal | 0.80 | 0.30 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BET Tropical | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BET Temperate | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BDT Tropical | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.10 | 0.10 | 0.10 | 0.35 | 0.25 | 0.10 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BDT Temperate | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.10 | 0.10 | 0.10 | 0.35 | 0.25 | 0.10 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BDT Boreal | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BES Temperate | 0.80 | 0.35 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BDS Temperate | 0.80 | 0.35 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BDS Boreal | 0.80 | 0.35 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | C\ :sub:`3` Grass Arctic | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | 0.20 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | C\ :sub:`3` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | 0.20 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | C\ :sub:`4` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | 0.20 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | Crop | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | 0.20 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - -Leaves (:math:`CC_{leaf}` ), stems (:math:`CC_{stem}` ), roots (:math:`CC_{root}` ), and transfer and storage carbon (:math:`CC_{ts}` ); mortality factors for leaves (:math:`M_{leaf}` ), live stems (:math:`M_{livestem,1}` ), dead stems (:math:`M_{deadstem}` ), roots (:math:`M_{root}` ), and transfer and storage carbon (:math:`M_{ts}` ) related to the carbon transfers from these pools to litter pool; mortality factors for live stems (:math:`M_{livestem,2}` ) related to the carbon transfer from live stems to dead stems; whole-plant mortality factor (:math:`\xi _{j}` ). +.. _Table PFT-specific fire parameters: + +.. table:: PFT-specific fire parameters. Note that the parameter values listed in this document (PFT-specific and others) are calibrated for default CLM6/CTSM6 land-only simulations forced by CRUJRA meteorology. For cases with the experimental hillslope hydrology mode and for CESM3 coupled simulations with an active atmosphere model, different values are recommended for the lower and upper thresholds of root-zone soil wetness and the maximum fire spread rate to keep the simulated global total burned area within the observational range, because these configurations alter soil moisture states and/or the fire calculation framework. The different values are available in the form of alternate parameter files. + + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | PFT | *CC*\ :sub:`leaf` | *CC*\ :sub:`stem` | *CC*\ :sub:`root` | *CC*\ :sub:`ts` | *M*\ :sub:`leaf` | *M*\ :sub:`livestem,1` | *M*\ :sub:`deadstem` | *M*\ :sub:`root` | *M*\ :sub:`ts` | *M*\ :sub:`livestem,2` | :math:`\xi`\ :sub:`j` | :math:`u`\ :sub:`max` | :math:`\beta`\ :sub:`low` | :math:`\beta`\ :sub:`up` | + +==================================+===========================+===========================+===========================+=========================+==========================+==============================+==============================+==========================+========================+==============================+=================================+====================================+====================================+====================================+ + | NET Temperate | 0.80 | 0.30 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | 0.020 | 0.25 | 0.55 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | NET Boreal | 0.80 | 0.30 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | 0.023 | 0.35 | 0.7 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | NDT Boreal | 0.80 | 0.30 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | 0.023 | 0.35 | 0.7 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | BET Tropical | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | 0.053 | 0.35 | 0.75 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | BET Temperate | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | 0.020 | 0.3 | 0.7 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | BDT Tropical | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.10 | 0.10 | 0.10 | 0.35 | 0.25 | 0.10 | 0.033 | 0.3 | 0.7 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | BDT Temperate | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | 0.020 | 0.3 | 0.7 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | BDT Boreal | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | 0.020 | 0.3 | 0.7 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | BES Temperate | 0.80 | 0.35 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | 0.020 | 0.3 | 0.55 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | BDS Temperate | 0.80 | 0.35 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | 0.020 | 0.3 | 0.55 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | BDS Boreal | 0.80 | 0.35 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | 0.023 | 0.35 | 0.7 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | C\ :sub:`3` Grass Arctic | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | 0.20 | 0.023 | 0.35 | 0.7 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | C\ :sub:`3` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | 0.20 | 0.048 | 0.3 | 0.7 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + | C\ :sub:`4` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | 0.20 | 0.062 | 0.4 | 0.7 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+------------------------------------+------------------------------------+------------------------------------+ + +Combustion completeness factors for leaf (:math:`CC_{leaf}` ), stem (:math:`CC_{stem}` ), root (:math:`CC_{root}` ), and transfer and storage carbon (:math:`CC_{ts}` ); mortality factors for leaf (:math:`M_{leaf}` ), live stem (:math:`M_{livestem,1}` ), dead stem (:math:`M_{deadstem}` ), root (:math:`M_{root}` ), and transfer and storage carbon (:math:`M_{ts}` ) related to the carbon transfers from these pools to the litter pool; mortality factor for live stem (:math:`M_{livestem,2}` ) related to the carbon transfer from the live stem pool to the dead stem pool; whole-plant mortality factor (:math:`\xi _{j}` ); maximum fire spread rate (:math:`u_{max}`); lower and upper thresholds for root-zone soil wetness (:math:`\beta _{low}` and :math:`\beta _{up}`). diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index d73e002ec2..84da23626e 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -807,6 +807,8 @@ The stem surface area is where :math:`N_{tree}` is the number of trees per m\ :sup:`2`, :math:`k_{A}` is an adjustable parameter to account for the departure of tree area from a cylinder, :math:`D_{bh}` is the mean tree breast-height diameter (m), and :math:`h_{tree}` is the mean tree height (m). +For plant functional types other than trees or shrubs, or if :math:`D_{bh} < 0.05`, :math:`A_{leaf} = 2 L + S` and :math:`A_{stem} = 0`. Furthermore, for trees and shrubs, if :math:`L < 0.1`, :math:`A_{leaf} = 2 L + S`, where :math:`S` is the exposed stem area index (section :numref:`Phenology and vegetation burial by snow`). This is intended to avoid small :math:`A_{leaf}` which leads to small leaf conductance and high leaf temperature which can trigger an error in the RRTMGP component of the atmospheric model. + .. _Figure Schematic diagram of sensible heat fluxes: .. figure:: image1.png @@ -1029,6 +1031,20 @@ The bare soil turbulent transfer coefficient is where the kinematic viscosity of air :math:`\upsilon =1.5\times 10^{-5}` m\ :sup:`2` s\ :sup:`-1` and :math:`a=0.13`. +When biomass heat storage is active, an empirical under-canopy wind speed is used in the calculation of the aerodynamic resistances to heat and moisture + +.. math:: + :label: eq_rah_raw + + r_{ah} ^{{'} } =r_{aw} ^{{'} } =\frac{1}{C_{s} U_{uc} } + +where + +.. math:: + :label: eq_under_canopy_wind_speed + + U_{uc} =\min \left(0.4, \frac{0.3 \ V_{a}}{u_{*}} \right) \ . + The leaf boundary layer resistance :math:`r_{b}` is .. math:: @@ -1381,7 +1397,7 @@ The numerical solution for vegetation temperature and the fluxes of momentum, se \Delta _{2} =\overrightarrow{S}_{v} -\overrightarrow{L}_{v} -\frac{\partial \overrightarrow{L}_{v} }{\partial T_{v} } \Delta T_{v} -H_{v} -\frac{\partial H_{v} }{\partial T_{v} } \Delta T_{v} -\lambda E_{v} -\frac{\partial \lambda E_{v} }{\partial T_{v} } \Delta T_{v} -where :math:`\Delta T_{v} =1{\rm \; or\; }-1`. The error :math:`\Delta _{2}` is added to the sensible heat flux later. + where :math:`\Delta T_{v} =1{\rm \; or\; }-1`. The error :math:`\Delta _{2}` is added to the sensible heat flux later. #. Water vapor flux :math:`E_{v}` (:eq:`5.133` ) @@ -1394,7 +1410,7 @@ where :math:`\Delta T_{v} =1{\rm \; or\; }-1`. The error :math:`\Delta _{2}` is \Delta _{3} =\max \left(0,\, E_{v} -E_{v}^{t} -\frac{W_{can} }{\Delta t} \right). -The error :math:`\lambda \Delta _{3}` is added to the sensible heat flux later. + The error :math:`\lambda \Delta _{3}` is added to the sensible heat flux later. #. Sensible heat flux :math:`H_{v}` (:eq:`5.135` ). The three energy error terms, :math:`\Delta _{1}`, :math:`\Delta _{2}`, and :math:`\lambda \Delta _{3}` are also added to the sensible heat flux. @@ -1408,7 +1424,11 @@ The error :math:`\lambda \Delta _{3}` is added to the sensible heat flux later. #. Specific humidity difference :math:`q_{atm} -q_{s}` -#. Potential temperature scale :math:`\theta _{*} =\frac{\theta _{*} }{\theta _{atm} -\theta _{s} } \left(\theta _{atm} -\theta _{s} \right)` where :math:`\frac{\theta _{*} }{\theta _{atm} -\theta _{s} }` was calculated earlier in the iteration #. Humidity scale :math:`q_{*} =\frac{q_{*} }{q_{atm} -q_{s} } \left(q_{atm} -q_{s} \right)` where :math:`\frac{q_{*} }{q_{atm} -q_{s} }` was calculated earlier in the iteration #. Virtual potential temperature scale :math:`\theta _{v*}` (:eq:`5.17` ) +#. Potential temperature scale :math:`\theta _{*} =\frac{\theta _{*} }{\theta _{atm} -\theta _{s} } \left(\theta _{atm} -\theta _{s} \right)` where :math:`\frac{\theta _{*} }{\theta _{atm} -\theta _{s} }` was calculated earlier in the iteration + +#. Humidity scale :math:`q_{*} =\frac{q_{*} }{q_{atm} -q_{s} } \left(q_{atm} -q_{s} \right)` where :math:`\frac{q_{*} }{q_{atm} -q_{s} }` was calculated earlier in the iteration + +#. Virtual potential temperature scale :math:`\theta _{v*}` (:eq:`5.17` ) #. Wind speed including the convective velocity, :math:`V_{a}` (:eq:`5.24` ) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 46a134485b..1f77e8c038 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -21,126 +21,6 @@ The National Center for Atmospheric Research (NCAR) is operated by the nonprofit National Center for Atmospheric Research P. O. Box 3000, Boulder, Colorado 80307-300 -**LIST OF FIGURES** - -- :numref:`Figure Land processes` Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from :ref:`Lawrence et al. (2011)` for CLM5.0). - -- :numref:`Figure CLM subgrid hierarchy` Configuration of the CLM subgrid hierarchy. - -- :numref:`Figure Radiation Schematic` Schematic diagram of (a) direct beam radiation, (b) diffuse solar radiation, and (c) longwave radiation absorbed, transmitted, and reflected by vegetation and ground. - -- :numref:`Figure Schematic diagram of sensible heat fluxes` Schematic diagram of sensible heat fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. - -- :numref:`Figure Schematic diagram of latent heat fluxes` Schematic diagram of water vapor fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. - -- :numref:`Figure Soil Temperature Schematic`. Schematic diagram of numerical scheme used to solve for soil temperature. - -- :numref:`Figure Hydrologic processes` Hydrologic processes represented in CLM. - -- :numref:`Figure Water flux schematic` Schematic diagram of numerical scheme used to solve for soil water fluxes. - -- :numref:`Figure three layer snow pack` Example of three layer snow pack (snl=-3). - -- :numref:`Figure MOSART conceptual diagram` MOSART conceptual diagram. - -- :numref:`Figure Schematic representation of the urban landunit` Schematic representation of the urban land unit. - -- :numref:`Figure Schematic of urban and atmospheric model coupling` Schematic of urban and atmospheric model coupling. - -- :numref:`Figure Schematic of THESIS urban properties tool` Schematic of THESIS urban properties tool. - -- :numref:`Figure Vegetation fluxes and pools` Vegetation fluxes and pools. - -- :numref:`Figure Carbon costs of N fixation as a function of soil temperature` Carbon costs of N fixation as a function of soil temperature. - -- :numref:`Figure annual phenology cycle` Example of annual phenology cycle for seasonal deciduous. - -- :numref:`Figure Schematic of decomposition model in CLM` Schematic of decomposition model in CLM. - -- :numref:`Figure Pool structure` Pool structure, transitions, respired fractions, and turnover times for the 2 alternate soil decomposition models included in CLM. - -- :numref:`Figure Methane Schematic` Schematic representation of biological and physical processes integrated in CLM that affect the net CH4 surface flux. - -- :numref:`Figure Schematic of land cover change` Schematic of land cover change impacts on CLM carbon pools and fluxes. - -- :numref:`Figure Schematic of translation of annual LUH2 land units` Schematic of translation of annual UNH land units to CLM plant functional types. - -**LIST OF TABLES** - -- :numref:`Table Plant functional types` Plant functional types - -- :numref:`Table Plant functional type canopy top and bottom heights` Plant functional type canopy top and bottom heights - -- :numref:`Table Soil layer structure` Soil layer structure - -- :numref:`Table Atmospheric input to land model` Atmospheric input to land model - -- :numref:`Table Land model output to atmospheric model` Land model output to atmospheric model - -- :numref:`Table Surface data required for CLM and their base spatial resolution` Surface data required for CLM and their base spatial resolution - -- :numref:`Table Physical constants` Physical constants - -- :numref:`Table Plant functional type optical properties` Plant functional type optical properties - -- :numref:`Table Intercepted snow optical properties` Intercepted snow optical properties - -- :numref:`Table Dry and saturated soil albedos` Dry and saturated soil albedos - -- :numref:`Table Spectral bands and weights used for snow radiative transfer` Spectral bands and weights used for snow radiative transfer - -- :numref:`Table Single-scatter albedo values used for snowpack impurities and ice` Single-scatter albedo values used for snowpack impurities and ice - -- :numref:`Table Mass extinction values` Mass extinction values (m2 kg-1) used for snowpack impurities and ice. - -- :numref:`Table Asymmetry scattering parameters used for snowpack impurities and ice` Asymmetry scattering parameters used for snowpack impurities and ice. - -- :numref:`Table Orbital parameters` Orbital parameters - -- :numref:`Table Plant functional type aerodynamic parameters` Plant functional type aerodynamic parameters - -- :numref:`Table Coefficients for saturation vapor pressure` Coefficients for e\ :sub:`sat`\ :sup:`T` - -- :numref:`Table Coefficients for derivative of esat` Coefficients for the derivative of e\ :sub:`sat`\ :sup:`T` - -- :numref:`Table Meltwater scavenging` Meltwater scavenging efficiency for particles within snow - -- :numref:`Table snow layer thickness` Minimum and maximum thickness of snow layers (m) - -- :numref:`Table Plant functional type (PFT) stomatal conductance parameters` Plant functional type (PFT) stomatal conductance parameters. - -- :numref:`Table Temperature dependence parameters for C3 photosynthesis` Temperature dependence parameters for C3 photosynthesis. - -- :numref:`Table Plant functional type root distribution parameters` Plant functional type root distribution parameters. - -- :numref:`Table MOSART Parameters` List of parameters in the global hydrography dataset. - -- :numref:`Table Allocation and CN ratio parameters` Allocation and carbon:nitrogen ratio parameters - -- :numref:`Table Decomposition rate constants` Decomposition rate constants for litter and SOM pools, C:N ratios, and acceleration parameters for the CLM-CN decomposition pool structure. - -- :numref:`Table Respiration fractions for litter and SOM pools` Respiration fractions for litter and SOM pools - -- :numref:`Table Turnover times` Turnover times, C:N ratios, and acceleration parameters for the Century-based decomposition cascade. - -- :numref:`Table Respiration fractions for Century-based structure` Respiration fractions for litter and SOM pools for Century-based structure - -- :numref:`Table PFT-specific combustion completeness and fire mortality factors` PFT-specific combustion completeness and fire mortality factors. - -- :numref:`Table Methane Parameter descriptions` Parameter descriptions and sensitivity analysis ranges applied in the methane model. - -- :numref:`Table Temperature dependence of aqueous and gaseous diffusion` Temperature dependence of aqueous and gaseous diffusion coefficients for CH4 and O2. - -- :numref:`Table Crop plant functional types` Crop plant functional types (PFTs). - -- :numref:`Table Crop phenology parameters` Crop phenology and morphology parameters. - -- :numref:`Table Crop allocation parameters` Crop allocation parameters. - -- :numref:`Table Dust Mass fraction` Mass fraction m\ :sub:`i` , mass median diameter :sub:`v, i` , and geometric standard deviation :sub:`g, i` , per dust source mode i - -- :numref:`Table Dust Minimum and maximum particle diameters` Minimum and maximum particle diameters in each dust transport bin j - **ACKNOWLEDGEMENTS** The authors would like to acknowledge the substantial contributions of the following members of the Land Model and Biogeochemistry Working Groups to the development of the Community Land Model since its inception in 1996: Benjamin Andre, Ian Baker, Michael Barlage, Mike Bosilovich, Marcia Branstetter, Tony Craig, Aiguo Dai, Yongjiu Dai, Mark Decker, Scott Denning, Robert Dickinson, Paul Dirmeyer, Jared Entin, Jay Famiglietti, Johannes Feddema, Mark Flanner, Jon Foley, Andrew Fox, Inez Fung, David Gochis, Alex Guenther, Tim Hoar, Forrest Hoffman, Paul Houser, Trish Jackson, Brian Kauffman, Silvia Kloster, Natalie Mahowald, Jiafu Mao, Lei Meng, Sheri Michelson, Guo-Yue Niu, Adam Phillips, Taotao Qian, Jon Radakovich, James Randerson, Nan Rosenbloom, Steve Running, Koichi Sakaguchi, Adam Schlosser, Andrew Slater, Reto Stöckli, Ying Sun, Quinn Thomas, Peter Thornton, Mariana Vertenstein, Nicholas Viovy, Aihui Wang, Guiling Wang, Zong-Liang Yang, Charlie Zender, Xiaodong Zeng, and Xubin Zeng. diff --git a/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst b/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst index acc3f0dc1c..e99fed4c3c 100644 --- a/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst +++ b/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst @@ -3,14 +3,14 @@ Lake Model ============= -The lake model, denoted the *Lake, Ice, Snow, and Sediment Simulator* (LISSS), is from :ref:`Subin et al. (2012a) `. It includes extensive modifications to the lake code of :ref:`Zeng et al. (2002) ` used in CLM versions 2 through 4, which utilized concepts from the lake models of :ref:`Bonan (1996) `, :ref:`Henderson-Sellers (1985) `, :ref:`Henderson-Sellers (1986) `, :ref:`Hostetler and Bartlein (1990) `, and the coupled lake-atmosphere model of :ref:`Hostetler et al. (1993) `, :ref:`Hostetler et al. (1993) `. Lakes have spatially variable depth prescribed in the surface data (section :ref:`External Data Lake`); the surface data optionally includes lake optical extinction coeffient and horizontal fetch, currently only used for site simulations. Lake physics includes freezing and thawing in the lake body, resolved snow layers, and "soil" and bedrock layers below the lake body. Temperatures and ice fractions are simulated for :math:`N_{levlak} =10` layers (for global simulations) or :math:`N_{levlak} =25` (for site simulations) with discretization described in section :numref:`Vertical Discretization Lake`. Lake albedo is described in section :numref:`Surface Albedo Lake`. Lake surface fluxes (section :numref:`Surface Fluxes and Surface Temperature Lake`) generally follow the formulations for non-vegetated surfaces, including the calculations of aerodynamic resistances (section :numref:`Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces`); however, the lake surface temperature :math:`T_{g}` (representing an infinitesimal interface layer between the top resolved lake layer and the atmosphere) is solved for simultaneously with the surface fluxes. After surface fluxes are evaluated, temperatures are solved simultaneously in the resolved snow layers (if present), the lake body, and the soil and bedrock, using the ground heat flux *G* as a top boundary condition. Snow, soil, and bedrock models generally follow the formulations for non-vegetated surfaces (Chapter :numref:`rst_Soil and Snow Temperatures`), with modifications described below. +The lake model, denoted the *Lake, Ice, Snow, and Sediment Simulator* (LISSS), is from :ref:`Subin et al. (2012a) `. It includes extensive modifications to the lake code of :ref:`Zeng et al. (2002) ` used in CLM versions 2 through 4, which utilized concepts from the lake models of :ref:`Bonan (1996) `, :ref:`Henderson-Sellers (1985) `, :ref:`Henderson-Sellers (1986) `, :ref:`Hostetler and Bartlein (1990) `, and the coupled lake-atmosphere model of :ref:`Hostetler et al. (1993) `. Lakes have spatially varying depth prescribed in the surface data (section :ref:`External Data Lake`); the surface data optionally includes lake optical extinction coeffient and horizontal fetch, currently only used for site simulations. Lake physics includes freezing and thawing in the lake body, resolved snow layers, and "soil" and bedrock layers below the lake body. Temperatures and ice fractions are simulated for :math:`N_{levlak} =10` layers (for global simulations) or :math:`N_{levlak} =25` (for site simulations) with discretization described in section :numref:`Vertical Discretization Lake`. Lake albedo is described in section :numref:`Ground Albedos`. Lake surface fluxes (section :numref:`Surface Fluxes and Surface Temperature Lake`) generally follow the formulations for non-vegetated surfaces, including the calculations of aerodynamic resistances (section :numref:`Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces`); however, the lake surface temperature :math:`T_{g}` (representing an infinitesimal interface layer between the top resolved lake layer and the atmosphere) is solved for simultaneously with the surface fluxes. After surface fluxes are evaluated, temperatures are solved simultaneously in the resolved snow layers (if present), the lake body, and the soil and bedrock, using the ground heat flux *G* as a top boundary condition. Snow, soil, and bedrock models generally follow the formulations for non-vegetated surfaces (Chapter :numref:`rst_Soil and Snow Temperatures`), with modifications described below. .. _Vertical Discretization Lake: Vertical Discretization --------------------------- -Currently, there is one lake modeled in each grid cell (with prescribed or assumed depth *d*, extinction coefficient :math:`\eta`, and fetch *f*), although this could be modified with changes to the CLM subgrid decomposition algorithm in future model versions. As currently implemented, the lake consists of 0-5 snow layers; water and ice layers (10 for global simulations and 25 for site simulations) comprising the "lake body;" 10 "soil" layers; and 5 bedrock layers. Each lake body layer has a fixed water mass (set by the nominal layer thickness and the liquid density), with frozen mass-fraction *I* a state variable. Resolved snow layers are present if the snow thickness :math:`z_{sno} \ge s_{\min }`, where *s*\ :sub:`min` = 4 cm by default, and is adjusted for model timesteps other than 1800 s in order to maintain numerical stability (section :numref:`Modifications to Snow Layer Logic Lake`). For global simulations with 10 body layers, the default (50 m lake) body layer thicknesses are given by: :math:`\Delta z_{i}` of 0.1, 1, 2, 3, 4, 5, 7, 7, 10.45, and 10.45 m, with node depths :math:`z_{i}` located at the center of each layer (i.e., 0.05, 0.6, 2.1, 4.6, 8.1, 12.6, 18.6, 25.6, 34.325, 44.775 m). For site simulations with 25 layers, the default thicknesses are (m): 0.1 for layer 1; 0.25 for layers 2-5; 0.5 for layers 6-9; 0.75 for layers 10-13; 2 for layers 14-15; 2.5 for layers 16-17; 3.5 for layers 18-21; and 5.225 for layers 22-25. For lakes with depth *d* :math:`\neq` 50 m and *d* :math:`\ge` 1 m, the top layer is kept at 10 cm and the other 9 layer thicknesses are adjusted to maintain fixed proportions. For lakes with *d* :math:`<` 1 m, all layers have equal thickness. Thicknesses of snow, soil, and bedrock layers follow the scheme used over non-vegetated surfaces (Chapter :numref:`rst_Soil and Snow Temperatures`), with modifications to the snow layer thickness rules to keep snow layers at least as thick as *s*\ :sub:`min` (section :numref:`Modifications to Snow Layer Logic Lake`). +Currently, there is one lake modeled in each grid cell (with prescribed or default depth *d*, extinction coefficient :math:`\eta`, and fetch *f*), although this could be modified with changes to the CLM subgrid decomposition algorithm in future model versions. As currently implemented, the lake consists of 0-5 snow layers; water and ice layers (10 for global simulations and 25 for site simulations) comprising the "lake body;" 10 "soil" layers; and 5 bedrock layers. Each lake body layer has a fixed water mass (set by the nominal layer thickness and the liquid density), with frozen mass-fraction *I* a state variable. Resolved snow layers are present if the snow thickness :math:`z_{sno} \ge s_{\min }`, where *s*\ :sub:`min` = 4 cm by default, and is adjusted for model timesteps other than 1800 s in order to maintain numerical stability (section :numref:`Modifications to Snow Layer Logic Lake`). For global simulations with 10 body layers, the default (50 m lake) body layer thicknesses are given by: :math:`\Delta z_{i}` of 0.1, 1, 2, 3, 4, 5, 7, 7, 10.45, and 10.45 m, with node depths :math:`z_{i}` located at the center of each layer (i.e., 0.05, 0.6, 2.1, 4.6, 8.1, 12.6, 18.6, 25.6, 34.325, 44.775 m). For site simulations with 25 layers, the default thicknesses are (m): 0.1 for layer 1; 0.25 for layers 2-5; 0.5 for layers 6-9; 0.75 for layers 10-13; 2 for layers 14-15; 2.5 for layers 16-17; 3.5 for layers 18-21; and 5.225 for layers 22-25. For lakes with depth *d* :math:`\neq` 50 m and *d* :math:`\ge` 1 m, the top layer is kept at 10 cm and the other 9 layer thicknesses are adjusted to maintain fixed proportions. For lakes with *d* :math:`<` 1 m, all layers have equal thickness. Thicknesses of snow, soil, and bedrock layers follow the scheme used over non-vegetated surfaces (Chapter :numref:`rst_Soil and Snow Temperatures`), with modifications to the snow layer thickness rules to keep snow layers at least as thick as *s*\ :sub:`min` (section :numref:`Modifications to Snow Layer Logic Lake`). .. _External Data Lake: @@ -19,31 +19,6 @@ External Data As discussed in :ref:`Subin et al. (2012a, b) `, the Global Lake and Wetland Database (:ref:`Lehner and Doll 2004`) is currently used to prescribe lake fraction in each land model grid cell, for a total of 2.3 million km\ :sup:`-2`. As in :ref:`Subin et al. (2012a, b) `, the :ref:`Kourzeneva et al. (2012)` global gridded dataset is currently used to estimate a mean lake depth in each grid cell, based on interpolated compilations of geographic information. -.. _Surface Albedo Lake: - -Surface Albedo ------------------- - -For direct radiation, the albedo *a* for lakes with ground temperature :math:`{T}_{g}` (K) above freezing is given by (:ref:`Pivovarov, 1972`) - -.. math:: - :label: 12.1 - - a=\frac{0.5}{\cos z+0.15} - -where *z* is the zenith angle. For diffuse radiation, the expression in eq. is integrated over the full sky to yield *a* = 0.10. - -For frozen lakes without resolved snow layers, the albedo at cold temperatures *a*\ :sub:`0` is 0.60 for visible and 0.40 for near infrared radiation. As the temperature at the ice surface, :math:`{T}_{g}`, approaches freezing [ :math:`{T}_{f}` (K) (:numref:`Table Physical Constants`)], the albedo is relaxed towards 0.10 based on :ref:`Mironov et al. (2010)`: - -.. math:: - :label: 12.2 - - a=a_{0} \left(1-x\right)+0.10x,x=\exp \left(-95\frac{T_{f} -T_{g} }{T_{f} } \right) - -where *a* is restricted to be no less than that given in :eq:`12.1`. - -For frozen lakes with resolved snow layers, the reflectance of the ice surface is fixed at *a*\ :sub:`0`, and the snow reflectance is calculated as over non-vegetated surfaces (Chapter :numref:`rst_Surface Albedos`). These two reflectances are combined to obtain the snow-fraction-weighted albedo as in over non-vegetated surfaces (Chapter :numref:`rst_Surface Albedos`). - .. _Surface Fluxes and Surface Temperature Lake: Surface Fluxes and Surface Temperature @@ -56,7 +31,7 @@ Surface Properties The fraction of shortwave radiation absorbed at the surface, :math:`\beta`, depends on the lake state. If resolved snow layers are present, then :math:`\beta` is set equal to the absorption fraction predicted by the snow-optics submodel (Chapter :numref:`rst_Surface Albedos`) for the top snow layer. Otherwise, :math:`\beta` is set equal to the near infrared fraction of the shortwave radiation reaching the surface simulated by the atmospheric model or atmospheric data model used for offline simulations (Chapter :numref:`rst_Land-only Mode`). The remainder of the shortwave radiation fraction (1 :math:`{-}` :math:`\beta`) is absorbed in the lake body or soil as described in section :numref:`Radiation Penetration`. -The surface roughnesses are functions of the lake state and atmospheric forcing. +The surface roughnesses are functions of the lake state and atmospheric forcing. For unfrozen lakes (:math:`T_{g} > T_{f}`), :math:`z_{0m}` is given by (:ref:`Subin et al. (2012a) `) @@ -68,7 +43,7 @@ For unfrozen lakes (:math:`T_{g} > T_{f}`), :math:`z_{0m}` is given by (:ref:`Su where :math:`\alpha` = 0.1, :math:`\nu` is the kinematic viscosity of air given below, *C* is the effective Charnock coefficient given below, :math:`u_{*}` is the friction velocity (m/s), and *g* is the acceleration of gravity (:numref:`Table Physical Constants`). The kinematic viscosity is given by .. math:: - :label: 12.4 + :label: 12.4 \nu =\nu _{0} \left(\frac{T_{g} }{T_{0} } \right)^{1.5} \frac{P_{0} }{P_{ref} } @@ -79,7 +54,7 @@ where :math:`P_{ref}` is the pressure at the atmospheric reference height. The Charnock coefficient *C* is a function of the lake fetch *F* (m), given in the surface data or set to 25 times the lake depth *d* by default: .. math:: - :label: 12.5 + :label: 12.5 \begin{array}{l} {C=C_{\min } +(C_{\max } -C_{\min } )\exp \left\{-\min \left(A,B\right)\right\}} \\ {A={\left(\frac{Fg}{u_{*} ^{2} } \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right.} 3} } \mathord{\left/ {\vphantom {\left(\frac{Fg}{u_{*} ^{2} } \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right.} 3} } f_{c} }} \right.} f_{c} } } \\ {B=\varepsilon \frac{\sqrt{dg} }{u} } \end{array} @@ -104,7 +79,7 @@ For frozen lakes ( :math:`T_{g} \le T_{f}` ) without resolved snow layers ( :math:`snl = 0` ), :math:`z_{0m} =z_{0m_{ice}} =2.3\times 10^{-3} {\rm m}` (:ref:`Meier et al. (2022) `). For frozen lakes with resolved -snow layers ( :math:`snl > 0` ), the momentum roughness length is evaluated based on accumulated snow melt :math:`M_{a} {\rm }` (:ref:`Meier et al. (2022) `). +snow layers ( :math:`snl > 0` ), the momentum roughness length is evaluated based on accumulated snow melt :math:`M_{a} {\rm }` (:ref:`Meier et al. (2022) `). For :math:`M_{a} >=1\times 10^{-5}` .. math:: @@ -123,7 +98,7 @@ For :math:`M_{a} <1\times 10^{-5}` Accumulated snow melt :math:`M_{a}` at the current time step :math:`t` is defined as .. math:: - :label: 12.5d + :label: 12.5d M ^{t}_{a} = M ^{t-1}_{a} - (q ^{t}_{sno} \Delta t + q ^{t}_{snowmelt} \Delta t)\times 10^{-3} @@ -169,7 +144,7 @@ where :math:`\vec{S}_{g}` \ is the absorbed solar radiation in the lake, .. math:: :label: 12.8 - \lambda =\left\{\begin{array}{l} {\lambda _{sub} \qquad T_{g} \le T_{f} } \\ {\lambda _{vap} \qquad T_{g} >T_{f} } \end{array}\right\}. + \lambda =\Bigg\{\begin{array}{l} {\lambda _{sub} \qquad T_{g} \le T_{f} } \\ {\lambda _{vap} \qquad T_{g} >T_{f} } \end{array} The sensible heat flux (W m\ :sup:`-2`) is @@ -226,7 +201,7 @@ The absorbed solar radiation :math:`\vec{S}_{g}` is \vec{S}_{g} =\sum _{\Lambda }S_{atm} \, \downarrow _{\Lambda }^{\mu } \left(1-\alpha _{g,\, \Lambda }^{\mu } \right) +S_{atm} \, \downarrow _{\Lambda } \left(1-\alpha _{g,\, \Lambda } \right) -where :math:`S_{atm} \, \downarrow _{\Lambda }^{\mu }` and :math:`S_{atm} \, \downarrow _{\Lambda }` are the incident direct beam and diffuse solar fluxes (W m\ :sup:`-2`) and :math:`\Lambda` denotes the visible (:math:`<` 0.7\ :math:`\mu {\rm m}`) and near-infrared (:math:`\ge` 0.7\ :math:`\mu {\rm m}`) wavebands (section :numref:`Atmospheric Coupling`), and :math:`\alpha _{g,\, \Lambda }^{\mu }` and :math:`\alpha _{g,\, \mu }` are the direct beam and diffuse lake albedos (section :numref:`Surface Albedo Lake`). +where :math:`S_{atm} \, \downarrow _{\Lambda }^{\mu }` and :math:`S_{atm} \, \downarrow _{\Lambda }` are the incident direct beam and diffuse solar fluxes (W m\ :sup:`-2`) and :math:`\Lambda` denotes the visible (:math:`<` 0.7\ :math:`\mu {\rm m}`) and near-infrared (:math:`\ge` 0.7\ :math:`\mu {\rm m}`) wavebands (section :numref:`Atmospheric Coupling`), and :math:`\alpha _{g,\, \Lambda }^{\mu }` and :math:`\alpha _{g,\, \mu }` are the direct beam and diffuse lake albedos (section :numref:`Ground Albedos`). The net emitted longwave radiation is @@ -241,7 +216,7 @@ where :math:`L_{g} \, \uparrow` is the upward longwave radiation from the surfac .. math:: :label: 12.16 - L\, \uparrow =\left(1-\varepsilon _{g} \right)L_{atm} \, \downarrow +\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{4} +4\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{3} \left(T_{g}^{n+1} -T_{g}^{n} \right) + \vec{L}_{g}\, \uparrow =\left(1-\varepsilon _{g} \right)L_{atm} \, \downarrow +\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{4} +4\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{3} \left(T_{g}^{n+1} -T_{g}^{n} \right) where :math:`\varepsilon _{g} =0.97` is the lake surface emissivity, :math:`\sigma` is the Stefan-Boltzmann constant (W m\ :sup:`-2` K\ :sup:`-4`) (:numref:`Table Physical Constants`), and @@ -285,29 +260,29 @@ where the partial derivatives are The fluxes of momentum, sensible heat, and water vapor are solved for simultaneously with lake surface temperature as follows. To begin, :math:`z_{0m}` and the scalar roughness lengths are set as described in section :numref:`Surface Properties Lake`. -#. An initial guess for the wind speed :math:`V_{a}` including the convective velocity :math:`U_{c}` is obtained from :eq:`5.24` assuming an initial convective velocity :math:`U_{c} =0` m s\ :sup:`-1` for stable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} \ge 0` as evaluated from :eq:`5.50`) and :math:`U_{c} =0.5` for unstable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} <0`). +#. An initial guess for the wind speed :math:`V_{a}` including the convective velocity :math:`U_{c}` is obtained from equation :eq:`5.24` assuming an initial convective velocity :math:`U_{c} =0` m s\ :sup:`-1` for stable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} \ge 0` as evaluated from equation :eq:`5.50`) and :math:`U_{c} =0.5` for unstable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} <0`). -#. An initial guess for the Monin-Obukhov length :math:`L` is obtained from the bulk Richardson number using :eq:`5.46` and :eq:`5.48`. +#. An initial guess for the Monin-Obukhov length :math:`L` is obtained from the bulk Richardson number using equations :eq:`5.46` and :eq:`5.48`. #. The following system of equations is iterated four times: -#. Heat of vaporization / sublimation :math:`\lambda` \ (:eq:`12.8`) +#. Heat of vaporization / sublimation :math:`\lambda` \ (equation :eq:`12.8`) -#. Thermal conductivity :math:`\lambda _{T}` \ (above) +#. Thermal conductivity :math:`\lambda _{T}` \ (described above after equation :eq:`12.13`) -#. Friction velocity :math:`u_{*}` (:eq:`5.32`, :eq:`5.33`, :eq:`5.34`, :eq:`5.35`) +#. Friction velocity :math:`u_{*}` (equations :eq:`5.32`, :eq:`5.33`, :eq:`5.34`, :eq:`5.35`) -#. Potential temperature scale :math:`\theta _{*}` (:eq:`5.37`, :eq:`5.38`, :eq:`5.39`, :eq:`5.40`) +#. Potential temperature scale :math:`\theta _{*}` (equations :eq:`5.37`, :eq:`5.38`, :eq:`5.39`, :eq:`5.40`) -#. Humidity scale :math:`q_{*}` (:eq:`5.41`, :eq:`5.42`, :eq:`5.43`, :eq:`5.44`) +#. Humidity scale :math:`q_{*}` (equations :eq:`5.41`, :eq:`5.42`, :eq:`5.43`, :eq:`5.44`) -#. Aerodynamic resistances :math:`r_{am}`, :math:`r_{ah}`, and :math:`r_{aw}` (:eq:`5.55`, :eq:`5.56`, :eq:`5.57`) +#. Aerodynamic resistances :math:`r_{am}`, :math:`r_{ah}`, and :math:`r_{aw}` (equations :eq:`5.55`, :eq:`5.56`, :eq:`5.57`) -#. Lake surface temperature :math:`T_{g}^{n+1}` (:eq:`12.18`) +#. Lake surface temperature :math:`T_{g}^{n+1}` (equation :eq:`12.18`) -#. Heat of vaporization / sublimation :math:`\lambda` (:eq:`12.8`) +#. Heat of vaporization / sublimation :math:`\lambda` (equation :eq:`12.8`) -#. Sensible heat flux :math:`H_{g}` is updated for :math:`T_{g}^{n+1}` (:eq:`12.9`) +#. Sensible heat flux :math:`H_{g}` is updated for :math:`T_{g}^{n+1}` (equation :eq:`12.9`) #. Water vapor flux :math:`E_{g}` is updated for :math:`T_{g}^{n+1}` as @@ -318,13 +293,13 @@ The fluxes of momentum, sensible heat, and water vapor are solved for simultaneo where the last term on the right side of equation :eq:`12.23` is the change in saturated specific humidity due to the change in :math:`T_{g}` between iterations. -#. Saturated specific humidity :math:`q_{sat}^{T_{g} }` and its derivative :math:`\frac{dq_{sat}^{T_{g} } }{dT_{g} }` are updated for :math:`T_{g}^{n+1}` (section :numref:`Monin-Obukhov Similarity Theory`). +14. Saturated specific humidity :math:`q_{sat}^{T_{g} }` and its derivative :math:`\frac{dq_{sat}^{T_{g} } }{dT_{g} }` are updated for :math:`T_{g}^{n+1}` (section :numref:`Monin-Obukhov Similarity Theory`). -#. Virtual potential temperature scale :math:`\theta _{v*}` (:eq:`5.17`) +#. Virtual potential temperature scale :math:`\theta _{v*}` (equation :eq:`5.17`) -#. Wind speed including the convective velocity, :math:`V_{a}` (:eq:`5.24`) +#. Wind speed including the convective velocity, :math:`V_{a}` (equation :eq:`5.24`) -#. Monin-Obukhov length :math:`L` (:eq:`5.49`) +#. Monin-Obukhov length :math:`L` (equation :eq:`5.49`) #. Roughness lengths (section :numref:`Surface Properties Lake`). @@ -375,28 +350,21 @@ where :math:`\tilde{c}_{v}` is the volumetric heat capacity (J m\ :sup:`-3` K\ : \frac{d}{dt} \sum _{j=1}^{N}\left[\tilde{c}_{v,j} (t)\left(T_{j} -T_{f} \right)+L_{j} (t)\right] \Delta z_{j} =G+\left(1-\beta \right)\vec{S}_{g} -where :math:`\tilde{c}_{v,j} (t)`\ is the volumetric heat capacity of the *j*\ th layer (section :numref:`Radiation Penetration`), :math:`L_{j} (t)`\ is the latent heat of fusion per unit volume of the *j*\ th layer (proportional to the mass of liquid water present), and the right-hand side represents the net influx of energy to the lake system. Note that :math:`\tilde{c}_{v,j} (t)` can only change due to phase change (except for changing snow layer mass, which, apart from energy required to melt snow, represents an untracked energy flux in the land model, along with advected energy associated with water flows in general), and this is restricted to occur at :math:`T_{j} =T_{f}` \ in the snow-lake-soil system, allowing eq. to be precisely enforced and justifying the exclusion of :math:`c_{v,j}` from the time derivative in eq.. - -.. _Overview of Changes from CLM4 2: - -Overview of Changes from CLM4 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Thermal conductivities include additional eddy diffusivity, beyond the :ref:`Hostetler and Bartlein (1990)` formulation, due to unresolved processes (:ref:`Fang and Stefan 1996`; :ref:`Subin et al. (2012a) `). Lake water is now allowed to freeze by an arbitrary fraction for each layer, which releases latent heat and changes thermal properties. Convective mixing occurs for all lakes, even if frozen. Soil and bedrock are included beneath the lake. The full snow model is used if the snow thickness exceeds a threshold; if there are resolved snow layers, radiation transfer is predicted by the snow-optics submodel (Chapter :numref:`rst_Surface Albedos`), and the remaining radiation penetrating the bottom snow layer is absorbed in the top layer of lake ice; conversely, if there are no snow layers, the solar radiation penetrating the bottom lake layer is absorbed in the top soil layer. The lakes have variable depth, and all physics is assumed valid for arbitrary depth, except for a depth-dependent enhanced mixing (section :numref:`Eddy Diffusivity and Thermal Conductivities`). Finally, a previous sign error in the calculation of eddy diffusivity (specifically, the Brunt-Väisälä frequency term; eq. ) was corrected. +where :math:`\tilde{c}_{v,j} (t)`\ is the volumetric heat capacity of the *j*\ th layer (section :numref:`Heat Capacities Lake`), :math:`L_{j} (t)`\ is the latent heat of fusion per unit volume of the *j*\ th layer (proportional to the mass of liquid water present), and the right-hand side represents the net influx of energy to the lake system. Note that :math:`\tilde{c}_{v,j} (t)` can only change due to phase change (except for changing snow layer mass, which, apart from energy required to melt snow, represents an untracked energy flux in the land model, along with advected energy associated with water flows in general), and this is restricted to occur at :math:`T_{j} =T_{f}` \ in the snow-lake-soil system, allowing equation :eq:`12.27` to be precisely enforced and justifying the exclusion of :math:`c_{v,j}` from the time derivative in equation :eq:`12.27`. .. _Boundary Conditions Lake: Boundary Conditions ^^^^^^^^^^^^^^^^^^^^^^^^^ -The top boundary condition, imposed at the top modeled layer :math:`i=j_{top}`, where :math:`j_{top} =-n_{sno} +1`, is the downwards surface flux *G* defined by the energy flux residual during the surface temperature solution (section :numref:`Boundary Conditions Lake`). The bottom boundary condition, imposed at :math:`i=N_{levlak} +N_{levgrnd}`, is zero flux. The 2-m windspeed :math:`u_{2}` \ (m s\ :sup:`-1`) is used in the calculation of eddy diffusivity: +The top boundary condition, imposed at the top modeled layer :math:`i=j_{top}`, where :math:`j_{top} =-n_{sno} +1`, is the downwards surface flux *G* defined by the energy flux residual during the surface temperature solution (section :numref:`Surface Flux Solution Lake`). The bottom boundary condition, imposed at :math:`i=N_{levlak} +N_{levgrnd}`, is zero flux. The 2-m windspeed :math:`u_{2}` \ (m s\ :sup:`-1`) is used in the calculation of eddy diffusivity: .. math:: :label: 12.28 u_{2} =\frac{u_{*} }{k} \ln \left(\frac{2}{z_{0m} } \right)\ge 0.1. -where :math:`u_{*}` \ is the friction velocity calculated in section :numref:`Boundary Conditions Lake` and +where :math:`u_{*}` \ is the friction velocity calculated in section :numref:`Monin-Obukhov Similarity Theory` and *k* is the von Karman constant (:numref:`Table Physical Constants`). .. _Eddy Diffusivity and Thermal Conductivities: @@ -419,7 +387,7 @@ where :math:`\kappa _{e}` is due to wind-driven eddies (:ref:`Hostetler and Bart .. math:: :label: 12.30 - m_{d} =\left\{\begin{array}{l} {1,\qquad d<25{\rm m}} \\ {10,\qquad d\ge 25{\rm m}} \end{array}\right\} + m_{d} =\Bigg\{\begin{array}{rr} {1,\qquad d<25{\rm m}} \\ {10,\qquad d\ge 25{\rm m}} \end{array} where *d* is the lake depth. @@ -428,9 +396,9 @@ The wind-driven eddy diffusion coefficient :math:`\kappa _{e,\, i}` (m\ :sup:`2` .. math:: :label: 12.31 - \kappa _{e,\, i} =\left\{\begin{array}{l} {\frac{kw^{*} z_{i} }{P_{0} \left(1+37Ri^{2} \right)} \exp \left(-k^{*} z_{i} \right)\qquad T_{g} >T_{f} } \\ {0\qquad T_{g} \le T_{f} } \end{array}\right\} + \kappa _{e,\, i} =\Bigg\{\begin{array}{rr} {\frac{kw^{*} z_{i} }{P_{0} \left(1+37Ri^{2} \right)} \exp \left(-k^{*} z_{i} \right)\qquad T_{g} >T_{f} } \\ {0\qquad T_{g} \le T_{f} } \end{array} -where :math:`P_{0} =1` is the neutral value of the turbulent Prandtl number, :math:`z_{i}` is the node depth (m), the surface friction velocity (m s\ :sup:`-1`) is :math:`w^{*} =0.0012u_{2}`, and :math:`k^{*}` varies with latitude :math:`\phi` as :math:`k^{*} =6.6u_{2}^{-1.84} \sqrt{\left|\sin \phi \right|}`. For the bottom layer, :math:`\kappa _{e,\, N_{levlak} } =\kappa _{e,N_{levlak} -1\, }`. As in :ref:`Hostetler and Bartlein (1990)`, the 2-m wind speed :math:`u_{2}` (m s\ :sup:`-1`) (eq. ) is used to evaluate :math:`w^{*}` and :math:`k^{*}` rather than the 10-m wind used by :ref:`Henderson-Sellers (1985) `. +where :math:`P_{0} =1` is the neutral value of the turbulent Prandtl number, :math:`z_{i}` is the node depth (m), the surface friction velocity (m s\ :sup:`-1`) is :math:`w^{*} =0.0012u_{2}`, and :math:`k^{*}` varies with latitude :math:`\phi` as :math:`k^{*} =6.6u_{2}^{-1.84} \sqrt{\left|\sin \phi \right|}`. For the bottom layer, :math:`\kappa _{e,\, N_{levlak} } =\kappa _{e,N_{levlak} -1\, }`. As in :ref:`Hostetler and Bartlein (1990)`, the 2-m wind speed :math:`u_{2}` (m s\ :sup:`-1`) (equation :eq:`12.28`) is used to evaluate :math:`w^{*}` and :math:`k^{*}` rather than the 10-m wind used by :ref:`Henderson-Sellers (1985) `. The Richardson number is @@ -446,7 +414,7 @@ where N^{2} =\frac{g}{\rho _{i} } \frac{\partial \rho }{\partial z} -and :math:`g` is the acceleration due to gravity (m s\ :sup:`-2`) (:numref:`Table Physical Constants`), :math:`\rho _{i}` is the density of water (kg m\ :sup:`-3`), and :math:`\frac{\partial \rho }{\partial z}` is approximated as :math:`\frac{\rho _{i+1} -\rho _{i} }{z_{i+1} -z_{i} }`. Note that because here, *z* is increasing downwards (unlike in :ref:`Hostetler and Bartlein (1990)`), eq. contains no negative sign; this is a correction from CLM4. The density of water is (:ref:`Hostetler and Bartlein (1990)`) +and :math:`g` is the acceleration due to gravity (m s\ :sup:`-2`) (:numref:`Table Physical Constants`), :math:`\rho _{i}` is the density of water (kg m\ :sup:`-3`), and :math:`\frac{\partial \rho }{\partial z}` is approximated as :math:`\frac{\rho _{i+1} -\rho _{i} }{z_{i+1} -z_{i} }`. Note that because here, *z* is increasing downwards (unlike in :ref:`Hostetler and Bartlein (1990)`), equation :eq:`12.33` contains no negative sign; this is a correction from CLM4. The density of water is (:ref:`Hostetler and Bartlein (1990)`) .. math:: :label: 12.34 @@ -460,7 +428,7 @@ The enhanced diffusivity :math:`K_{ed}` is given by (:ref:`Fang and Stefan 1996< K_{ed} =1.04\times 10^{-8} \left(N^{2} \right)^{-0.43} ,N^{2} \ge 7.5\times 10^{-5} {\rm s}^{2} -where :math:`N^{2}` \ is calculated as in eq. except for the minimum value imposed in. +where :math:`N^{2}` \ is calculated as in equation :eq:`12.33` except for the minimum value imposed by equation :eq:`12.35`. The thermal conductivity for the liquid water portion of lake body layer *i*, :math:`\tau _{liq,i}` (W m\ :sup:`-1` K\ :sup:`-1`) is given by @@ -492,7 +460,7 @@ The thermal conductivity of snow, soil, and bedrock layers above and below the l Radiation Penetration ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If there are no resolved snow layers, the surface absorption fraction :math:`\beta` is set according to the near-infrared fraction simulated by the atmospheric model. This is apportioned to the surface energy budget (section :numref:`Surface Properties Lake`), and thus no additional radiation is absorbed in the top :math:`z_{a}` (currently 0.6 m) of unfrozen lakes, for which the light extinction coefficient :math:`\eta` (m\ :sup:`-1`) varies between lake columns (eq. ). For frozen lakes (:math:`T_{g} \le T_{f}` ), the remaining :math:`\left(1-\beta \right)\vec{S}_{g}` fraction of surface absorbed radiation that is not apportioned to the surface energy budget is absorbed in the top lake body layer. This is a simplification, as lake ice is partially transparent. If there are resolved snow layers, then the snow optics submodel (Chapter :numref:`rst_Surface Albedos`) is used to calculate the snow layer absorption (except for the absorption predicted for the top layer by the snow optics submodel, which is assigned to the surface energy budget), with the remainder penetrating snow layers absorbed in the top lake body ice layer. +If there are no resolved snow layers, the surface absorption fraction :math:`\beta` is set according to the near-infrared fraction simulated by the atmospheric model. This is apportioned to the surface energy budget (section :numref:`Surface Properties Lake`), and thus no additional radiation is absorbed in the top :math:`z_{a}` (currently 0.6 m) of unfrozen lakes, for which the light extinction coefficient :math:`\eta` (m\ :sup:`-1`) varies between lake columns (equation :eq:`12.41`). For frozen lakes (:math:`T_{g} \le T_{f}` ), the remaining :math:`\left(1-\beta \right)\vec{S}_{g}` fraction of surface absorbed radiation that is not apportioned to the surface energy budget is absorbed in the top lake body layer. This is a simplification, as lake ice is partially transparent. If there are resolved snow layers, then the snow optics submodel (Chapter :numref:`rst_Surface Albedos`) is used to calculate the snow layer absorption (except for the absorption predicted for the top layer by the snow optics submodel, which is assigned to the surface energy budget), with the remainder penetrating snow layers absorbed in the top lake body ice layer. For unfrozen lakes, the solar radiation remaining at depth :math:`z>z_{a}` in the lake body is given by @@ -559,7 +527,7 @@ where superscripts *n* + 1 and *n* denote values at the end and beginning of the :math:`F_{i}` (W m\ :sup:`-2`) is the downward heat flux at the bottom of layer *i*, and :math:`\phi _{i}` is the solar radiation absorbed in layer *i*. -Eq. is solved using the semi-implicit Crank-Nicholson Method, resulting in a tridiagonal system of equations: +Equation :eq:`12.44` is solved using the semi-implicit Crank-Nicholson Method, resulting in a tridiagonal system of equations: .. math:: :label: 12.45 @@ -612,14 +580,14 @@ Finally, the mass of ice in the layer :math:`M_{ice}` is adjusted downwards by : where :math:`c'_{v,i} =c_{v,i} +M\left(c_{liq} -c_{ice} \right)`. -If freezing occurs, :math:`Q_{avail}` is again given by but will be negative. The melt :math:`M`, also negative, is given by +If freezing occurs, :math:`Q_{avail}` is again given by equation :eq:`12.47`, but will be negative. The melt :math:`M`, also negative, is given by .. math:: :label: 12.51 M=\max \left\{-M_{liq} ,\frac{Q_{avail} }{H_{fus} } \right\} -where :math:`M_{liq}` is the mass of water in the layer: :math:`\left(1-I_{i} \right)\rho _{liq} \Delta z_{i}` for a lake body layer, or the soil / snow water content state variable (:math:`w_{liq}` ). The heat remainder :math:`Q_{rem}` is given by eq. and will be negative or zero. Finally, :math:`M_{liq}` is adjusted downwards by :math:`-M` and the temperature is reset according to eq.. +where :math:`M_{liq}` is the mass of water in the layer: :math:`\left(1-I_{i} \right)\rho _{liq} \Delta z_{i}` for a lake body layer, or the soil / snow water content state variable (:math:`w_{liq}` ). The heat remainder :math:`Q_{rem}` is given by equation :eq:`12.49` and will be negative or zero. Finally, :math:`M_{liq}` is adjusted downwards by :math:`-M` and the temperature is reset according to equation :eq:`12.50` In the presence of nonzero snow water :math:`W_{sno}` without resolved snow layers over an unfrozen top lake layer, the available energy in the top lake layer :math:`\left(T_{1} -T_{f} \right)c_{v,1}` is used to melt the snow. Similar to above, :math:`W_{sno}` is either completely melted and the remainder of heat returned to the top lake layer, or the available heat is exhausted and the top lake layer is set to freezing. The snow thickness is adjusted downwards in proportion to the amount of melt, maintaining constant density. @@ -704,7 +672,7 @@ Lake Hydrology Overview ^^^^^^^^^^^^^^ -Hydrology is done similarly to other impervious non-vegetated columns (e.g., glaciers) where snow layers may be resolved but infiltration into the permanent ground is not allowed. The water mass of lake columns is currently maintained constant, aside from overlying snow. The water budget is balanced with :math:`q_{rgwl}` (eq.; kg m\ :sup:`-2` s\ :sup:`-1`), a generalized runoff term for impervious land units that may be negative. +Hydrology is done similarly to other impervious non-vegetated columns (e.g., glaciers) where snow layers may be resolved but infiltration into the permanent ground is not allowed. The water mass of lake columns is currently maintained constant, aside from overlying snow. The water budget is balanced with :math:`q_{rgwl}` (kg m\ :sup:`-2` s\ :sup:`-1`), a generalized runoff term for impervious land units that may be negative (see section :numref:`rst_Hydrology` for more information about :math:`q_{rgwl}`). There are some modifications to the soil and snow parameterizations as compared with the soil in vegetated land units, or the snow overlying other impervious columns. The soil can freeze or thaw, with the allowance for frost heave (or the initialization of excess ice) (sections :numref:`Eddy Diffusivity and Thermal Conductivities` and :numref:`Phase Change Lake`), but no air-filled pore space is allowed in the soil. To preserve numerical stability in the lake model (which uses a slightly different surface flux algorithm than over other non-vegetated land units), two changes are made to the snow model. First, dew or frost is not allowed to be absorbed by a top snow layer which has become completely melted during the timestep. Second, because occasional instabilities occurred during model testing when the Courant–Friedrichs–Lewy (CFL) condition was violated, due to the explicit time-stepping integration of the surface flux solution, resolved snow layers must be a minimum of :math:`s_{\min }` = 4 cm thick rather than 1 cm when the default timestep of 1800 s is used. diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst index 674e4cc0b3..36bf94bdb8 100644 --- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst +++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst @@ -32,7 +32,7 @@ In MOSART, the travel velocities of water across hillslopes, sub-network and mai .. math:: :label: 14.1 - V = \frac{R^{\frac{2}{3}} S_{f}}{n} + V = \frac{R^{\frac{2}{3}} S_{f}^{\frac{1}{2}}}{n} where :math:`V` is the travel velocity (m s :sup:`-1` ), :math:`R` is the hydraulic radius (m). :math:`S_{f}` is the friction slope that accounts for the effects of gravity, friction, inertia and other forces on the water. If the channel slope is steep enough, the gravity force dominates over the others so one can approximate :math:`S_{f}` by the channel bed slope :math:`S`, which is the key assumption underpinning the kinematic wave method. :math:`n` is the Manning's roughness coefficient, which is mainly controlled by surface roughness and sinuosity of the flow path. @@ -41,7 +41,7 @@ If the water surface is sufficiently large or the water depth :math:`h` is suffi .. math:: :label: 14.2 - R_{h} = h_{h} + R_{h} = h_{h} \\ R_{t} = h_{t} Here :math:`R_{h}` (m) and :math:`R_{t}` (m) are hydraulic radius for hillslope and sub-network channel routing respectively, and :math:`h_{h}` (m) and :math:`h_{t}` (m) are water depth during hillslope and sub-network channel routing respectively. @@ -60,9 +60,9 @@ For hillslopes, sub-network and main channels, a common continuity equation can .. math:: :label: 14.4 - \frac{dS}{dt} = Q_{in} - Q_{out} + R + \frac{dS}{dt} = Q_{in} - Q_{out} + R - I -where :math:`Q_{in}` (m :sup:`3` s :sup:`-1` ) is the main channel flow from the upstream grid(s) into the main channel of the current grid, which is zero for hillslope and sub-network routing. :math:`Q_{out}` (m :sup:`3` s :sup:`-1` ) is the outflow rate from hillslope into the sub-network, from the sub-network into the main channel, or from the current main channel to the main channel of its downstream grid (if not the outlet grid) or ocean (if the current grid is the basin outlet). :math:`R` (m :sup:`3` s :sup:`-1` ) is a source term, which could be the surface runoff generation rate for hillslopes, or lateral inflow (from hillslopes) into sub-network channel or water-atmosphere exchange fluxes such as precipitation and evaporation. It is assumed that surface runoff is generated uniformly across all the hillslopes. Currently, MOSART does not exchange water with the atmosphere or return water to the land model so its function is strictly to transport water from runoff generation through the hillslope, tributaries, and main channels to the basin outlets. +where :math:`Q_{in}` (m :sup:`3` s :sup:`-1` ) is the main channel flow from the upstream grid(s) into the main channel of the current grid, which is zero for hillslope and sub-network routing. :math:`Q_{out}` (m :sup:`3` s :sup:`-1` ) is the outflow rate from hillslope into the sub-network, from the sub-network into the main channel, or from the current main channel to the main channel of its downstream grid (if not the outlet grid) or ocean (if the current grid is the basin outlet). :math:`R` (m :sup:`3` s :sup:`-1` ) is a source term, which could be the surface runoff generation rate for hillslopes, or lateral inflow (from hillslopes) into sub-network channel or water-atmosphere exchange fluxes such as precipitation and evaporation. It is assumed that surface runoff is generated uniformly across all the hillslopes. :math:`I` is water abstraction via irrigation demand only from main channel (i.e., :math:`I` = 0 for hillslope and sub-network). Currently, MOSART does not exchange water with the atmosphere, but returns water from a main channel to the land model based on irrigation demand if irrigation opition is actived in the land model. .. _Numerical Solution MOSART: @@ -112,14 +112,3 @@ MOSART is supported by a comprehensive, global hydrography dataset at 0.5 ° res | :math:`n_{h}` | \- | Manning's roughness coefficient for overland flow routing | +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ -Difference between CLM5.0 and CLM4.5 -------------------------------------- - -1. Routing methods: RTM, a linear reservoir method, is used in CLM4.5 for river routing, whilst in CLM5.0, MOSART is an added option for river routing based on the more physically-based kinematic wave method. - -2. Runoff treatment: In RTM runoff is routed regardless of its sign so negative streamflow can be simulated at times. MOSART routes only non-negative runoff and always produces positive streamflow, which is important for future extensions to model riverine heat and biogeochemical fluxes. - -3. Input parameters: RTM in CLM4.5 only requires one layer of a spatially varying variable of channel velocity, whilst MOSART in CLM5.0 requires 13 parameters that are all available globally at 0.5 ° resolution. - -4. Outputs: RTM only produces streamflow simulation, whilst MOSART additionally simulates the time-varying channel velocities, channel water depth, and channel surface water variations. - diff --git a/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst index c7f9a7bcbd..f489dce3be 100644 --- a/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst +++ b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst @@ -14,6 +14,8 @@ Methane Model Structure and Flow The driver routine for the methane biogeochemistry calculations controls the initialization of boundary conditions, inundation, and impact of redox conditions; calls to routines to calculate CH\ :sub:`4` production, oxidation, transport through aerenchyma, ebullition, and the overall mass balance (for unsaturated and saturated soils and, if desired, lakes); resolves changes to CH\ :sub:`4` calculations associated with a changing inundated fraction; performs a mass balance check; and calculates the average column CH\ :sub:`4` production, oxidation, and exchanges with the atmosphere. +Default history includes a short list of methane-related fields. One can set namelist parameter ``hist_wrtch4diag = .true.`` to obtain a list of methane-related fields that is longer by about 20. Alternatively one may use namelist fincl statements to add individual fields of interest to history. + .. _Governing Mass-Balance Relationship: Governing Mass-Balance Relationship diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index d739751d7d..6410556ac8 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -3,16 +3,14 @@ Stomatal Resistance and Photosynthesis ========================================= -Summary of CLM5.0 updates relative to the CLM4.5 ------------------------------------------------------ +History +------- -We describe here the complete photosynthesis and stomatal conductance parameterizations that appear in CLM5.0. Corresponding information for CLM4.5 appeared in the CLM4.5 Technical Note (:ref:`Oleson et al. 2013 `). - -CLM5 includes the following new changes to photosynthesis and stomatal conductance: +We describe here the complete photosynthesis and stomatal conductance parameterizations that appear in CLM6.0. In this version relative to CLM5, we have changed numerous parameter values, but have kept the algorithm unchanged. In CLM5 relative to CLM4.5, this section included the following updates: - Default stomatal conductance calculation uses the Medlyn conductance model -- :math:`V_{c,max}` and :math:`J_{max}` at 25 :sup:`\o`\ C: are now prognostic, and predicted via optimality by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) +- :math:`V_{c,max}` and :math:`J_{max}` at 25\ :sup:`\o`\ C: are now prognostic, and predicted via optimality by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) - Leaf N concentration and the fraction of leaf N in Rubisco used to calculate :math:`V_{cmax25}` are determined by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) @@ -28,16 +26,16 @@ Leaf stomatal resistance, which is needed for the water vapor flux (Chapter :num Stomatal resistance ----------------------- -CLM5 calculates stomatal conductance using the Medlyn stomatal conductance model (:ref:`Medlyn et al. 2011`). Previous versions of CLM calculated leaf stomatal resistance using the Ball-Berry conductance model as described by :ref:`Collatz et al. (1991)` and implemented in global climate models (:ref:`Sellers et al. 1996`). The Medlyn model calculates stomatal conductance (i.e., the inverse of resistance) based on net leaf photosynthesis, the leaf-to-air vapor pressure difference, and the CO\ :sub:`2` concentration at the leaf surface. Leaf stomatal resistance is: +Since CLM5 the model has calculated stomatal conductance using the Medlyn stomatal conductance model (:ref:`Medlyn et al. 2011`). Previous versions of CLM calculated leaf stomatal resistance using the Ball-Berry conductance model as described by :ref:`Collatz et al. (1991)` and implemented in global climate models (:ref:`Sellers et al. 1996`). The Medlyn model calculates stomatal conductance (i.e., the inverse of resistance) based on net leaf photosynthesis, the leaf-to-air vapor pressure difference, and the CO\ :sub:`2` concentration at the leaf surface. Leaf stomatal resistance is: .. math:: :label: 9.1 \frac{1}{r_{s} } =g_{s} = g_{o} + 1.6(1 + \frac{g_{1} }{\sqrt{D_{s}}}) \frac{A_{n} }{{c_{s} \mathord{\left/ {\vphantom {c_{s} P_{atm} }} \right.} P_{atm} } } -where :math:`r_{s}` is leaf stomatal resistance (s m\ :sup:`2` :math:`\mu`\ mol\ :sup:`-1`), :math:`g_{o}` is the minimum stomatal conductance (:math:`\mu` mol m :sup:`-2` s\ :sup:`-1`), :math:`A_{n}` is leaf net photosynthesis (:math:`\mu`\ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`), :math:`c_{s}` is the CO\ :sub:`2` partial pressure at the leaf surface (Pa), :math:`P_{atm}` is the atmospheric pressure (Pa), and :math:`D_{s}=(e_{i}-e{_s})/1000` is the leaf-to-air vapor pressure difference at the leaf surface (kPa) where :math:`e_{i}` is the saturation vapor pressure (Pa) evaluated at the leaf temperature :math:`T_{v}`, and :math:`e_{s}` is the vapor pressure at the leaf surface (Pa). :math:`g_{1}` is a plant functional type dependent parameter (:numref:`Table Plant functional type (PFT) stomatal conductance parameters`) and is the same as those used in the CABLE model (:ref:`de Kauwe et al. 2015 `). +where :math:`r_{s}` is leaf stomatal resistance (s m\ :sup:`2` :math:`\mu`\ mol\ :sup:`-1`), :math:`A_{n}` is leaf net photosynthesis (:math:`\mu`\ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`), :math:`c_{s}` is the CO\ :sub:`2` partial pressure at the leaf surface (Pa), :math:`P_{atm}` is the atmospheric pressure (Pa), and :math:`D_{s}=(e_{i}-e{_s})/1000` is the leaf-to-air vapor pressure difference at the leaf surface (kPa) where :math:`e_{i}` is the saturation vapor pressure (Pa) evaluated at the leaf temperature :math:`T_{v}`, and :math:`e_{s}` is the vapor pressure at the leaf surface (Pa). :math:`g_{o}` is plant functional type (pft)-dependent minimum stomatal conductance (:math:`\mu` mol m :sup:`-2` s\ :sup:`-1`) and :math:`g_{1}` is a pft-dependent parameter (:numref:`Table Plant functional type (PFT) stomatal conductance parameters`) with same values originally as in the CABLE model (:ref:`de Kauwe et al. 2015 `) but most values have been replaced in CLM6. -The value for :math:`g_{o}=100` :math:`\mu` mol m :sup:`-2` s\ :sup:`-1` for C\ :sub:`3` and C\ :sub:`4` plants. Photosynthesis is calculated for sunlit (:math:`A^{sun}`) and shaded (:math:`A^{sha}`) leaves to give :math:`r_{s}^{sun}` and :math:`r_{s}^{sha}`. Additionally, soil water influences stomatal resistance through plant hydraulic stress, detailed in the :ref:`rst_Plant Hydraulics` chapter. +Photosynthesis is calculated for sunlit (:math:`A^{sun}`) and shaded (:math:`A^{sha}`) leaves to give :math:`r_{s}^{sun}` and :math:`r_{s}^{sha}`. Additionally, soil water influences stomatal resistance through plant hydraulic stress, detailed in the :ref:`rst_Plant Hydraulics` chapter. Resistance is converted from units of s m\ :sup:`2` :math:`\mu` mol\ :sup:`-1` to s m\ :sup:`-1` as: 1 s m\ :sup:`-1` = :math:`1\times 10^{-9} R_{gas} \frac{\theta _{atm} }{P_{atm} }` :math:`\mu` mol\ :sup:`-1` m\ :sup:`2` s, where :math:`R_{gas}` is the universal gas constant (J K\ :sup:`-1` kmol\ :sup:`-1`) (:numref:`Table Physical constants`) and :math:`\theta _{atm}` is the atmospheric potential temperature (K). @@ -45,57 +43,59 @@ Resistance is converted from units of s m\ :sup:`2` :math:`\mu` mol\ :sup:`-1` t .. table:: Plant functional type (PFT) stomatal conductance parameters. - +----------------------------------+-------------------+ - | PFT | g\ :sub:`1` | - +==================================+===================+ - | NET Temperate | 2.35 | - +----------------------------------+-------------------+ - | NET Boreal | 2.35 | - +----------------------------------+-------------------+ - | NDT Boreal | 2.35 | - +----------------------------------+-------------------+ - | BET Tropical | 4.12 | - +----------------------------------+-------------------+ - | BET temperate | 4.12 | - +----------------------------------+-------------------+ - | BDT tropical | 4.45 | - +----------------------------------+-------------------+ - | BDT temperate | 4.45 | - +----------------------------------+-------------------+ - | BDT boreal | 4.45 | - +----------------------------------+-------------------+ - | BES temperate | 4.70 | - +----------------------------------+-------------------+ - | BDS temperate | 4.70 | - +----------------------------------+-------------------+ - | BDS boreal | 4.70 | - +----------------------------------+-------------------+ - | C\ :sub:`3` arctic grass | 2.22 | - +----------------------------------+-------------------+ - | C\ :sub:`3` grass | 5.25 | - +----------------------------------+-------------------+ - | C\ :sub:`4` grass | 1.62 | - +----------------------------------+-------------------+ - | Temperate Corn | 1.79 | - +----------------------------------+-------------------+ - | Spring Wheat | 5.79 | - +----------------------------------+-------------------+ - | Temperate Soybean | 5.79 | - +----------------------------------+-------------------+ - | Cotton | 5.79 | - +----------------------------------+-------------------+ - | Rice | 5.79 | - +----------------------------------+-------------------+ - | Sugarcane | 1.79 | - +----------------------------------+-------------------+ - | Tropical Corn | 1.79 | - +----------------------------------+-------------------+ - | Tropical Soybean | 5.79 | - +----------------------------------+-------------------+ - | Miscanthus | 1.79 | - +----------------------------------+-------------------+ - | Switchgrass | 1.79 | - +----------------------------------+-------------------+ + +----------------------------------+-------------+------------------+ + | PFT | g\ :sub:`o` | g\ :sub:`1` | + +==================================+=============+==================+ + | NET Temperate | 110.93 | 2.35 | + +----------------------------------+-------------+------------------+ + | NET Boreal | 12500 | 2.57 | + +----------------------------------+-------------+------------------+ + | NDT Boreal | 1.00 | 2.09 | + +----------------------------------+-------------+------------------+ + | BET Tropical | 1733.21 | 3.50 | + +----------------------------------+-------------+------------------+ + | BET temperate | 102.24 | 4.12 | + +----------------------------------+-------------+------------------+ + | BDT tropical | 97.56 | 2.85 | + +----------------------------------+-------------+------------------+ + | BDT temperate | 100.40 | 4.45 | + +----------------------------------+-------------+------------------+ + | BDT boreal | 99.73 | 5.05 | + +----------------------------------+-------------+------------------+ + | BES temperate | 100.00 | 4.38 | + +----------------------------------+-------------+------------------+ + | BDS temperate | 100.00 | 4.70 | + +----------------------------------+-------------+------------------+ + | BDS boreal | 100.00 | 4.70 | + +----------------------------------+-------------+------------------+ + | C\ :sub:`3` arctic grass | 100.00 | 3.78 | + +----------------------------------+-------------+------------------+ + | C\ :sub:`3` grass | 5063.54 | 8.32 | + +----------------------------------+-------------+------------------+ + | C\ :sub:`4` grass | 100.00 | 1.62 | + +----------------------------------+-------------+------------------+ + | C\ :sub:`3` crop | 5063.54 | 9.17 | + +----------------------------------+-------------+------------------+ + | Temperate Corn | 100.00 | 1.79 | + +----------------------------------+-------------+------------------+ + | Spring Wheat | 100.00 | 5.79 | + +----------------------------------+-------------+------------------+ + | Temperate Soybean | 100.00 | 5.79 | + +----------------------------------+-------------+------------------+ + | Cotton | 100.00 | 5.79 | + +----------------------------------+-------------+------------------+ + | Rice | 100.00 | 5.79 | + +----------------------------------+-------------+------------------+ + | Sugarcane | 100.00 | 1.79 | + +----------------------------------+-------------+------------------+ + | Tropical Corn | 100.00 | 1.79 | + +----------------------------------+-------------+------------------+ + | Tropical Soybean | 100.00 | 5.79 | + +----------------------------------+-------------+------------------+ + | Miscanthus | 100.00 | 1.79 | + +----------------------------------+-------------+------------------+ + | Switchgrass | 100.00 | 1.79 | + +----------------------------------+-------------+------------------+ .. _Photosynthesis: @@ -105,18 +105,18 @@ Photosynthesis Photosynthesis in C\ :sub:`3` plants is based on the model of :ref:`Farquhar et al. (1980)`. Photosynthesis in C\ :sub:`4` plants is based on the model of :ref:`Collatz et al. (1992)`. :ref:`Bonan et al. (2011)` describe the implementation, modified here. In its simplest form, leaf net photosynthesis after accounting for respiration (:math:`R_{d}` ) is .. math:: - :label: 9.2 + :label: leaf_net_psn - A_{n} =\min \left(A_{c} ,A_{j} ,A_{p} \right)-R_{d} . + A_{n} =\min \left(A_{c} ,A_{j} ,A_{p} \right)-R_{d} The RuBP carboxylase (Rubisco) limited rate of carboxylation :math:`A_{c}` (:math:`\mu` \ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is .. math:: - :label: 9.3 + :label: rubisco_lim_rate_of_carboxylation - A_{c} =\left\{\begin{array}{l} {\frac{V_{c\max } \left(c_{i} -\Gamma _{*} \right)}{c_{i} +K_{c} \left(1+{o_{i} \mathord{\left/ {\vphantom {o_{i} K_{o} }} \right.} K_{o} } \right)} \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {V_{c\max } \qquad \qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}\qquad \qquad c_{i} -\Gamma _{*} \ge 0. + A_{c} =\left\{\begin{array}{l} {\frac{\beta_{t} V_{c\max } \left(c_{i} -\Gamma _{*} \right)}{c_{i} +K_{c} \left(1+{o_{i} \mathord{\left/ {\vphantom {o_{i} K_{o} }} \right.} K_{o} } \right)} \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {\beta_{t} V_{c\max } \qquad \qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}\qquad \qquad c_{i} -\Gamma _{*} \ge 0. -The maximum rate of carboxylation allowed by the capacity to regenerate RuBP (i.e., the light-limited rate) :math:`A_{j}` (:math:`\mu` \ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is +where :math:`\beta_{t} = \beta_{t,sun}` is the transpiration water stress for sunlit leaves and :math:`\beta_{t} = \beta_{t,sha}` for shaded leaves (Eqs. :eq:`beta_t_sun`, :eq:`beta_t_sha`). The maximum rate of carboxylation allowed by the capacity to regenerate RuBP (i.e., the light-limited rate) :math:`A_{j}` (:math:`\mu` \ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is .. math:: :label: 9.4 @@ -128,9 +128,9 @@ The product-limited rate of carboxylation for C\ :sub:`3` plants and the PEP car .. math:: :label: 9.5 - A_{p} =\left\{\begin{array}{l} {3T_{p\qquad } \qquad \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {k_{p} \frac{c_{i} }{P_{atm} } \qquad \qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}. + A_{p} =\left\{\begin{array}{l} {3T_{p\qquad } \qquad \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {k_{p} \frac{c_{i} }{P_{atm} } \qquad \qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\} -In these equations, :math:`c_{i}` is the internal leaf CO\ :sub:`2` partial pressure (Pa) and :math:`o_{i} =0.20P_{atm}` is the O\ :sub:`2` partial pressure (Pa). :math:`K_{c}` and :math:`K_{o}` are the Michaelis-Menten constants (Pa) for CO\ :sub:`2` and O\ :sub:`2`. :math:`\Gamma _{*}` (Pa) is the CO\ :sub:`2` compensation point. :math:`V_{c\max }` is the maximum rate of carboxylation (µmol m\ :sup:`-2` s\ :sup:`-1`, Chapter :numref:`rst_Photosynthetic Capacity`) and :math:`J_{x}` is the electron transport rate (µmol m\ :sup:`-2` s\ :sup:`-1`). :math:`T_{p}` is the triose phosphate utilization rate (µmol m\ :sup:`-2` s\ :sup:`-1`), taken as :math:`T_{p} =0.167V_{c\max }` so that :math:`A_{p} =0.5V_{c\max }` for C\ :sub:`3` plants (as in :ref:`Collatz et al. 1992 `). For C\ :sub:`4` plants, the light-limited rate :math:`A_{j}` varies with :math:`\phi` in relation to the quantum efficiency (:math:`\alpha =0.05` mol CO\ :sub:`2` mol\ :sup:`-1` photon). :math:`\phi` is the absorbed photosynthetically active radiation (W m\ :sup:`-2`) (section :numref:`Solar Fluxes`), which is converted to photosynthetic photon flux assuming 4.6 :math:`\mu` \ mol photons per joule. :math:`k_{p}` is the initial slope of C\ :sub:`4` CO\ :sub:`2` response curve. +In these equations, :math:`c_{i}` is the internal leaf CO\ :sub:`2` partial pressure (Pa) and :math:`o_{i} =0.209P_{atm}` is the O\ :sub:`2` partial pressure (Pa) (where 0.209 is the value of the atmospheric O\ :sub:`2` molar ratio in mol/mol). :math:`K_{c}` and :math:`K_{o}` are the Michaelis-Menten constants (Pa) for CO\ :sub:`2` and O\ :sub:`2`. :math:`\Gamma _{*}` (Pa) is the CO\ :sub:`2` compensation point. :math:`V_{c\max }` is the maximum rate of carboxylation (µmol m\ :sup:`-2` s\ :sup:`-1`, Chapter :numref:`rst_Photosynthetic Capacity`) and :math:`J_{x}` is the electron transport rate (µmol m\ :sup:`-2` s\ :sup:`-1`). :math:`T_{p}` is the triose phosphate utilization rate (µmol m\ :sup:`-2` s\ :sup:`-1`), taken as :math:`T_{p} =0.167V_{c\max }` so that :math:`A_{p} =0.5V_{c\max }` for C\ :sub:`3` plants (as in :ref:`Collatz et al. 1992 `). For C\ :sub:`4` plants, the light-limited rate :math:`A_{j}` varies with :math:`\phi` in relation to the quantum efficiency (:math:`\alpha =0.05` mol CO\ :sub:`2` mol\ :sup:`-1` photon). :math:`\phi` is the absorbed photosynthetically active radiation (W m\ :sup:`-2`) (section :numref:`Solar Fluxes`), which is converted to photosynthetic photon flux assuming 4.6 :math:`\mu` \ mol photons per joule. :math:`k_{p}` is the initial slope of C\ :sub:`4` CO\ :sub:`2` response curve. For C\ :sub:`3` plants, the electron transport rate depends on the photosynthetically active radiation absorbed by the leaf. A common expression is the smaller of the two roots of the equation @@ -146,37 +146,31 @@ where :math:`J_{\max }` is the maximum potential rate of electron transport (:ma I_{PSII} =0.5\Phi _{PSII} (4.6\phi ) -where :math:`\Phi _{PSII}` is the quantum yield of photosystem II, and the term 0.5 arises because one photon is absorbed by each of the two photosystems to move one electron. Parameter values are :math:`\Theta _{PSII}` \ = 0.7 and :math:`\Phi _{PSII}` \ = 0.85. In calculating :math:`A_{j}` (for both C\ :sub:`3` and C\ :sub:`4` plants), :math:`\phi =\phi ^{sun}` for sunlit leaves and :math:`\phi =\phi ^{sha}` for shaded leaves. +where :math:`\Phi _{PSII}` is the quantum yield of photosystem II, and the term 0.5 arises because one photon is absorbed by each of the two photosystems to move one electron. Parameter values are :math:`\Theta _{PSII}` \ = 0.7 and :math:`\Phi _{PSII} = 1 - f_{nps} = 0.85`, where :math:`f_{nps}` is the fraction of light absorbed by non-photosynthetic pigment. In calculating :math:`A_{j}` (for both C\ :sub:`3` and C\ :sub:`4` plants), :math:`\phi =\phi ^{sun}` for sunlit leaves and :math:`\phi =\phi ^{sha}` for shaded leaves. The model uses co-limitation as described by :ref:`Collatz et al. (1991, 1992) `. The actual gross photosynthesis rate, :math:`A`, is given by the smaller root of the equations .. math:: :label: 9.8 - \begin{array}{rcl} {\Theta _{cj} A_{i}^{2} -\left(A_{c} +A_{j} \right)A_{i} +A_{c} A_{j} } & {=} & {0} \\ {\Theta _{ip} A^{2} -\left(A_{i} +A_{p} \right)A+A_{i} A_{p} } & {=} & {0} \end{array} . - -Values are :math:`\Theta _{cj} =0.98` and :math:`\Theta _{ip} =0.95` for C\ :sub:`3` plants; and :math:`\Theta _{cj} =0.80`\ and :math:`\Theta _{ip} =0.95` for C\ :sub:`4` plants. :math:`A_{i}` is the intermediate co-limited photosynthesis. :math:`A_{n} =A-R_{d}`. + \begin{array}{rcl} {\Theta _{cj} A_{i}^{2} -\left(A_{c} +A_{j} \right)A_{i} +A_{c} A_{j} } & {=} & {0} \\ {\Theta _{ip} A^{2} -\left(A_{i} +A_{p} \right)A+A_{i} A_{p} } & {=} & {0} \end{array} -The parameters :math:`K_{c}`, :math:`K_{o}`, and :math:`\Gamma` depend on temperature. Values at 25 °C are :math:`K_{c25} ={\rm 4}0{\rm 4}.{\rm 9}\times 10^{-6} P_{atm}`, :math:`K_{o25} =278.4\times 10^{-3} P_{atm}`, and :math:`\Gamma _{25} {\rm =42}.75\times 10^{-6} P_{atm}`. :math:`V_{c\max }`, :math:`J_{\max }`, :math:`T_{p}`, :math:`k_{p}`, and :math:`R_{d}` also vary with temperature. +Values are :math:`\Theta _{cj} =0.9393` and :math:`\Theta _{ip} =0.95` for C\ :sub:`3` plants, :math:`\Theta _{cj} =0.80` and :math:`\Theta _{ip} =0.95` for C\ :sub:`4` plants, and :math:`\Theta _{cj} =0.98` for C\ :sub:`3` non-generic crops. :math:`A_{i}` is the intermediate co-limited photosynthesis. -:math:`J_{\max 25}` at 25 :sup:`\o`\ C: is calculated by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) +Now we write Eq. :eq:`leaf_net_psn` as :math:`A_{n} = A - \beta_{t} R_{d}` with :math:`\beta_{t}` as defined in Eq. :eq:`rubisco_lim_rate_of_carboxylation` to account for the effect of water stress on respiration. -Parameter values at 25 :sup:`\o`\ C are calculated from :math:`V_{c\max }` \ at 25 -:sup:`\o`\ C:, including: -:math:`T_{p25} =0.167V_{c\max 25}`, and -:math:`R_{d25} =0.015V_{c\max 25}` (C\ :sub:`3`) and -:math:`R_{d25} =0.025V_{c\max 25}` (C\ :sub:`4`). +The parameters :math:`K_{c}`, :math:`K_{o}`, and :math:`\Gamma _{*}` depend on temperature. Values at 25°C are :math:`K_{c25} ={\rm 4}0{\rm 4}.{\rm 9}\times 10^{-6} P_{atm}`, :math:`K_{o25} =278.4\times 10^{-3} P_{atm}`, and :math:`\Gamma _{*25} {\rm =42}.75\times 10^{-6} P_{atm}`. -For C\ :sub:`4` plants, :math:`k_{p25} =20000\; V_{c\max 25}`. +:math:`V_{c\max }`, :math:`J_{\max }`, :math:`T_{p}`, :math:`k_{p}`, and :math:`R_{d}` also vary with temperature. :math:`J_{\max 25}` at 25\ :sup:`\o`\ C is calculated by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`). -However, when the biogeochemistry is active (the default mode), :math:`R_{d25}` is calculated from leaf nitrogen as described in (Chapter :numref:`rst_Plant Respiration`) +Parameter values at 25\ :sup:`\o`\ C are calculated from :math:`V_{c\max }` \ at 25\ :sup:`\o`\ C, including: :math:`T_{p25} =0.167V_{c\max 25}`, :math:`R_{d25} =0.015V_{c\max 25}` (C\ :sub:`3`), and :math:`R_{d25} =0.025V_{c\max 25}` (C\ :sub:`4`). For C\ :sub:`4` plants, :math:`k_{p25} =20000\; V_{c\max 25}`. However, in active biogeochemistry mode (default), :math:`R_{d25}` is calculated from leaf nitrogen (see Chapter :numref:`rst_Plant Respiration`) The parameters :math:`V_{c\max 25}`, :math:`J_{\max 25}`, :math:`T_{p25}`, :math:`k_{p25}`, and :math:`R_{d25}` are scaled over the canopy for sunlit and shaded leaves (section :numref:`Canopy scaling`). In C\ :sub:`3` plants, these are adjusted for leaf temperature, :math:`T_{v}` (K), as: .. math:: :label: 9.9 - \begin{array}{rcl} {V_{c\max } } & {=} & {V_{c\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {J_{\max } } & {=} & {J_{\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {T_{p} } & {=} & {T_{p25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {R_{d} } & {=} & {R_{d25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {K_{c} } & {=} & {K_{c25} \; f\left(T_{v} \right)} \\ {K_{o} } & {=} & {K_{o25} \; f\left(T_{v} \right)} \\ {\Gamma } & {=} & {\Gamma _{25} \; f\left(T_{v} \right)} \end{array} + \begin{array}{rcl} {V_{c\max } } & {=} & {V_{c\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {J_{\max } } & {=} & {J_{\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {T_{p} } & {=} & {T_{p25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {R_{d} } & {=} & {R_{d25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {K_{c} } & {=} & {K_{c25} \; f\left(T_{v} \right)} \\ {K_{o} } & {=} & {K_{o25} \; f\left(T_{v} \right)} \\ {\Gamma _{*}} & {=} & {\Gamma _{*25} \; f\left(T_{v} \right)} \end{array} .. math:: :label: 9.10 @@ -188,9 +182,9 @@ and .. math:: :label: 9.11 - f_{H} \left(T_{v} \right)=\frac{1+\exp \left(\frac{298.15\Delta S-\Delta H_{d} }{298.15\times 0.001R_{gas} } \right)}{1+\exp \left(\frac{\Delta ST_{v} -\Delta H_{d} }{0.001R_{gas} T_{v} } \right)} . + f_{H} \left(T_{v} \right)=\frac{1+\exp \left(\frac{298.15\Delta S-\Delta H_{d} }{298.15\times 0.001R_{gas} } \right)}{1+\exp \left(\frac{\Delta ST_{v} -\Delta H_{d} }{0.001R_{gas} T_{v} } \right)} -:numref:`Table Temperature dependence parameters for C3 photosynthesis` lists parameter values for :math:`\Delta H_{a}` and :math:`\Delta H_{d}`. :math:`\Delta S` is calculated separately for :math:`V_{c\max }` and :math:`J_{max }` to allow for temperature acclimation of photosynthesis (see equation :eq:`9.16`), and :math:`\Delta S` is 490 J mol :sup:`-1` K :sup:`-1` for :math:`R_d` (:ref:`Bonan et al. 2011`, :ref:`Lombardozzi et al. 2015`). Because :math:`T_{p}` as implemented here varies with :math:`V_{c\max }`, :math:`T_{p}` uses the same temperature parameters as :math:`V_{c\max}`. For C\ :sub:`4` plants, +:numref:`Table Temperature dependence parameters for C3 photosynthesis` lists parameter values for :math:`\Delta H_{a}` and :math:`\Delta H_{d}`. :math:`\Delta S` (entropy term) is calculated separately for :math:`V_{c\max }` and :math:`J_{max }` to allow for temperature acclimation of photosynthesis (see equation :eq:`9.16`), and :math:`\Delta S` is 490 J mol :sup:`-1` K :sup:`-1` for :math:`R_d` (:ref:`Bonan et al. 2011`, :ref:`Lombardozzi et al. 2015`). Because :math:`T_{p}` as implemented here varies with :math:`V_{c\max }`, :math:`T_{p}` uses the same temperature parameters as :math:`V_{c\max}`. For C\ :sub:`4` plants, .. math:: :label: 9.12 @@ -246,12 +240,12 @@ In the model, acclimation is implemented as in :ref:`Kattge and Knorr (2007) `; :ref:`Sollins 1982`), different species mixtures (:ref:`Gomes et al. 2003`), and different size and age classes (:ref:`Busing 2005`; :ref:`Law et al. 2003`). In CLM6, mortality formulations have evolved beyond a single fixed mortality parameter for all PFTs. The annual mortality (*r_mort*) has now become a PFT-dependent variable, with some woody PFTs by default assigned a value other than 0.02 (:numref:`Table Model default annual mortality rate`). + +.. _Table Model default annual mortality rate: + +.. table:: Model default annual mortality rate (*r_mort*) for woody PFTs + + +---------------------------------------------------+--------------------------------------+ + | Plant functional type | Mortality rate (yr :sup:`-1`) | + +===================================================+======================================+ + | NET Temperate | 0.0211945164991821 | + +---------------------------------------------------+--------------------------------------+ + | NET Boreal | 0.0174 | + +---------------------------------------------------+--------------------------------------+ + | NDT Boreal | 0.0198950093389492 | + +---------------------------------------------------+--------------------------------------+ + | BET Tropical | 0.024 | + +---------------------------------------------------+--------------------------------------+ + | BET Temperate | 0.0199981934178915 | + +---------------------------------------------------+--------------------------------------+ + | BDT Tropical | 0.0200001818014196 | + +---------------------------------------------------+--------------------------------------+ + | BDT Temperate | 0.0210684434513937 | + +---------------------------------------------------+--------------------------------------+ + | BDT Boreal | 0.024 | + +---------------------------------------------------+--------------------------------------+ + +PFT name abbreviations: NET = Needleleaf Evergreen Tree, NDT = Needleleaf Deciduous Tree, BET = Broadleaf Evergreen Tree, BDT = Broadleaf Deciduous Tree. Shrubs and grasses all still use the default 2% annual mortality rate. + + + +Conceptual representation +---------------------------------------------- +This section describes plant mortality in the biogeochemistry (BGC) configuration of CLM for non-FATES vegetation. It focuses on the representation of gap-phase mortality, which accounts for the aggregate loss of plant biomass due to processes such as disturbance, competition, age-related decline, and environmental stress. + +In this framework, mortality is represented as a first-order loss process, in which all vegetation carbon and nitrogen pools experience proportional losses over time. The equations presented in this section describe the pool-level mortality fluxes and their routing within the biogeochemical framework. + +This section does not describe mechanistic mortality processes represented in the Functionally Assembled Terrestrial Ecosystem Simulator (FATES), where mortality emerges from explicit demographic, physiological, and disturbance processes (see Chapter :numref:`rst_Dynamic Global Vegetation and FATES`). Readers interested in those formulations should refer to the `FATES documentation`_. Mortality associated with fire and land-use or harvest processes is treated separately in the Fire and Land Use Change sections (see Chapters :numref:`rst_Fire` and :numref:`rst_Transient Landcover Change`, respectively). Legacy dynamic vegetation configurations (CNDV) used related mortality formulations but are no longer actively supported; mechanistic dynamic vegetation and mortality processes in CTSM are now handled through FATES. + +.. _FATES documentation: https://fates-users-guide.readthedocs.io/en/latest/index.html + + +Implementation +---------------------------------------------- + +Vegetation carbon and nitrogen dynamics are implemented using a matrix-based formulation (:ref:`Lu et al. 2020`; :ref:`Liao et al. 2023`), in which the evolution of vegetation pools is governed by a combination of process-specific transfer and turnover operators. Within this framework, mortality is represented as one component of the overall vegetation transfer system, alongside phenological turnover and fire-related processes. -Plant mortality as described here applies to perennial vegetation types, and is intended to represent the death of individuals from a stand of plants due to the aggregate of processes such as wind throw, insect attack, disease, extreme temperatures or drought, and age-related decline in vigor. These processes are referred to in aggregate as "gap-phase" mortality. Mortality due to fire and anthropogenic land cover change are treated separately (see Chapters :numref:`rst_Fire` and :numref:`rst_Transient Landcover Change`, respectively). +The matrix formulation provides a compact representation of vegetation dynamics and organizes the bookkeeping of transfers among pools, but does not alter the underlying conceptual treatment of mortality as a proportional loss from vegetation pools. -Mortality Fluxes Leaving Vegetation Pools + +Mortality fluxes and routing ---------------------------------------------- -Whole-plant mortality is parameterized very simply, assuming a mortality rate of 2% yr\ :sup:`-1` for all vegetation types. This is clearly a gross oversimplification of an important process, and additional work is required to better constrain this process in different climate zones (:ref:`Keller et al. 2004`; :ref:`Sollins 1982`), for different species mixtures (:ref:`Gomes et al. 2003`), and for different size and age classes (:ref:`Busing 2005`; :ref:`Law et al. 2003`). Literature values for forest mortality rates range from at least 0.7% to 3.0% yr\ :sup:`-1`. Taking the annual rate of mortality (*am*, proportion yr\ :sup:`-1`) as 0.02, a mortality rate per second (*m*) is calculated as :math:`m={am\mathord{\left/ {\vphantom {am \left(365\cdot 86400\right)}} \right.} \left(365\cdot 86400\right)}`. All vegetation carbon and nitrogen pools for display, storage, and transfer are affected at rate *m*, with mortality fluxes out of vegetation pools eventually merged to the column level and deposited in litter pools. Mortality (*mort*) fluxes out of displayed vegetation carbon and nitrogen pools are +Carbon and nitrogen removed from vegetation pools are routed according to tissue type: + +- Leaf and fine-root pools are transferred to litter pools (labile, cellulose, and lignin components) + +- Stem and coarse-root pools are transferred to coarse woody debris pools + +- Storage and transfer pools are assumed to represent labile material and are therefore transferred to litter pools + +This formulation provides a simplified, bulk representation of mortality consistent with the structure of non-demographic CLM configurations. A conceptual diagram of vegetation fluxes and pools (:numref:`Figure Vegetation fluxes and pools`) can be found in Chapter :numref:`rst_CN Pools`. + + +Mortality fluxes leaving vegetation pools +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Whole-plant mortality is represented as a first-order process with a prescribed mortality rate. For an annual mortality fraction (:math:`a_m`, yr\ :sup:`-1`), the corresponding rate per unit time (second) :math:`m` is given by: .. math:: :label: 33.1) - CF_{leaf\_ mort} =CS_{leaf} m + m = \frac{a_m}{365 \times 86400} + +Mortality fluxes from vegetation carbon pools are computed as: .. math:: :label: 33.2) - CF_{froot\_ mort} =CS_{froot} m + CF_{i,mort} =CS_{i} m + +and similarly for nitrogen: .. math:: :label: 33.3) - CF_{livestem\_ mort} =CS_{livestem} m + NF_{i,mort} =NS_{i} m + +where :math:`CF_{i}` is carbon flux, :math:`CS_{i}` is carbon state variable (or pool), :math:`NF_{i}` is nitrogen flux, :math:`NS_{i}` is nitrogen state, for each vegetation pool :math:`i`, respectively. + +These fluxes are applied to all vegetation pools, including: + +- displayed pools: *leaf*, *froot*, *livestem*, *deadstem*, *livecroot*, *deadcroot* +- storage pools: *leaf_stor*, *froot_stor*, *livestem_stor*, *deadstem_stor*, *livecroot_stor*, *deadcroot_stor*, *gresp_stor* +- transfer pools: *leaf_xfer*, *froot_xfer*, *livestem_xfer*, *deadstem_xfer*, *livecroot_xfer*, *deadcroot_xfer*, *gresp_xfer* +- retranslocated pools: *retrans* + +where *croot* refers to coarse roots, *froot* refers to fine roots, *gresp* refers to growth respiration, *retrans* refers to retranslocated, *stor* refers to storage, and *xfer* refers to transfer. Note that *gresp* only exists in carbon pools, and *retrans* only exists in nitrogen pools. + + + +Aggregation to column level +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Analogous to the treatment of litterfall fluxes (Chapter :numref:`rst_Vegetation Phenology and Turnover`), mortality fluxes leaving the vegetation pools are first computed at the plant functional type (PFT) level and then aggregated to the column level according to the weighted distribution of PFT :math:`p` on the column (:math:`wcol_{p}` ), and deposited in litter or coarse woody debris pools, which are defined at the column level. + +- Non-woody tissue pools + +Carbon and nitrogen fluxes from mortality of displayed leaf and fine root into litter pools are calculated as .. math:: :label: 33.4) - CF_{deadstem\_ mort} =CS_{deadstem} m + CF_{leaf\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{leaf\_ mort} f_{lab\_ leaf,p} wcol_{p} .. math:: :label: 33.5) - CF_{livecroot\_ mort} =CS_{livecroot} m + CF_{leaf\_ mort,lit2} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{leaf\_ mort} f_{cel\_ leaf,p} wcol_{p} .. math:: :label: 33.6) - CF_{deadcroot\_ mort} =CS_{deadcroot} m + CF_{leaf\_ mort,lit3} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{leaf\_ mort} f_{lig\_ leaf,p} wcol_{p} .. math:: :label: 33.7) - NF_{leaf\_ mort} =NS_{leaf} m + CF_{froot\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{froot\_ mort} f_{lab\_ froot,p} wcol_{p} .. math:: :label: 33.8) - NF_{froot\_ mort} =NS_{froot} m + CF_{froot\_ mort,lit2} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{froot\_ mort} f_{cel\_ froot,p} wcol_{p} .. math:: :label: 33.9) - NF_{livestem\_ mort} =NS_{livestem} m + CF_{froot\_ mort,lit3} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{froot\_ mort} f_{lig\_ froot,p} wcol_{p} + +where :math:`{f}_{lab\_leaf,p}`, :math:`{f}_{cel\_leaf,p}`, and :math:`{f}_{lig\_leaf,p}` are the labile (lit1), cellulose/hemicellulose (lit2), and lignin (lit3) fractions of leaf litter for PFT :math:`p`, +and the same rule applies to the fine root litter fractions. +:math:`{wcol}_{p}` is the fractional contribution of PFT :math:`p` to the column, :math:`p` is an index through the plant functional types occurring on a column, and :math:`n_{\mathrm{pft}}` is the number of PFTs present in the column. + +Nitrogen fluxes to the litter pools are assumed to follow the C:N of the senescent tissue, and so are distributed using the same fractions used for carbon fluxes: .. math:: :label: 33.10) - NF_{deadstem\_ mort} =NS_{deadstem} m + NF_{leaf\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{leaf\_ mort} f_{lab\_ leaf,p} wcol_{p} .. math:: :label: 33.11) - NF_{livecroot\_ mort} =NS_{livecroot} m + NF_{leaf\_ mort,lit2} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{leaf\_ mort} f_{cel\_ leaf,p} wcol_{p} .. math:: :label: 33.12) - NF_{deadcroot\_ mort} =NS_{deadcroot} m + NF_{leaf\_ mort,lit3} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{leaf\_ mort} f_{lig\_ leaf,p} wcol_{p} .. math:: :label: 33.13) - NF_{retrans\_ mort} =NS_{retrans} m. - -where CF are carbon fluxes, CS is carbon storage, NF are nitrogen fluxes, NS is nitrogen storage, *croot* refers to coarse roots, *froot* refers to fine roots, and *retrans* refers to retranslocated. - -Mortality fluxes out of carbon and nitrogen storage (*stor)* pools are + NF_{froot\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{froot\_ mort} f_{lab\_ froot,p} wcol_{p} .. math:: :label: 33.14) - CF_{leaf\_ stor\_ mort} =CS_{leaf\_ stor} m + NF_{froot\_ mort,lit2} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{froot\_ mort} f_{cel\_ froot,p} wcol_{p} .. math:: :label: 33.15) - CF_{froot\_ stor\_ mort} =CS_{froot\_ stor} m + NF_{froot\_ mort,lit3} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{froot\_ mort} f_{lig\_ froot,p} wcol_{p} . + + +- Woody tissue pools + +Carbon and nitrogen mortality fluxes from displayed live and dead stem and coarse root pools are merged to the column level and deposited in the coarse woody debris (*cwd*) pools: .. math:: :label: 33.16) - CF_{livestem\_ stor\_ mort} =CS_{livestem\_ stor} m + CF_{livestem\_ mort,cwd} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{livestem\_ mort} wcol_{p} .. math:: :label: 33.17) - CF_{deadstem\_ stor\_ mort} =CS_{deadstem\_ stor} m + CF_{deadstem\_ mort,cwd} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{deadstem\_ mort} wcol_{p} .. math:: :label: 33.18) - CF_{livecroot\_ stor\_ mort} =CS_{livecroot\_ stor} m + CF_{livecroot\_ mort,cwd} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{livecroot\_ mort} wcol_{p} .. math:: :label: 33.19) - CF_{deadcroot\_ stor\_ mort} =CS_{deadcroot\_ stor} m + CF_{deadcroot\_ mort,cwd} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{deadcroot\_ mort} wcol_{p} .. math:: :label: 33.20) - CF_{gresp\_ stor\_ mort} =CS_{gresp\_ stor} m + NF_{livestem\_ mort,cwd} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{livestem\_ mort} wcol_{p} .. math:: :label: 33.21) - NF_{leaf\_ stor\_ mort} =NS_{leaf\_ stor} m + NF_{deadstem\_ mort,cwd} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{deadstem\_ mort} wcol_{p} .. math:: :label: 33.22) - NF_{froot\_ stor\_ mort} =NS_{froot\_ stor} m + NF_{livecroot\_ mort,cwd} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{livecroot\_ mort} wcol_{p} .. math:: :label: 33.23) - NF_{livestem\_ stor\_ mort} =NS_{livestem\_ stor} m + NF_{deadcroot\_ mort,cwd} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{deadcroot\_ mort} wcol_{p} + +- Storage and transfer pools + +All vegetation storage and transfer pools for carbon and nitrogen are assumed to exist as labile pools within the plant (e.g. as carbohydrate stores, in the case of carbon pools). This assumption applies to storage and transfer pools for both non-woody and woody tissues. The mortality fluxes from these pools are therefore assumed to be deposited in the labile litter pools (:math:`{CS}_{lit1}`, :math:`{NS}_{lit1}`), after being merged to the column level. + +Carbon mortality fluxes out of storage and transfer pools are: .. math:: :label: 33.24) - NF_{deadstem\_ stor\_ mort} =NS_{deadstem\_ stor} m + CF_{leaf\_ stor\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{leaf\_ stor\_ mort} wcol_{p} .. math:: :label: 33.25) - NF_{livecroot\_ stor\_ mort} =NS_{livecroot\_ stor} m + CF_{froot\_ stor\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{froot\_ stor\_ mort} wcol_{p} .. math:: :label: 33.26) - NF_{deadcroot\_ stor\_ mort} =NS_{deadcroot\_ stor} m - -where *gresp* refers to growth respiration. - -Mortality fluxes out of carbon and nitrogen transfer (*xfer)* growth pools are + CF_{livestem\_ stor\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{livestem\_ stor\_ mort} wcol_{p} .. math:: :label: 33.27) - CF_{leaf\_ xfer\_ mort} =CS_{leaf\_ xfer} m + CF_{deadstem\_ stor\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{deadstem\_ stor\_ mort} wcol_{p} .. math:: :label: 33.28) - CF_{froot\_ xfer\_ mort} =CS_{froot\_ xfer} m + CF_{livecroot\_ stor\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{livecroot\_ stor\_ mort} wcol_{p} .. math:: :label: 33.29) - CF_{livestem\_ xfer\_ mort} =CS_{livestem\_ xfer} m + CF_{deadcroot\_ stor\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{deadcroot\_ stor\_ mort} wcol_{p} .. math:: :label: 33.30) - CF_{deadstem\_ xfer\_ mort} =CS_{deadstem\_ xfer} m + CF_{gresp\_ stor\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{gresp\_ stor\_ mort} wcol_{p} .. math:: :label: 33.31) - CF_{livecroot\_ xfer\_ mort} =CS_{livecroot\_ xfer} m + CF_{leaf\_ xfer\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{leaf\_ xfer\_ mort} wcol_{p} .. math:: :label: 33.32) - CF_{deadcroot\_ xfer\_ mort} =CS_{deadcroot\_ xfer} m + CF_{froot\_ xfer\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{froot\_ xfer\_ mort} wcol_{p} .. math:: :label: 33.33) - CF_{gresp\_ xfer\_ mort} =CS_{gresp\_ xfer} m + CF_{livestem\_ xfer\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{livestem\_ xfer\_ mort} wcol_{p} .. math:: :label: 33.34) - NF_{leaf\_ xfer\_ mort} =NS_{leaf\_ xfer} m + CF_{deadstem\_ xfer\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{deadstem\_ xfer\_ mort} wcol_{p} .. math:: :label: 33.35) - NF_{froot\_ xfer\_ mort} =NS_{froot\_ xfer} m + CF_{livecroot\_ xfer\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{livecroot\_ xfer\_ mort} wcol_{p} .. math:: :label: 33.36) - NF_{livestem\_ xfer\_ mort} =NS_{livestem\_ xfer} m + CF_{deadcroot\_ xfer\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{deadcroot\_ xfer\_ mort} wcol_{p} .. math:: :label: 33.37) - NF_{deadstem\_ xfer\_ mort} =NS_{deadstem\_ xfer} m + CF_{gresp\_ xfer\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}CF_{gresp\_ xfer\_ mort} wcol_{p} . + +Nitrogen mortality fluxes out of storage and transfer pools, including the storage pool for retranslocated nitrogen, are calculated as: .. math:: :label: 33.38) - NF_{livecroot\_ xfer\_ mort} =NS_{livecroot\_ xfer} m + NF_{leaf\_ stor\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{leaf\_ stor\_ mort} wcol_{p} .. math:: :label: 33.39) - NF_{deadcroot\_ xfer\_ mort} =NS_{deadcroot\_ xfer} m - -Mortality Fluxes Merged to the Column Level ------------------------------------------------- - -Analogous to the treatment of litterfall fluxes, mortality fluxes leaving the vegetation pools are merged to the column level according to the weighted distribution of PFTs on the column (:math:`wcol_{p}` ), and deposited in litter and coarse woody debris pools, which are defined at the column level. Carbon and nitrogen fluxes from mortality of displayed leaf and fine root into litter pools are calculated as - + NF_{froot\_ stor\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{froot\_ stor\_ mort} wcol_{p} + .. math:: :label: 33.40) - CF_{leaf\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{leaf\_ mort} f_{lab\_ leaf,p} wcol_{p} + NF_{livestem\_ stor\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{livestem\_ stor\_ mort} wcol_{p} .. math:: :label: 33.41) - CF_{leaf\_ mort,lit2} =\sum _{p=0}^{npfts}CF_{leaf\_ mort} f_{cel\_ leaf,p} wcol_{p} + NF_{deadstem\_ stor\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{deadstem\_ stor\_ mort} wcol_{p} .. math:: :label: 33.42) - CF_{leaf\_ mort,lit3} =\sum _{p=0}^{npfts}CF_{leaf\_ mort} f_{lig\_ leaf,p} wcol_{p} + NF_{livecroot\_ stor\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{livecroot\_ stor\_ mort} wcol_{p} .. math:: :label: 33.43) - CF_{froot\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{froot\_ mort} f_{lab\_ froot,p} wcol_{p} + NF_{deadcroot\_ stor\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{deadcroot\_ stor\_ mort} wcol_{p} .. math:: :label: 33.44) - CF_{froot\_ mort,lit2} =\sum _{p=0}^{npfts}CF_{froot\_ mort} f_{cel\_ froot,p} wcol_{p} + NF_{retrans\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{retrans\_ mort} wcol_{p} .. math:: :label: 33.45) - CF_{froot\_ mort,lit3} =\sum _{p=0}^{npfts}CF_{froot\_ mort} f_{lig\_ froot,p} wcol_{p} + NF_{leaf\_ xfer\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{leaf\_ xfer\_ mort} wcol_{p} .. math:: :label: 33.46) - NF_{leaf\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{leaf\_ mort} f_{lab\_ leaf,p} wcol_{p} + NF_{froot\_ xfer\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{froot\_ xfer\_ mort} wcol_{p} .. math:: :label: 33.47) - NF_{leaf\_ mort,lit2} =\sum _{p=0}^{npfts}NF_{leaf\_ mort} f_{cel\_ leaf,p} wcol_{p} + NF_{livestem\_ xfer\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{livestem\_ xfer\_ mort} wcol_{p} .. math:: :label: 33.48) - NF_{leaf\_ mort,lit3} =\sum _{p=0}^{npfts}NF_{leaf\_ mort} f_{lig\_ leaf,p} wcol_{p} + NF_{deadstem\_ xfer\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{deadstem\_ xfer\_ mort} wcol_{p} .. math:: :label: 33.49) - NF_{froot\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{froot\_ mort} f_{lab\_ froot,p} wcol_{p} + NF_{livecroot\_ xfer\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{livecroot\_ xfer\_ mort} wcol_{p} .. math:: :label: 33.50) - NF_{froot\_ mort,lit2} =\sum _{p=0}^{npfts}NF_{froot\_ mort} f_{cel\_ froot,p} wcol_{p} - -.. math:: - :label: 33.51) - - NF_{froot\_ mort,lit3} =\sum _{p=0}^{npfts}NF_{froot\_ mort} f_{lig\_ froot,p} wcol_{p} . - -where *lab* refers to labile, *cel* refers to cellulose, and *lig* refers to lignin. Carbon and nitrogen mortality fluxes from displayed live and dead stem and coarse root pools are merged to the column level and deposited in the coarse woody debris (*cwd*) pools: - -.. math:: - :label: 33.52) - - CF_{livestem\_ mort,cwd} =\sum _{p=0}^{npfts}CF_{livestem\_ mort} wcol_{p} - -.. math:: - :label: 33.53) - - CF_{deadstem\_ mort,cwd} =\sum _{p=0}^{npfts}CF_{deadstem\_ mort} wcol_{p} - -.. math:: - :label: 33.54) - - CF_{livecroot\_ mort,cwd} =\sum _{p=0}^{npfts}CF_{livecroot\_ mort} wcol_{p} - -.. math:: - :label: 33.55) - - CF_{deadcroot\_ mort,cwd} =\sum _{p=0}^{npfts}CF_{deadcroot\_ mort} wcol_{p} - -.. math:: - :label: 33.56) - - NF_{livestem\_ mort,cwd} =\sum _{p=0}^{npfts}NF_{livestem\_ mort} wcol_{p} - -.. math:: - :label: 33.57) - - NF_{deadstem\_ mort,cwd} =\sum _{p=0}^{npfts}NF_{deadstem\_ mort} wcol_{p} - -.. math:: - :label: 33.58) - - NF_{livecroot\_ mort,cwd} =\sum _{p=0}^{npfts}NF_{livecroot\_ mort} wcol_{p} - -.. math:: - :label: 33.59) - - NF_{deadcroot\_ mort,cwd} =\sum _{p=0}^{npfts}NF_{deadcroot\_ mort} wcol_{p} - -All vegetation storage and transfer pools for carbon and nitrogen are assumed to exist as labile pools within the plant (e.g. as carbohydrate stores, in the case of carbon pools). This assumption applies to storage and transfer pools for both non-woody and woody tissues. The mortality fluxes from these pools are therefore assumed to be deposited in the labile litter pools (:math:`{CS}_{lit1}`, :math:`{NS}_{lit1}`), after being merged to the column level. Carbon mortality fluxes out of storage and transfer pools are: - -.. math:: - :label: 33.60) - - CF_{leaf\_ stor\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{leaf\_ stor\_ mort} wcol_{p} - -.. math:: - :label: 33.61) - - CF_{froot\_ stor\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{froot\_ stor\_ mort} wcol_{p} - -.. math:: - :label: 33.62) - - CF_{livestem\_ stor\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{livestem\_ stor\_ mort} wcol_{p} - -.. math:: - :label: 33.63) - - CF_{deadstem\_ stor\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{deadstem\_ stor\_ mort} wcol_{p} - -.. math:: - :label: 33.64) - - CF_{livecroot\_ stor\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{livecroot\_ stor\_ mort} wcol_{p} - -.. math:: - :label: 33.65) - - CF_{deadcroot\_ stor\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{deadcroot\_ stor\_ mort} wcol_{p} - -.. math:: - :label: 33.66) - - CF_{gresp\_ stor\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{gresp\_ stor\_ mort} wcol_{p} - -.. math:: - :label: 33.67) - - CF_{leaf\_ xfer\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{leaf\_ xfer\_ mort} wcol_{p} - -.. math:: - :label: 33.68) - - CF_{froot\_ xfer\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{froot\_ xfer\_ mort} wcol_{p} - -.. math:: - :label: 33.69) - - CF_{livestem\_ xfer\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{livestem\_ xfer\_ mort} wcol_{p} - -.. math:: - :label: 33.70) - - CF_{deadstem\_ xfer\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{deadstem\_ xfer\_ mort} wcol_{p} - -.. math:: - :label: 33.71) - - CF_{livecroot\_ xfer\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{livecroot\_ xfer\_ mort} wcol_{p} - -.. math:: - :label: 33.72) - - CF_{deadcroot\_ xfer\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{deadcroot\_ xfer\_ mort} wcol_{p} - -.. math:: - :label: 33.73) - - CF_{gresp\_ xfer\_ mort,lit1} =\sum _{p=0}^{npfts}CF_{gresp\_ xfer\_ mort} wcol_{p} . - -Nitrogen mortality fluxes out of storage and transfer pools, including the storage pool for retranslocated nitrogen, are calculated as: - -.. math:: - :label: 33.74) - - NF_{leaf\_ stor\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{leaf\_ stor\_ mort} wcol_{p} - -.. math:: - :label: 33.75) - - NF_{froot\_ stor\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{froot\_ stor\_ mort} wcol_{p} - -.. math:: - :label: 33.76) - - NF_{livestem\_ stor\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{livestem\_ stor\_ mort} wcol_{p} - -.. math:: - :label: 33.77) - - NF_{deadstem\_ stor\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{deadstem\_ stor\_ mort} wcol_{p} - -.. math:: - :label: 33.78) - - NF_{livecroot\_ stor\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{livecroot\_ stor\_ mort} wcol_{p} - -.. math:: - :label: 33.79) - - NF_{deadcroot\_ stor\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{deadcroot\_ stor\_ mort} wcol_{p} - -.. math:: - :label: 33.80) - - NF_{retrans\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{retrans\_ mort} wcol_{p} - -.. math:: - :label: 33.81) - - NF_{leaf\_ xfer\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{leaf\_ xfer\_ mort} wcol_{p} - -.. math:: - :label: 33.82) - - NF_{froot\_ xfer\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{froot\_ xfer\_ mort} wcol_{p} - -.. math:: - :label: 33.83) - - NF_{livestem\_ xfer\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{livestem\_ xfer\_ mort} wcol_{p} - -.. math:: - :label: 33.84) - - NF_{deadstem\_ xfer\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{deadstem\_ xfer\_ mort} wcol_{p} - -.. math:: - :label: 33.85) - - NF_{livecroot\_ xfer\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{livecroot\_ xfer\_ mort} wcol_{p} - -.. math:: - :label: 33.86) - - NF_{deadcroot\_ xfer\_ mort,lit1} =\sum _{p=0}^{npfts}NF_{deadcroot\_ xfer\_ mort} wcol_{p} . + NF_{deadcroot\_ xfer\_ mort,lit1} =\sum _{p=0}^{n_{\mathrm{pft}}}NF_{deadcroot\_ xfer\_ mort} wcol_{p} . diff --git a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst index 69f100f435..b43b5879a8 100644 --- a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst +++ b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst @@ -2,81 +2,87 @@ Plant Respiration ================= -CLM5 includes changes to plant respiration including - - A new leaf respiration algorithm based on Atkin et al. (2016) - - A lower growth respiration coefficient, based on Atkin et al. (2017) Autotrophic Respiration ---------------------------- -The model treats maintenance and growth respiration fluxes separately, even though it is difficult to measure them as separate fluxes (Lavigne and Ryan, 1997; Sprugel et al., 1995). Maintenance respiration is defined as the carbon cost to support the metabolic activity of existing live tissue, while growth respiration is defined as the additional carbon cost for the synthesis of new growth. +The model treats maintenance and growth respiration fluxes separately, even though it is difficult to measure them as separate fluxes (:ref:`Lavigne and Ryan 1997 `; :ref:`Sprugel et al. 1995 `). Maintenance respiration is defined as the carbon cost to support the metabolic activity of existing live tissue, while growth respiration is defined as the additional carbon cost for the synthesis of new growth. Maintenance Respiration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Atkin et al. (2016) propose a model for leaf respiration that is based on the leaf nitrogen content per unit area (:math:`NS_{narea}` , gN m\ :sup:`-2` leaf), with an intercept parameter that is PFT dependant, and an acclimation term that depends upon the average temperature of the previous 10 day period :math:`t_{2m,10days}`, in Celsius. +Maintenance respiration is calculated separately for leaves, live stems, live coarse roots, and fine roots. For leaf maintenance respiration (:math:`CF_{mr\_ leaf}`; gC m\ :sup:`-2` s\ :sup:`-1`), :ref:`Atkin et al. (2015)` propose a model that includes an intercept parameter that is PFT-dependent (:math:`i_{atkin,pft}`; see :numref:`Table Atkin leaf respiration model intercept values` for values), a term for leaf nitrogen content per unit area (:math:`NS_{narea}`; gN m\ :sup:`-2` leaf), and an acclimation term that depends on the average temperature of the previous 10 day period (:math:`t_{2m,10days}`; °C). Leaf maintenance respiration carbon flux is calculated as: .. math:: :label: 17.46) CF_{mr\_ leaf} = i_{atkin,pft} + (NS_{narea} 0.2061) - (0.0402 (t_{2m,10days})) -The temperature dependance of leaf maintenance (dark) respiration is described in Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`. +The temperature dependence of leaf maintenance (dark) respiration is described in Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`. + +Live stem (:math:`CF_{mr\_ livestem}`; gC m\ :sup:`-2` s\ :sup:`-1`), live coarse root (:math:`CF_{mr\_ livecroot}`; gC m\ :sup:`-2` s\ :sup:`-1`), and fine root (:math:`CF_{mr\_ froot}`; gC m\ :sup:`-2` s\ :sup:`-1`) maintenance respiration are calculated as the product of a nitrogen-scaled base respiration rate and a Q10-based temperature scaling. :math:`MR_{base}` (gC gN\ :sup:`-1` s\ :sup:`-1`) represents the base respiration rate per unit nitrogen, :math:`MR_{Q10}` (= 1.5) is the temperature sensitivity for maintenance respiration, and :math:`T_{2m}` (°C) is the air temperature at 2m height. :math:`NS_{livestem}` (gN m\ :sup:`-2` live stem), :math:`NS_{livecroot}` (gN m\ :sup:`-2` live coarse root), and :math:`NS_{froot}` (gN m\ :sup:`-2` fine root) represent nitrogen content per unit area for live stem, live coarse root, and fine root, respectively. Finally, fine root respiration is calculated as the sum of contributions from each soil level *j*. :math:`rootfr_{j}` represents the fraction of fine roots distributed in soil level *j* and :math:`Ts_{j}` (°C) is the soil temperature at level *j*. Thus, + +Live stem maintenance respiration carbon flux is calculated as: .. math:: :label: 17.47) CF_{mr\_ livestem} =NS_{livestem} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} +Live coarse root respiration carbon flux is calculated as: + .. math:: :label: 17.48) CF_{mr\_ livecroot} =NS_{livecroot} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} +Fine root maintenance respiration carbon flux is calculated as: + .. math:: :label: 17.49) CF_{mr\_ froot} =\sum _{j=1}^{nlevsoi}NS_{froot} rootfr_{j} MR_{base} MR_{Q10} ^{(Ts_{j} -20)/10} -where :math:`MR_{q10}` (= 2.0) is the temperature sensitivity for maintenance respiration, :math:`T_{2m}` (°C) is the air temperature at 2m height, :math:`Ts_{j}`* (°C) is the soil temperature at level *j*, and :math:`rootfr_{j}` is the fraction of fine roots distributed in soil level *j*. +The total maintenance respiration cost (:math:`CF_{mr}`; gC m\ :sup:`-2` s\ :sup:`-1`) is then calculated as the sum of leaf (:math:`CF_{mr\_ leaf}`), fine root (:math:`CF_{mr\_ froot}`), live stem (:math:`CF_{mr\_ livestem}`), and live coarse root (:math:`CF_{mr\_ livecroot}`) components: + +.. math:: + :label: 17.50) + + CF_{mr} =CF_{mr\_ leaf} +CF_{mr\_ froot} +CF_{mr\_ livestem} +CF_{mr\_ livecroot} + + +.. _Table Atkin leaf respiration model intercept values: .. table:: Atkin leaf respiration model intercept values. ======================== ============= Plant functional type :math:`i_{atkin}` ======================== ============= - NET Temperate 1.499 - NET Boreal 1.499 - NDT Boreal 1.499 - BET Tropical 1.756 - BET temperate 1.756 - BDT tropical 1.756 - BDT temperate 1.756 - BDT boreal 1.756 - BES temperate 2.075 - BDS temperate 2.075 - BDS boreal 2.075 - C\ :sub:`3` arctic grass 2.196 - C\ :sub:`3` grass 2.196 - C\ :sub:`4` grass 2.196 + NET Temperate 1.5 + NET Boreal 1.42 + NDT Boreal 1.22 + BET Tropical 1.93 + BET temperate 1.82 + BDT tropical 1.5 + BDT temperate 1.64 + BDT boreal 1.41 + BES temperate 2.07 + BDS temperate 2.07 + BDS boreal 2.07 + C\ :sub:`3` arctic grass 2.2 + C\ :sub:`3` grass 2.35 + C\ :sub:`4` grass 2.2 ======================== ============= -Note that, for woody vegetation, maintenance respiration costs are not calculated for the dead stem and dead coarse root components. These components are assumed to consist of dead xylem cells, with no metabolic function. By separating the small live component of the woody tissue (ray parenchyma, phloem, and sheathing lateral meristem cells) from the larger fraction of dead woody tissue, it is reasonable to assume a common base maintenance respiration rate for all live tissue types. +Note that, for woody vegetation, maintenance respiration costs are not calculated for dead stem and dead coarse root components. These components are assumed to consist of dead xylem cells with no metabolic function. By separating the small live component of the woody tissue (ray parenchyma, phloem, and sheathing lateral meristem cells) from the larger fraction of dead woody tissue, it is reasonable to assume a common base maintenance respiration rate for all live tissue types. -The total maintenance respiration cost is then given as: - -.. math:: - :label: 17.50) - - CF_{mr} =CF_{mr\_ leaf} +CF_{mr\_ froot} +CF_{mr\_ livestem} +CF_{mr\_ livecroot} . .. _Growth Respiration: Growth Respiration ^^^^^^^^^^^^^^^^^^^^^^^^^ -Growth respiration is calculated as a factor of 0.11 times the total carbon allocation to new growth (:math:`CF_{growth}`, after allocating carbon for N acquisition, Chapter :numref:`rst_FUN`.) on a given timestep, based on construction costs for a range of woody and non-woody tissues, with estimates of the growth respiration flux revised downswards following (Atkin et al. 2017). For new carbon and nitrogen allocation that enters storage pools for subsequent display, it is not clear what fraction of the associated growth respiration should occur at the time of initial allocation, and what fraction should occur later, at the time of display of new growth from storage. Eddy covariance estimates of carbon fluxes in forest ecosystems suggest that the growth respiration associated with transfer of allocated carbon and nitrogen from storage into displayed tissue is not significant (Churkina et al., 2003), and so it is assumed in CLM that all of the growth respiration cost is incurred at the time of initial allocation, regardless of the fraction of allocation that is displayed immediately (i.e. regardless of the value of :math:`f_{cur}`, section 13.5). This behavior is parameterized in such a way that if future research suggests that some fraction of the growth respiration cost should be incurred at the time of display from storage, a simple parameter modification will effect the change. [1]_ +Growth respiration is calculated as a factor of 0.11 times the total carbon allocated to new growth (:math:`CF_{growth}`) after allocating carbon for N acquisition (see Chapter :numref:`rst_CN Allocation`) on a given timestep, based on construction costs for a range of woody and non-woody tissues. Estimates of the growth respiration flux were revised downward following :ref:`Atkin et al. (2017)`. For new carbon and nitrogen allocation that enters storage pools for subsequent display, it is not clear what fraction of the associated growth respiration should occur at the time of initial allocation, and what fraction should occur later, at the time of display of new growth from storage. Eddy covariance estimates of carbon fluxes in forest ecosystems suggest that the growth respiration associated with transfer of allocated carbon and nitrogen from storage into displayed tissue is not significant (:ref:`Churkina et al. 2003 `), so it is assumed in CLM that all of the growth respiration cost is incurred at the time of initial allocation, regardless of the fraction of allocation that is displayed immediately (i.e. regardless of the value of :math:`f_{cur}`, section :numref:`Carbon Allocation to New Growth`). This behavior is parameterized in such a way that if future research suggests that some fraction of the growth respiration cost should be incurred at the time of display from storage, a simple parameter modification will effect the change. [1]_ .. [1] - Parameter :math:`\text{grpnow}` in routines CNGResp and CNAllocation, currently set to 1.0, could be changed to a smaller value to transfer some portion (1 - :math:`\text{grpnow}` ) of the growth respiration forward in time to occur at the time of growth display from storage. - + Parameter :math:`\text{grpnow}` in routines CNGRespMod.F90 and CNAllocationMod.F90, currently set to 1.0, could be changed to a smaller value to transfer some portion (1 - :math:`\text{grpnow}` ) of the growth respiration forward in time to occur at the time of growth display from storage. diff --git a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst index df2b367b3a..4c7eed9d59 100644 --- a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst +++ b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst @@ -26,9 +26,7 @@ Solar Fluxes .. figure:: image1.png - Schematic diagram of (a) direct beam radiation, (b) diffuse solar radiation, and (c) longwave radiation absorbed, transmitted, and reflected by vegetation and ground. - -For clarity, terms involving :math:`T^{n+1} -T^{n}` are not shown in (c). + Schematic diagram of (a) direct beam radiation, (b) diffuse solar radiation, and (c) longwave radiation absorbed, transmitted, and reflected by vegetation and ground. For simplicity, terms involving :math:`T^{n+1} -T^{n}` (i.e. time stepping) are not shown in (c) but do get addressed later in this section. The total solar radiation absorbed by the vegetation and ground is @@ -79,7 +77,7 @@ with :math:`L^{sun}` and :math:`L^{sha}` the sunlit and shaded plant area index, L^{sun} =\frac{1-e^{-K(L+S)} }{K} -and the shaded leaf area index is :math:`L^{sha} =(L+S)-L^{sun}`. In calculating :math:`L^{sun}`, +and the shaded plant area index is :math:`L^{sha} =(L+S)-L^{sun}`. In calculating :math:`L^{sun}`, .. math:: :label: 4.8 @@ -182,7 +180,7 @@ These equations assume that absorptivity equals emissivity. The emissivity of th \varepsilon _{g} =\varepsilon _{soi} \left(1-f_{sno} \right)+\varepsilon _{sno} f_{sno} -where :math:`\varepsilon _{soi} =0.96` for soil, 0.97 for glacier, :math:`\varepsilon _{sno} =0.97`, and :math:`f_{sno}` is the fraction of ground covered by snow (section :numref:`Snow Covered Area Fraction`). The vegetation emissivity is +where :math:`\varepsilon _{soi} =0.96` for soil, :math:`\varepsilon _{sno} =0.97` for snow, which is also the same for glacier, and :math:`f_{sno}` is the fraction of ground covered by snow (section :numref:`Snow Covered Area Fraction`). The vegetation emissivity is .. math:: :label: 4.20 diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index e5191e247c..373618b522 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -67,13 +67,13 @@ Asner, G.P., Wessman, C.A., Schimel, D.S., and Archer, S. 1998. Variability in l Axelsson, E., and Axelsson, B. 1986. Changes in carbon allocation patterns in spruce and pine trees following irrigation and fertilization. Tree Phys. 2:189-204. -.. _Atkin2016: +.. _Atkinetal2015: -Atkin OK, Bloomfield KJ, Reich PB, Tjoelker MG, Asner GP, Bonal D et al (2015) Global variability in leaf respiration in relation to climate, plant functional types and leaf traits. New Phytologist 206:614–636 +Atkin O.K., Bloomfield K.J., Reich P.B., Tjoelker M.G., Asner G.P., Bonal D. et al. 2015. Global variability in leaf respiration in relation to climate, plant functional types and leaf traits. New Phytologist 206:614–636 -.. _Atkin2017: +.. _Atkinetal2017: -Leaf Respiration in Terrestrial Biosphere Models. In Plant Respiration: Metabolic Fluxes and Carbon Balance, Advances in Photosynthesis and Respiration 43, G. Tcherkez, J. Ghashghaie (eds.) Springer International Publishing AG 2017 +Atkin O.K., Abdul Bahar N., Bloomfield K., Griffin K.L., Heskel M.A., Huntingford C., Martinez-de la Torre A., Turnbull, M.H. 2017. Leaf Respiration in Terrestrial Biosphere Models. In Plant Respiration: Metabolic Fluxes and Carbon Balance, Advances in Photosynthesis and Respiration 43, G. Tcherkez, J. Ghashghaie (eds.) Springer International Publishing AG 2017 .. _BadgerandDirmeyer2015: @@ -172,6 +172,10 @@ Bonan, G.B., Williams, M., Fisher, R.A., and Oleson, K.W. 2014. Modeling stomata Botta, A et al., 2000. A global prognostic scheme of leaf onset using satellite data. Global Change Biology 6.7, pp. 709-725. +.. _BrieglebLight2007: + +Briegleb, B. P. and Light, B.: A Delta-Eddington multiple scattering parameterization for solar radiation in the sea ice component of the Community Climate System Model, NCAR/TN- 472+STR, National Center for Atmospheric Research, 108 pp., 2007 + .. _Brownetal1997: Brown J., Ferrians O. J. Jr, Heginbottom J. A. and Melnikov E. S. 1997. Circum-Arctic Map of Permafrost and Ground-Ice Conditions (Boulder, CO: National Snow and Ice Data Center) version 2, DOI: 10.3133/cp45 @@ -220,6 +224,10 @@ Castillo, G., Kendra, C., Levis, S., and Thornton, P. 2012. Evaluation of the ne Cao, M., Marshall, S. and Gregson, K., 1996. Global carbon exchange and methane emissions from natural wetlands: Application of a process-based model. J. Geophys. Res. 101(D9):14,399-14,414. +.. _Chenetal2023: + +Chen, Y., Hall, J., van Wees, D., Andela, N., Hantson, S., Giglio, L., van der Werf, G.R., Morton, D.C., Randerson, J.T. 2023. Multi-decadal trends and variability in burned area from the fifth version of the Global Fire Emissions Database (GFED5). Earth Syst. Sci. Data 15:5227-5259. + .. _Chengetal2019: Cheng, Y. et al., 2019. Parameterizing perennial bioenergy crops in Version 5 of the Community Land Model Based on Site‐Level Observations in the Central Midwestern United States. Journal of Advances in Modeling Earth Systems, 2(2013), 1–24. https://doi.org/10.1029/2019MS001719 @@ -308,6 +316,10 @@ Dai, A., and Trenberth, K.E. 2002. Estimates of freshwater discharge from contin Damseaux, A., Matthes, H., Dutch, V.R., Wake, L., and Rutter, N. 2025. Impact of snow thermal conductivity schemes on pan-Arctic permafrost dynamics in the Community Land Model version 5.0, The Cryosphere, 19, 1539–1558, DOI:10.5194/tc-19-1539-2025. +.. _Dangetal2019: + +Dang, C., Zender, C. S., & Flanner, M. G. (2019). Intercomparison and improvement of two‐stream shortwave radiative transfer schemes in Earth system models for a unified treatment of cryospheric surfaces. The Cryosphere, 13(9), 2325–2343. + .. _Darmenovaetal2009: Darmenova, K., Sokolik, I.N., Shao, Y., Marticorena, B. and Bergametti, G., 2009. Development of a physically based dust emission module within the Weather Research and Forecasting (WRF) model: Assessment of dust emission parameterizations and input parameters for source regions in Central and East Asia. Journal of Geophysical Research: Atmospheres, 114(D14). DOI:10.1029/2008JD011236. @@ -444,6 +456,10 @@ Flanner, M.G., and Zender, C.S. 2006. Linking snowpack microphysics and albedo e Flanner, M.G., Zender, C.S., Randerson, J.T., and Rasch, P.J. 2007. Present day climate forcing and response from black carbon in snow. J. Geophys. Res. 112:D11202. DOI:10.1029/2006JD008003. +.. _Flanneretal2021: + +Flanner, M. G., Arnheim, J. B., Cook, J. M., Dang, C., He, C., Huang, X., Singh, D., Skiles, S. M., Whicker, C. A., and Zender, C. S.: SNICAR-ADv3: a community tool for modeling spectral snow albedo, Geosci. Model Dev., 14, 7673–7704, 2021 + .. _Flatauetal1992: Flatau, P.J., Walko, R.L., and Cotton, W.R. 1992. Polynomial fits to saturation vapor pressure. J. Appl. Meteor. 31:1507-1513. @@ -504,10 +520,6 @@ Ghimire, B., W. J. Riley, C. D. Koven, M. Mu, and J. T. Randerson, 2016: Represe Gholz, H.L., Perry, C.S., Cropper, W.P., Jr. and Hendry, L.C., 1985. Litterfall, decomposition, and nitrogen and phosphorous dynamics in a chronosequence of slash pine (*Pinus elliottii*) plantations. Forest Science, 31: 463-478. -.. _Giglioetal2006: - -Giglio, L., Csiszar, I., and Justice, C.O. 2006. Global distribution and seasonality of active fires as observed with the Terra and Aqua Moderate Resolution Imaging Spectroradiometer (MODIS) sensors. J. Geophys. Res. 111:G02016. DOI:10.1029/2005JG000142. - .. _GlobalSoilDataTask2000: Global Soil Data Task 2000. Global soil data products CD-ROM (IGBP-DIS). International Geosphere-Biosphere Programme-Data and Information Available Services [Available online at http://www.daac.ornl.gov]. @@ -572,6 +584,18 @@ Hastings, D.A., Dunbar, P.K., Elphingstone, G.M., Bootz, M., Murakami, H., Maruy Hauser, E., Wieder, W.R., Bonan, G.B., and Cleveland, C.C. 2023. Flexible foliar stoichiometry reduces the magnitude of the global land carbon sink. Geophys. Res. Lett. 50(21), e2023GL105493. DOI:10.1029/2023GL105493 +.. _Heetal2017: + +He, C., Takano, Y., Liou, K. N., Yang, P., Li, Q., & Chen, F. (2017). Impact of snow grain shape and black carbon–snow internal mixing on snow optical properties: Parameterizations for climate models. Journal of Climate, 30(24), 10019–10036. + +.. _Heetal2019: + +He, C., Liou, K. N., Takano, Y., Chen, F., & Barlage, M. (2019). Enhanced snow absorption and albedo reduction by dust‐snow internal mixing: Modeling and parameterization. Journal of Advances in Modeling Earth Systems, 11(11), 3755–3776. + +.. _Heetal2024: + +He, C., Flanner, M., Lawrence, D. M., & Gu, Y. (2024). New features and enhancements in community land model (CLM5) snow albedo modeling: Description, sensitivity, and evaluation. Journal of Advances in Modeling Earth Systems, 16, e2023MS003861. + .. _Healdetal2008: Heald, C.L., Henze, D.K., Horowitz, L.W., Feddema, J., Lamarque, J.-F., Guenther, A., Hess, P.G., Vitt, F., Seinfeld, J.H., Goldstein, A.H., and Fung, I. 2008. Predicted change in global secondary organic aerosol concentrations in response to future climate, emissions, and land use change. J. Geophys. Res. 113:D05211. DOI:10.1029/2007JD009092. @@ -824,10 +848,6 @@ Lee, H., Swenson, S.C., Slater A.G. and Lawrence D.M., 2014. Effects of excess g Lehner, B., Verdin, K. and Jarvis, A., 2008. New global hydrograhy derived from spaceborne elevation data. Eos Trans., AGU, 89, 93 – 94. -.. _LePageetal2010: - -Le Page, Y., van der Werf, G.R., Morton, D.C., and Pereira, J.M.C. 2010. Modeling fire-driven deforestation potential in Amazonia under current and projected climate conditions. J. Geophys. Res. 115:G03012. DOI:10.1029/2009JG001190. - .. _Lerman1979: Lerman, A., 1979. Geochemical processes: Water and sediment environments. John Wiley and Sons, New York, N.Y. @@ -864,6 +884,10 @@ Levis, S., Bonan, G., Kluzek, E., Thornton, P., Jones, A., Sacks, W., and Kuchar Levis, S., Badger, A., Drewniak, B., Nevison, C., Ren, X. 2016. CLMcrop yields and water requirements: avoided impacts by choosing RCP 4.5 over 8.5. Climatic Change. DOI:10.1007/s10584-016-1654-9. +.. _Liaoetal2023: + +Liao, C., Lu X., Huang Y., Tao F., Lawrence D.M, Koven C.D., Oleson K.W., Wieder W.R., Kluzek E., Huang X., Luo Y. 2023 . Matrix Approach to Accelerate Spin-Up of CLM5. Journal of Advances in Modeling Earth Systems, 15(8), e2023MS003625. doi:10.1029/2023MS003625. + .. _Lietal2000: Li, C., Aber, J., Stange, F., Butterbach-Bahl, K. and Papen, H. 2000. A process-oriented model of N2O and NO emissions from forest soils: 1. Model development. J. Geophys. Res. 105(D4):4369-4384. @@ -880,6 +904,14 @@ Li, F., Zeng, X. D., and Levis, S. 2012b. Corrigendum to "A process-based fire p Li, F., Levis, S., and Ward, D. S. 2013a. Quantifying the role of fire in the Earth system – Part 1: Improved global fire modeling in the Community Earth System Model (CESM1). Biogeosciences 10:2293-2314. +.. _Lietal2019: + +Li, F., Val Martin, M., Andreae, M.O., Arneth, A., Hantson, S., Kaiser, J.W., Lasslop, G., Yue, C., Bachelet, D., Forrest, M., Kluzek, E., Liu, X., Mangeon, S., Melton, J.R., Ward, D.S., Darmenov, A., Hickler, T., Ichoku, C., Magi, B.I., Sitch, S., van der Werf, G.R., Wiedinmyer, C., Rabin, S.S. 2019. Historical (1700-2012) global multi-model estimates of the fire emissions from the Fire Modeling Intercomparison Project (FireMIP). Atmos. Chem. Phys. 19:12545-12567. + +.. _Lietal2024b: + +Li, F. et al. 2024. Quantifying the role of fire in the Earth system: Improved global fire modeling in Earth system models. AGU Fall Meeting 2024, Washington, D.C., USA, 9-13 December 2024, GC41E-01. https://agu.confex.com/agu/agu24/meetingapp.cgi/Paper/1529786. + .. _LiLawrence2017: Li, F., and Lawrence, D. 2017. Role of fire in the global land water budget during the 20th century through changing ecosystems. J. Clim. 30: 1894-1908. @@ -900,7 +932,7 @@ Li, H., L. Leung, A. Getirana, M. Huang, H. Wu, Y. Xu, J. Guo and N. Voisin. 201 Li, H., L. Leung, T. Tesfa, N. Voisin, M. Hejazi, L. Liu, Y. Liu, J. Rice, H. Wu, and X. Yang. 2015. Modeling stream temperature in the Anthropocene: An earth system modeling approach, J. Adv. Model. Earth Syst., 7, doi:10.1002/2015MS000471. -.. _Lietal2024: +.. _Lietal2024a: Li, X. "C", Zhao, L., Oleson, K., Zhou, Y., Qin, Y., Zhang, K., and Fang, B. 2024. Enhancing urban climate‐energy modeling in the Community Earth System Model (CESM) through explicit representation of urban air‐conditioning adoption. JAMES, 16, e2023MS004107. https://doi.org/10.1029/2023MS004107. @@ -948,6 +980,10 @@ Luo, Y., Hui, D., and Zhang, D. 2006. Elevated CO2 stimulates net accumulations Luo J, Hess P G, Hall S, et al. Agricultural emissions of reactive nitrogen gases from constrained simulations using the Community Land Model. Authorea Preprints, 2025. +.. _Luetal2020: + +Lu, X., Du, Z., Huang, Y., Lawrence, D., Kluzek, E., Collier, N., Lombardozzi, D., Sobhani, N., Schuur, E.A. and Luo, Y., 2020. Full implementation of matrix approach to biogeochemistry module of CLM5. Journal of Advances in Modeling Earth Systems, 12(11), p.e2020MS002105. + .. _Magilletal1997: Magill, A.H. et al., 1997. Biogeochemical response of forest ecosystems to simulated chronic nitrogen deposition. Ecological Applications, 7: 402-415. @@ -1205,6 +1241,10 @@ Peterson, D.L. and K.C. Ryan, 1986. Modeling postfire conifer mortality for long Petrescu, A.M.R. et al. 2010. Modeling regional to global CH4 emissions of boreal and arctic wetlands. Global Biogeochemical Cycles, 24(GB4009). +.. _Picardetal2016: + +Picard, G., Libois, Q., & Arnaud, L. (2016). Refinement of the ice absorption spectrum in the visible using radiance profile measurements in Antarctic snow. The Cryosphere, 10(6), 2655–2672. + .. _pfeiffer2013: Pfeiffer, M., A. Spessa, and J.O. Kaplan, 2013. A model for global biomass burning in preindustrial time: LPJ-LMfire (v1. 0). Geoscientific Model Development 6.3, pp. 643-685. @@ -1706,6 +1746,10 @@ Wania, R., Ross, I. and Prentice, I.C. 2009. Integrating peatlands and permafros Wania, R., Ross, I. and Prentice, I.C. 2010. Implementation and evaluation of a new methane model within a dynamic global vegetation model LPJ-WHyMe v1.3. Geoscientific Model Development Discussions 3:1-59. +.. _WarrenBrandt2008: + +Warren, S. G., & Brandt, R. E. (2008). Optical constants of ice from the ultraviolet to the microwave: A revised compilation. Journal of Geophysical Research, 113(D14), D14220. + .. _weng2014: Weng, E.S. et al., 2014. Scaling from individuals to ecosystems in an Earth System Model using a mathematically tractable model of height-structured competition for light. Biogeosciences Discussions 11.12, pp. 17757-17860. diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst index eefa967b80..b416f50c6c 100644 --- a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -3,7 +3,7 @@ Snow Hydrology =============== -The parameterizations for snow are based primarily on :ref:`Anderson (1976) `, :ref:`Jordan (1991) `, and :ref:`Dai and Zeng (1997) `. The snowpack can have up to twelve layers. These layers are indexed in the Fortran code as :math:`i=-11,-10,...,-1,0` where layer :math:`i=0` is the snow layer next to the top soil layer and layer :math:`i=-11` is the top layer of a twelve-layer snow pack. Since the number of snow layers varies according to the snow depth, we use the notation :math:`snl+1` to describe the top layer of snow for the variable layer snow pack, where :math:`snl` is the negative of the number of snow layers. Refer to :numref:`Figure three layer snow pack` for an example of the snow layer structure for a three layer snow pack. +The parameterizations for snow are based primarily on :ref:`Anderson (1976) `, :ref:`Jordan (1991) `, and :ref:`Dai and Zeng (1997) `. The snowpack can have up to twelve layers. These layers are indexed in the Fortran code as :math:`i=-11,-10,...,-1,0` where layer :math:`i=0` is the snow layer next to the top soil layer and layer :math:`i=-11` is the top layer of a twelve-layer snowpack. Since the number of snow layers varies according to the snow depth, we use the notation :math:`snl+1` to describe the top layer of snow for the variable layer snowpack, where :math:`snl` is the negative of the number of snow layers. Refer to :numref:`Figure three layer snow pack` for an example of the snow layer structure for a three layer snowpack. .. _Figure three layer snow pack: @@ -30,7 +30,7 @@ The state variables for snow are the mass of water :math:`w_{liq,i}` (kg m\ :sup \text{Water equivalent} = \text{Ice equivalent} \times \frac{\rho_\text{ice}}{\rho_\text{liq}} -Section :numref:`Snow Covered Area Fraction` describes the calculation of fractional snow covered area, which is used in the surface albedo calculation (Chapter :numref:`rst_Surface Albedos`) and the surface flux calculations (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`). The following two sections (:numref:`Ice Content` and :numref:`Water Content`) describe the ice and water content of the snow pack assuming that at least one snow layer exists. Section :numref:`Black and organic carbon and mineral dust within snow` describes how black and organic carbon and mineral dust particles are represented within snow, including meltwater flushing. See Section :numref:`Initialization of snow layer` for a description of how a snow layer is initialized. +Section :numref:`Snow Covered Area Fraction` describes the calculation of fractional snow covered area, which is used in the surface albedo calculation (Chapter :numref:`rst_Surface Albedos`) and the surface flux calculations (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`). Sections (:numref:`Ice Content` and :numref:`Water Content`) describe the ice and water content of the snowpack assuming that at least one snow layer exists. Section :numref:`Black and organic carbon and mineral dust within snow` describes how black and organic carbon and mineral dust particles are represented within snow, including meltwater scavenging. See Section :numref:`Initialization of snow layer` for a description of how a snow layer is initialized. .. _Snow Covered Area Fraction: @@ -113,8 +113,8 @@ The temperature dependent term is given by (:ref:`van Kampenhout et al. (2017) < \rho_{T} = \left\{\begin{array}{lr} - 50 + 1.7 \left(17\right)^{1.5} & \qquad T_{atm} >T_{f} +2 \ \\ - 50+1.7 \left(T_{atm} -T_{f} + 15\right)^{1.5} & \qquad T_{f} - 15 < T_{atm} \le T_{f} + 2 \ \\ + 50 + 1.7 \ \left(17\right)^{1.5} & \qquad T_{atm} >T_{f} +2 \ \\ + 50+1.7 \ \left(T_{atm} -T_{f} + 15\right)^{1.5} & \qquad T_{f} - 15 < T_{atm} \le T_{f} + 2 \ \\ -3.833 \ \left( T_{atm} -T_{f} \right) - 0.0333 \ \left( T_{atm} -T_{f} \right)^{2} &\qquad T_{atm} \le T_{f} - 15 \end{array}\right\} @@ -167,7 +167,7 @@ The snow water equivalent :math:`W_{sno}` is capped to not exceed 10,000 kg m\ : Water Content ^^^^^^^^^^^^^^^^^^^ -The conservation equation for mass of water in snow layers is +The conservation equation for mass of liquid water in snow layers is .. math:: :label: 8.26 @@ -228,7 +228,7 @@ Equations :eq:`8.29` - :eq:`8.33` are solved sequentially from top (:math:`i=snl Black and organic carbon and mineral dust within snow ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Particles within snow originate from atmospheric aerosol deposition (:math:`D_{sp}` in Table 2.3 (kg m\ :sup:`-2` s\ :sup:`-1`) and influence snow radiative transfer (sections :numref:`Snow Albedo`, :numref:`Snowpack Optical Properties`, and :numref:`Snow Aging`). Particle masses and mixing ratios are represented with a simple mass-conserving scheme. The model maintains masses of the following eight particle species within each snow layer: hydrophilic black carbon, hydrophobic black carbon, hydrophilic organic carbon, hydrophobic organic carbon, and four species of mineral dust with the following particle sizes: 0.1-1.0, 1.0-2.5, 2.5-5.0, and 5.0-10.0 :math:`\mu m`. Each of these species has unique optical properties (:numref:`Table Single-scatter albedo values used for snowpack impurities and ice`) and meltwater removal efficiencies (:numref:`Table Meltwater scavenging`). +Particles within snowpack originate from atmospheric aerosol deposition (:math:`D_{sp}` in Table 2.3, kg m\ :sup:`-2` s\ :sup:`-1`) and influence snowpack radiative transfer (sections :numref:`Snow Albedo`, :numref:`Snowpack Optical Properties`, and :numref:`Snow Aging`). Particle masses and mixing ratios are represented with a simple mass-conserving scheme. The model maintains masses of the following eight particle species within each snow layer: hydrophilic black carbon, hydrophobic black carbon, hydrophilic organic carbon, hydrophobic organic carbon, and four species of mineral dust with the following particle sizes: 0.1-1.0, 1.0-2.5, 2.5-5.0, and 5.0-10.0 :math:`\mu m`. Each of these species has unique optical properties (:numref:`Table Single-scatter albedo values used for snowpack impurities and ice`) and meltwater removal efficiencies (:numref:`Table Meltwater scavenging`). The black carbon and organic carbon deposition rates described in Table 2.3 are combined into four categories as follows @@ -252,7 +252,7 @@ The black carbon and organic carbon deposition rates described in Table 2.3 are D_{oc,\, hphob} =D_{oc,\, dryhphob} -Deposited particles are assumed to be instantly mixed (homogeneously) within the surface snow layer and are added after the inter-layer water fluxes are computed (section :numref:`Water Content`) so that some aerosol is in the top layer after deposition and is not immediately washed out before radiative calculations are done. Particle masses are then redistributed each time step based on meltwater drainage through the snow column (section :numref:`Water Content`) and snow layer combination and subdivision (section :numref:`Snow Layer Combination and Subdivision`). The change in mass of each of the particle species :math:`\Delta m_{sp,\, i}` (kg m\ :sup:`-2`) is +Deposited particles are assumed to be instantly mixed within the surface snow layer (black carbon and dust can be either internally or externally mixed with snow grains; section :numref:`Snow Albedo`) and are added after the inter-layer water fluxes are computed (section :numref:`Water Content`) so that some aerosol is in the top layer after deposition and is not immediately washed out before radiative calculations are done. Particle masses are then redistributed each time step based on meltwater drainage through the snow column (section :numref:`Water Content`) and snow layer combination and subdivision (section :numref:`Snow Layer Combination and Subdivision`). The change in mass of each of the particle species :math:`\Delta m_{sp,\, i}` (kg m\ :sup:`-2`) is .. math:: :label: 8.38 @@ -469,7 +469,7 @@ The latter equation (for the mobility index :math:`M_\mathrm{O}`) is a simplific Snow Layer Combination and Subdivision ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -After the determination of snow temperature including phase change(Chapter :numref:`rst_Soil and Snow Temperatures`), snow hydrology (Chapter :numref:`rst_Snow Hydrology`), and the compaction calculations (section :numref:`Snow Compaction`), the number of snow layers is adjusted by either combining or subdividing layers. The combination and subdivision of snow layers is based on :ref:`Jordan (1991) `. +After the determination of snow temperature including phase change (Chapter :numref:`rst_Soil and Snow Temperatures`), snow hydrology (Chapter :numref:`rst_Snow Hydrology`), and the compaction calculations (section :numref:`Snow Compaction`), the number of snow layers is adjusted by either combining or subdividing layers. The combination and subdivision of snow layers is based on :ref:`Jordan (1991) `. .. _Combination: @@ -617,5 +617,5 @@ then adjusted as, T_{2}^{n+1} = T_{2}^{n} +\left(\frac{T_{1}^{n} -T_{2}^{n} }{{\left(\Delta z_{1} +\Delta z_{2}^{n} \right)\mathord{\left/ {\vphantom {\left(\Delta z_{1} +\Delta z_{2}^{n} \right) 2}} \right.} 2} } \right)\left(\frac{\Delta z_{2}^{n+1} }{2} \right) & \qquad T'_{3} `. Albedo and the vertical absorption profile depend on solar zenith angle, albedo of the substrate underlying snow, mass concentrations of atmospheric-deposited aerosols (black carbon, mineral dust, and organic carbon), and ice effective grain size (:math:`r_{e}`), which is simulated with a snow aging routine described in section :numref:`Snow Aging`. Representation of impurity mass concentrations within the snowpack is described in section :numref:`Black and organic carbon and mineral dust within snow`. Implementation of SNICAR in CLM is also described somewhat by :ref:`Flanner and Zender (2005) ` and :ref:`Flanner et al. (2007) `. +Snow albedo and solar absorption within each snow layer are simulated with the Snow, Ice, and Aerosol Radiative Model (SNICAR-ADv3; :ref:`Flanner et al., 2021 `), which incorporates an adding-doubling radiative transfer solution (:ref:`Dang et al., 2019 `; :ref:`Briegleb and Light, 2007 `; Note that the original SNICAR uses the tri-diagonal matrix two-stream radiative transfer solution from :ref:`Toon et al., 1989 `). Snow albedo and the vertical light absorption profile depend on solar zenith angle, albedo of the substrate underlying snow, mass concentrations of atmospheric-deposited aerosols (black carbon, mineral dust, and organic carbon), snow layer thickness, snow density, and ice effective grain size (:math:`r_{e}`) that is simulated with a snow aging routine described in section :numref:`Snow Aging`. Representation of impurity mass concentrations within the snowpack is described in section :numref:`Black and organic carbon and mineral dust within snow`. Implementation of SNICAR-ADv3 in CTSM/CLM is described by :ref:`He et al. (2024) `, while the original SNICAR implementation is described by :ref:`Flanner and Zender (2005) `, and :ref:`Flanner et al. (2007) `. -The two-stream solution requires the following bulk optical properties for each snow layer and spectral band: extinction optical depth (:math:`\tau`), single-scatter albedo (:math:`\omega`), and scattering asymmetry parameter (*g*). The snow layers used for radiative calculations are identical to snow layers applied elsewhere in CLM, except for the case when snow mass is greater than zero but no snow layers exist. When this occurs, a single radiative layer is specified to have the column snow mass and an effective grain size of freshly-fallen snow (section :numref:`Snow Aging`). The bulk optical properties are weighted functions of each constituent *k*, computed for each snow layer and spectral band as +The adding-doubling two-stream solution requires the following bulk optical properties for each snow layer and spectral band: extinction optical depth (:math:`\tau`), single-scatter albedo (:math:`\omega`), and scattering asymmetry parameter (*g*). The snow layers used for radiative calculations are identical to snow layers applied elsewhere in CLM, except for the case when snow mass is greater than zero but no snow layers exist. When this occurs, a single radiative layer is specified to have the column snow mass and an effective grain size of freshly-fallen snow (section :numref:`Snow Aging`). For aerosols externally mixed with snow grains, the bulk optical properties are weighted functions of each constituent *k*, computed for each snow layer and spectral band as .. math:: :label: 3.62 @@ -539,14 +539,16 @@ The two-stream solution requires the following bulk optical properties for each g=\frac{\sum _{1}^{k}g_{k} \omega _{k} \tau _{k} }{\sum _{1}^{k}\omega _{k} \tau _{k} } -For each constituent (ice, two black carbon species, two organic carbon species, and four dust species), :math:`\omega`, *g*, and the mass extinction cross-section :math:`\psi` (m\ :sup:`2` kg\ :sub:`-1`) are computed offline with Mie Theory, e.g., applying the computational technique from :ref:`Bohren and Huffman (1983) `. The extinction optical depth for each constituent depends on its mass extinction cross-section and layer mass, :math:`w _{k}` (kg\ m\ :sup:`-1`) as +For each constituent (ice, two black carbon species, two organic carbon species, and four dust species), :math:`\omega`, *g*, and the mass extinction cross-section :math:`\psi` (m\ :sup:`2` kg\ :sup:`-1`) are pre-computed offline with Mie Theory by assuming lognormal size distribution for each constituent and applying the computational technique from :ref:`Bohren and Huffman (1983) `. The extinction optical depth for each constituent depends on its mass extinction cross-section and layer mass, :math:`w _{k}` (kg\ m\ :sup:`-1`) as .. math:: :label: 3.65 \tau _{k} =\psi _{k} w_{k} -The two-stream solution (:ref:`Toon et al. (1989) `) applies a tri-diagonal matrix solution to produce upward and downward radiative fluxes at each layer interface, from which net radiation, layer absorption, and surface albedo are easily derived. Solar fluxes are computed in five spectral bands, listed in :numref:`Table Spectral bands and weights used for snow radiative transfer`. Because snow albedo varies strongly across the solar spectrum, it was determined that four bands were needed to accurately represent the near-infrared (NIR) characteristics of snow, whereas only one band was needed for the visible spectrum. Boundaries of the NIR bands were selected to capture broad radiative features and maximize accuracy and computational efficiency. We partition NIR (0.7-5.0 :math:`\mu` m) surface downwelling flux from CLM according to the weights listed in :numref:`Table Spectral bands and weights used for snow radiative transfer`, which are unique for diffuse and direct incident flux. These fixed weights were determined with offline hyperspectral radiative transfer calculations for an atmosphere typical of mid-latitude winter (:ref:`Flanner et al. (2007) `). The tri-diagonal solution includes intermediate terms that allow for easy interchange of two-stream techniques. We apply the Eddington solution for the visible band (following :ref:`Wiscombe and Warren 1980 `) and the hemispheric mean solution ((:ref:`Toon et al. (1989) `) for NIR bands. These choices were made because the Eddington scheme works well for highly scattering media, but can produce negative albedo for absorptive NIR bands with diffuse incident flux. Delta scalings are applied to :math:`\tau`, :math:`\omega`, and :math:`g` (:ref:`Wiscombe and Warren 1980 `) in all spectral bands, producing effective values (denoted with :math:`*`) that are applied in the two-stream solution +Compared to the original SNICAR implementation, the SNICAR-ADv3 implementation includes two new features: nonspherical snow grain shape (:ref:`He et al., 2017 `) and aerosol-snow internal mixing for black carbon (BC) and dust (:ref:`He et al., 2017 `; :ref:`He et al., 2019 `). The original SNICAR assumes spherical snow grains, which however may not be a realistic representation since nonspherical snow grains are ubiquitous in reality. Thus, in SNICAR-ADv3, four typical snow grain shapes representative of real‐world observations, including sphere, spheroid, hexagonal plate/column, and fractal snowflake are used. The :ref:`He et al. (2017) ` parameterizations are used to quantify snow grain nonsphericity impacts on snow asymmetry factor (*g*) before the calculation of bulk optical properties (equation :eq:`3.64`). Snow extinction optical depth (:math:`\tau`) and single-scattering albedo (:math:`\omega`) are not modified. The default snow grain shape is set to hexagonal plate/column (:ref:`Flanner et al., 2021 `). The snow grain shape can be controlled via namelist option (:ref:`He et al., 2024 `). For BC internal mixing with snow grain, the original SNICAR assumes BC‐snow external mixing, with hydrophilic BC treated as coated BC. However, in reality BC can also be internally mixed with snow grains. The :ref:`He et al. (2017) ` parameterizations are used to quantify BC-snow internal mixing effects on snow single-scattering albedo (:math:`\omega`), with no changes in snow extinction optical depth (:math:`\tau`) and asymmetry factor (*g*) due to neglibile impacts. The hydrophilic BC is no longer treated as coated BC because sulfate coating on the BC particle surface is dissolvable into water during wet deposition. The hydrophilic BC is hence treated as internally mixed with snow grains. For dust-snow internal mixing, the :ref:`He et al. (2019) ` parameterizations are used to quantify its impact on snow single-scattering albedo (:math:`\omega`), with no changes in snow extinction optical depth (:math:`\tau`) and asymmetry factor (*g*). Currently, dust-snow internal mixing (if activated) applies to all dust size bins. Both BC-snow and dust-snow internal/external mixing can be controlled by namelist options (:ref:`He et al., 2024 `). By default, BC and dust are externally mixed with snow grains, and it is recommended not to activate both internal mixing together which has not been fully tested. + +The original SNICAR two-stream solution (:ref:`Toon et al., 1989 `) applies a tri-diagonal matrix solution to produce upward and downward radiative fluxes at each layer interface, from which net radiation, layer absorption, and surface albedo are easily derived. The SNICAR-ADv3 instead uses a more accurate adding-doubling radiative transfer solution (:ref:`Dang et al., 2019 `; :ref:`Briegleb and Light, 2007 `). Solar fluxes are computed in either five spectral bands (default) listed in :numref:`Table Spectral bands and weights used for snow radiative transfer` or 480 hyperspectral bands (from 200 nm to 5000 nm with 10-nm spectral resolution; :ref:`Flanner et al., 2021 `). Because snow albedo varies strongly across the solar spectrum, it was determined that at least four bands were needed to accurately represent the near-infrared (NIR) characteristics of snow, whereas only one band was needed for the visible spectrum, which is why the five bands are used by default to achieve a balance between computational time and accuracy. Boundaries of the four NIR bands were selected to capture broad radiative features and maximize accuracy and computational efficiency. The 480-band capability can be used via namelist option (:ref:`He et al., 2024 `). We partition NIR (0.7-5.0 :math:`\mu` m) surface downwelling flux from CLM according to the weights from six typical atmospheric conditions (:ref:`Flanner et al., 2021 `), including Mid‐latitude winter, Mid‐latitude summer, Sub‐Arctic winter, Sub‐Arctic summer, Summit (Greenland), and High mountain, which are unique for diffuse and direct incident flux and can be selected via namelist options (:ref:`He et al., 2024 `). By default, the mid‐latitude winter downward solar spectrum (:numref:`Table Spectral bands and weights used for snow radiative transfer`) is used. These prescribed weights were determined with offline hyperspectral atmospheric radiative transfer calculations. The radiative transfer solution includes intermediate terms that allow for easy interchange of two-stream techniques. We apply the delta-Eddington solution to the layer bulk optical properties following :ref:`Briegleb and Light (2007) `. Specifically, Delta scalings are applied to :math:`\tau`, :math:`\omega`, and :math:`g` in all spectral bands, producing effective values (denoted with :math:`*`) that are applied in the two-stream solution. .. math:: :label: 3.66 @@ -561,7 +563,7 @@ The two-stream solution (:ref:`Toon et al. (1989) `) applies a tri .. math:: :label: 3.68 - g^{*} =\frac{g}{1+g} + g^{*} =\frac{g-g^{2}}{1-g^{2}} .. _Table Spectral bands and weights used for snow radiative transfer: @@ -572,18 +574,18 @@ The two-stream solution (:ref:`Toon et al. (1989) `) applies a tri +=========================================================+======================+==================+ | Band 1: 0.3-0.7\ :math:`\mu`\ m (visible) | (1.0) | (1.0) | +---------------------------------------------------------+----------------------+------------------+ - | Band 2: 0.7-1.0\ :math:`\mu`\ m (near-IR) | 0.494 | 0.586 | + | Band 2: 0.7-1.0\ :math:`\mu`\ m (near-IR) | 0.494 | 0.634 | +---------------------------------------------------------+----------------------+------------------+ - | Band 3: 1.0-1.2\ :math:`\mu`\ m (near-IR) | 0.181 | 0.202 | + | Band 3: 1.0-1.2\ :math:`\mu`\ m (near-IR) | 0.180 | 0.186 | +---------------------------------------------------------+----------------------+------------------+ - | Band 4: 1.2-1.5\ :math:`\mu`\ m (near-IR) | 0.121 | 0.109 | + | Band 4: 1.2-1.5\ :math:`\mu`\ m (near-IR) | 0.123 | 0.094 | +---------------------------------------------------------+----------------------+------------------+ - | Band 5: 1.5-5.0\ :math:`\mu`\ m (near-IR) | 0.204 | 0.103 | + | Band 5: 1.5-5.0\ :math:`\mu`\ m (near-IR) | 0.203 | 0.086 | +---------------------------------------------------------+----------------------+------------------+ -Under direct-beam conditions, singularities in the radiative approximation are occasionally approached in spectral bands 4 and 5 that produce unrealistic conditions (negative energy absorption in a layer, negative albedo, or total absorbed flux greater than incident flux). When any of these three conditions occur, the Eddington approximation is attempted instead, and if both approximations fail, the cosine of the solar zenith angle is adjusted by 0.02 (conserving incident flux) and a warning message is produced. This situation occurs in only about 1 in 10 :sup:`6` computations of snow albedo. After looping over the five spectral bands, absorption fluxes and albedo are averaged back into the bulk NIR band used by the rest of CLM. +Under direct-beam conditions, the two-stream approximations become poor for large solar zenith angle, which is mostly contributed by the errors of near-IR band calculations, especially for optically thick snowpacks. To improve the performance of two-stream algorithms, the :ref:`Dang et al. (2019) ` parameterization that corrects the underestimated near-IR snow albedo at large solar zenith angles (>75deg) is used for NIR bands (:ref:`He et al., 2024 `). -Soil albedo (or underlying substrate albedo), which is defined for visible and NIR bands, is a required boundary condition for the snow radiative transfer calculation. Currently, the bulk NIR soil albedo is applied to all four NIR snow bands. With ground albedo as a lower boundary condition, SNICAR simulates solar absorption in all snow layers as well as the underlying soil or ground. With a thin snowpack, penetrating solar radiation to the underlying soil can be quite large and heat cannot be released from the soil to the atmosphere in this situation. Thus, if the snowpack has total snow depth less than 0.1 m (:math:`z_{sno} < 0.1`) and there are no explicit snow layers, the solar radiation is absorbed by the top soil layer. If there is a single snow layer, the solar radiation is absorbed in that layer. If there is more than a single snow layer, 75% of the solar radiation is absorbed in the top snow layer, and 25% is absorbed in the next lowest snow layer. This prevents unrealistic soil warming within a single timestep. +Soil albedo (or underlying substrate albedo), which is defined for visible and NIR bands, is a required boundary condition for the snow radiative transfer calculation. Currently, the bulk NIR soil albedo is applied to all four NIR snow bands. With ground albedo as a lower boundary condition, SNICAR-ADv3 simulates solar absorption in all snow layers as well as the underlying soil or ground. With a thin snowpack, penetrating solar radiation to the underlying soil can be quite large and heat cannot be released from the soil to the atmosphere in this situation. Thus, if the snowpack has total snow depth less than 0.1 m (:math:`z_{sno} < 0.1`) and there are no explicit snow layers, the solar radiation is absorbed by the top soil layer. If there is a single snow layer, the solar radiation is absorbed in that layer. If there is more than a single snow layer, 75% of the solar radiation is absorbed in the top snow layer, and 25% is absorbed in the next lowest snow layer. This prevents unrealistic soil warming within a single timestep. The radiative transfer calculation is performed twice for each column containing a mass of snow greater than :math:`1 \times 10^{-30}` kg\ m\ :sup:`-2` (excluding lake and urban columns); once each for direct-beam and diffuse incident flux. Absorption in each layer :math:`i` of pure snow is initially recorded as absorbed flux per unit incident flux on the ground (:math:`S_{sno,\, i}` ), as albedos must be calculated for the next timestep with unknown incident flux. The snow absorption fluxes that are used for column temperature calculations are @@ -599,7 +601,7 @@ This weighting is performed for direct-beam and diffuse, visible and NIR fluxes. Snowpack Optical Properties ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Ice optical properties for the five spectral bands are derived offline and stored in a namelist-defined lookup table for online retrieval (see CLM5.0 User's Guide). Mie properties are first computed at fine spectral resolution (470 bands), and are then weighted into the five bands applied by CLM according to incident solar flux, :math:`I^{\downarrow } (\lambda )`. For example, the broadband mass-extinction cross section (:math:`\bar{\psi }`) over wavelength interval :math:`\lambda _{1}` to :math:`\lambda _{2}` is +Ice optical properties for the five or 480 spectral bands are derived offline based on Mie calculations and stored in a namelist-defined lookup table for online retrieval (:ref:`He et al., 2024 `). The ice refractive index used in Mie calculation follows the updates in (:ref:`Flanner et al., 2021 `), which is a compilation of the :ref:`Picard et al. (2016) ` and :ref:`Warren and Brandt (2008) ` datasets. Mie properties are first computed at fine spectral resolution (480 bands from 200 nm to 5000 nm with 10-nm spectral resolution), and are then weighted into the five bands according to incident solar flux, :math:`I^{\downarrow } (\lambda )`, under six different atmospheric conditions (section :numref:`Snow Albedo`). For example, the broadband mass-extinction cross section (:math:`\bar{\psi }`) over wavelength interval :math:`\lambda _{1}` to :math:`\lambda _{2}` is .. math:: :label: 3.70 @@ -613,9 +615,9 @@ Broadband single-scatter albedo (:math:`\bar{\omega }`) is additionally weighted \bar{\omega }=\frac{\int _{\lambda _{1} }^{\lambda _{2} }\omega (\lambda )I^{\downarrow } ( \lambda )\alpha _{sno} (\lambda ){\rm d}\lambda }{\int _{\lambda _{1} }^{\lambda _{2} }I^{\downarrow } ( \lambda )\alpha _{sno} (\lambda ){\rm d}\lambda } -Inclusion of this additional albedo weight was found to improve accuracy of the five-band albedo solutions (relative to 470-band solutions) because of the strong dependence of optically-thick snowpack albedo on ice grain single-scatter albedo (:ref:`Flanner et al. (2007) `). The lookup tables contain optical properties for lognormal distributions of ice particles over the range of effective radii: 30\ :math:`\mu`\ m :math:`< r _{e} < \text{1500} \mu \text{m}`, at 1 :math:`\mu` m resolution. Single-scatter albedos for the end-members of this size range are listed in :numref:`Table Single-scatter albedo values used for snowpack impurities and ice`. +Inclusion of this additional albedo weight was found to improve accuracy of the five-band albedo solutions (relative to 480-band solutions) because of the strong dependence of optically-thick snowpack albedo on ice grain single-scatter albedo (:ref:`Flanner et al., 2007 `). The lookup tables contain optical properties for lognormal distributions of ice particles over the range of effective radii: 30\ :math:`\mu`\ m :math:`< r _{e} < \text{1500} \mu \text{m}`, at 1 :math:`\mu` m resolution. Single-scatter albedos for the end-members of this size range are listed in :numref:`Table Single-scatter albedo values used for snowpack impurities and ice`. -Optical properties for black carbon are described in :ref:`Flanner et al. (2007) `. Single-scatter albedo, mass extinction cross-section, and asymmetry parameter values for all snowpack species, in the five spectral bands used, are listed in :numref:`Table Single-scatter albedo values used for snowpack impurities and ice`, :numref:`Table Mass extinction values`, and :numref:`Table Asymmetry scattering parameters used for snowpack impurities and ice`. These properties were also derived with Mie Theory, using various published sources of indices of refraction and assumptions about particle size distribution. Weighting into the five CLM spectral bands was determined only with incident solar flux, as in equation :eq:`3.69`. +Optical properties for black carbon, organic carbon, and mineral dust are described in :ref:`Flanner et al. (2021) `. Three types of dust can be selected via namelist options (:ref:`He et al., 2024 `), including Saharan dust (default), Colorado dust, and Greenland dust, due to their substantially different optical properties. Single-scatter albedo, mass extinction cross-section, and asymmetry parameter values for all snowpack species under diffuse radiation with the default atmospheric condition (mid-latitude winter), in the five spectral bands used, are listed in :numref:`Table Single-scatter albedo values used for snowpack impurities and ice`, :numref:`Table Mass extinction values`, and :numref:`Table Asymmetry scattering parameters used for snowpack impurities and ice`. These properties were also derived with Mie Theory, using various published sources of indices of refraction and assumptions about particle size distribution (:ref:`Flanner et al., 2021 `). Weighting into the five CLM spectral bands was determined using the 480-band values with incident solar flux under six different atmospheric conditions (section :numref:`Snow Albedo`), as in equation :eq:`3.70`. .. _Table Single-scatter albedo values used for snowpack impurities and ice: @@ -624,25 +626,25 @@ Optical properties for black carbon are described in :ref:`Flanner et al. (2007) +----------------------------------------------------------------+----------+----------+----------+----------+----------+ | Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | +================================================================+==========+==========+==========+==========+==========+ - | Hydrophilic black carbon | 0.516 | 0.434 | 0.346 | 0.276 | 0.139 | + | Hydrophilic black carbon | 0.366 | 0.302 | 0.252 | 0.217 | 0.152 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Hydrophobic black carbon | 0.288 | 0.187 | 0.123 | 0.089 | 0.040 | + | Hydrophobic black carbon | 0.366 | 0.302 | 0.252 | 0.217 | 0.152 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Hydrophilic organic carbon | 0.997 | 0.994 | 0.990 | 0.987 | 0.951 | + | Hydrophilic organic carbon | 0.772 | 0.990 | 0.987 | 0.983 | 0.971 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Hydrophobic organic carbon | 0.963 | 0.921 | 0.860 | 0.814 | 0.744 | + | Hydrophobic organic carbon | 0.772 | 0.990 | 0.987 | 0.983 | 0.971 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Dust 1 | 0.979 | 0.994 | 0.993 | 0.993 | 0.953 | + | Dust 1 | 0.945 | 0.991 | 0.992 | 0.992 | 0.983 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Dust 2 | 0.944 | 0.984 | 0.989 | 0.992 | 0.983 | + | Dust 2 | 0.870 | 0.976 | 0.989 | 0.992 | 0.991 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Dust 3 | 0.904 | 0.965 | 0.969 | 0.973 | 0.978 | + | Dust 3 | 0.802 | 0.948 | 0.965 | 0.974 | 0.984 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Dust 4 | 0.850 | 0.940 | 0.948 | 0.953 | 0.955 | + | Dust 4 | 0.730 | 0.913 | 0.943 | 0.954 | 0.965 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Ice (:math:`r _{e}` = 30 :math:`\mu` m) | 0.9999 | 0.9999 | 0.9992 | 0.9938 | 0.9413 | + | Ice (:math:`r _{e}` = 30 :math:`\mu` m) | 0.9999 | 0.9999 | 0.9993 | 0.9954 | 0.9510 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Ice (:math:`r _{e}` = 1500 :math:`\mu` m) | 0.9998 | 0.9960 | 0.9680 | 0.8730 | 0.5500 | + | Ice (:math:`r _{e}` = 1500 :math:`\mu` m) | 0.9998 | 0.9963 | 0.9678 | 0.8735 | 0.5492 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ .. _Table Mass extinction values: @@ -652,25 +654,25 @@ Optical properties for black carbon are described in :ref:`Flanner et al. (2007) +----------------------------------------------------------------+----------+----------+----------+----------+----------+ | Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | +================================================================+==========+==========+==========+==========+==========+ - | Hydrophilic black carbon | 25369 | 12520 | 7739 | 5744 | 3527 | + | Hydrophilic black carbon | 12389 | 7971 | 5744 | 4654 | 3155 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Hydrophobic black carbon | 11398 | 5923 | 4040 | 3262 | 2224 | + | Hydrophobic black carbon | 12389 | 7971 | 5744 | 4654 | 3155 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Hydrophilic organic carbon | 37774 | 22112 | 14719 | 10940 | 5441 | + | Hydrophilic organic carbon | 4933 | 1390 | 628 | 375 | 143 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Hydrophobic organic carbon | 3289 | 1486 | 872 | 606 | 248 | + | Hydrophobic organic carbon | 4933 | 1390 | 628 | 375 | 143 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Dust 1 | 2687 | 2420 | 1628 | 1138 | 466 | + | Dust 1 | 2543 | 2242 | 1469 | 1013 | 458 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Dust 2 | 841 | 987 | 1184 | 1267 | 993 | + | Dust 2 | 803 | 950 | 1144 | 1205 | 1000 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Dust 3 | 388 | 419 | 400 | 397 | 503 | + | Dust 3 | 369 | 399 | 378 | 380 | 488 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Dust 4 | 197 | 203 | 208 | 205 | 229 | + | Dust 4 | 188 | 193 | 197 | 197 | 212 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Ice (:math:`r _{e}` = 30 :math:`\mu` m) | 55.7 | 56.1 | 56.3 | 56.6 | 57.3 | + | Ice (:math:`r _{e}` = 30 :math:`\mu` m) | 55.7 | 56.1 | 56.4 | 56.7 | 57.2 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Ice (:math:`r _{e}` = 1500 :math:`\mu` m) | 1.09 | 1.09 | 1.09 | 1.09 | 1.1 | + | Ice (:math:`r _{e}` = 1500 :math:`\mu` m) | 1.09 | 1.09 | 1.09 | 1.09 | 1.09 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ .. _Table Asymmetry scattering parameters used for snowpack impurities and ice: @@ -680,23 +682,23 @@ Optical properties for black carbon are described in :ref:`Flanner et al. (2007) +----------------------------------------------------------------+----------+----------+----------+----------+----------+ | Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | +================================================================+==========+==========+==========+==========+==========+ - | Hydrophilic black carbon | 0.52 | 0.34 | 0.24 | 0.19 | 0.10 | + | Hydrophilic black carbon | 0.44 | 0.34 | 0.28 | 0.24 | 0.18 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Hydrophobic black carbon | 0.35 | 0.21 | 0.15 | 0.11 | 0.06 | + | Hydrophobic black carbon | 0.44 | 0.34 | 0.28 | 0.24 | 0.18 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Hydrophilic organic carbon | 0.77 | 0.75 | 0.72 | 0.70 | 0.64 | + | Hydrophilic organic carbon | 0.58 | 0.47 | 0.39 | 0.34 | 0.25 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Hydrophobic organic carbon | 0.62 | 0.57 | 0.54 | 0.51 | 0.44 | + | Hydrophobic organic carbon | 0.58 | 0.47 | 0.39 | 0.34 | 0.25 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Dust 1 | 0.69 | 0.72 | 0.67 | 0.61 | 0.44 | + | Dust 1 | 0.71 | 0.72 | 0.67 | 0.62 | 0.48 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Dust 2 | 0.70 | 0.65 | 0.70 | 0.72 | 0.70 | + | Dust 2 | 0.73 | 0.66 | 0.71 | 0.74 | 0.73 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Dust 3 | 0.79 | 0.75 | 0.68 | 0.63 | 0.67 | + | Dust 3 | 0.82 | 0.76 | 0.68 | 0.63 | 0.67 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Dust 4 | 0.83 | 0.79 | 0.77 | 0.76 | 0.73 | + | Dust 4 | 0.87 | 0.80 | 0.78 | 0.76 | 0.73 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ - | Ice (:math:`r _{e}` = 30\ :math:`\mu`\ m) | 0.88 | 0.88 | 0.88 | 0.88 | 0.90 | + | Ice (:math:`r _{e}` = 30\ :math:`\mu`\ m) | 0.88 | 0.88 | 0.88 | 0.88 | 0.89 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ | Ice (:math:`r _{e}` = 1500\ :math:`\mu`\ m) | 0.89 | 0.90 | 0.90 | 0.92 | 0.97 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index 695281556f..e352d1a9e6 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -21,7 +21,7 @@ The main changes in the urban model from CLM5.0 to CLM6.0 are (see below) 1) an The building energy model introduced in :ref:`Oleson and Feddema (2020) ` accounts for the conduction of heat through interior surfaces (roof, sunlit and shaded walls, and floors), convection (sensible heat exchange) between interior surfaces and building air, longwave radiation exchange between interior surfaces, and ventilation (natural infiltration and exfiltration). Idealized HAC systems are assumed where the system capacity is infinite and the system supplies the amount of energy needed to keep the indoor air temperature (:math:`T_{iB}`) within maximum and minimum emperatures (:math:`T_{iB,\, \max },\, T_{iB,\, \min }` ), thus explicitly resolving space heating and AC fluxes. Anthropogenic sources of waste heat (:math:`Q_{H,\, waste}` ) from HAC that account for inefficiencies in the heating and AC equipment and from energy lost in the conversion of primary energy sources to end use energy are derived from :ref:`Sivak (2013) `. These sources of waste heat are incorporated as modifications to the canyon energy budget. -An explicit AC adoption parameterization for the BEM was developed for CLM6.0 (:ref:`Li et al. (2024) `). An AC adoption parameter is introduced (:math:`p_{AC}` ). The AC flux is first calculated under saturated AC adoption (i.e., :math:`p_{AC}=100%` ). The actual AC flux removed from the indoor air is then scaled based on :math:`p_{AC}` and the waste heat added to the urban canyon due to AC energy use is also scaled by :math:`p_{AC}`. A global, spatially explicit dataset for the AC adoption rate was developed at country- and sub-country-level from sources such as the International Energy Agency (IEA), national surveys, scientific literature, and others. For use with CLM, the AC adoption parameter was regridded to 0.9° latitude by 1.25° longitude and is read in for each of the three urban density classes using the file specified by the ``urbantv_streams`` namelist group (variables ``p_ac_MD``, ``p_ac_HD``, ``p_ac_TBD``). The maximum building interior temperature is also specified by the file in the ``urbantv_streams`` namelist group and is now considered to be the AC proxy setpoint in the parameterization and is set to 300K for all urban density classes (variables ``tbuildmax_MD``', ``tbuildmax_HD``, ``tbuildmax_TBD``). The explicit AC adoption parameterization in combination with the AC adoption rate dataset significantly improve CLM's performance in model building AC energy flux, both in magnitude and spatial variability (:ref:`Li et al. (2024) `). +An explicit AC adoption parameterization for the BEM was developed for CLM6.0 (:ref:`Li et al. (2024) `). An AC adoption parameter is introduced (:math:`p_{AC}` ). The AC flux is first calculated under saturated AC adoption (i.e., :math:`p_{AC}=100%` ). The actual AC flux removed from the indoor air is then scaled based on :math:`p_{AC}` and the waste heat added to the urban canyon due to AC energy use is also scaled by :math:`p_{AC}`. A global, spatially explicit dataset for the AC adoption rate was developed at country- and sub-country-level from sources such as the International Energy Agency (IEA), national surveys, scientific literature, and others. For use with CLM, the AC adoption parameter was regridded to 0.9° latitude by 1.25° longitude and is read in for each of the three urban density classes using the file specified by the ``urbantv_streams`` namelist group (variables ``p_ac_MD``, ``p_ac_HD``, ``p_ac_TBD``). The maximum building interior temperature is also specified by the file in the ``urbantv_streams`` namelist group and is now considered to be the AC proxy setpoint in the parameterization and is set to 300K for all urban density classes (variables ``tbuildmax_MD``', ``tbuildmax_HD``, ``tbuildmax_TBD``). The explicit AC adoption parameterization in combination with the AC adoption rate dataset significantly improve CLM's performance in model building AC energy flux, both in magnitude and spatial variability (:ref:`Li et al. (2024) `). Global urban properties were originally developed by :ref:`Jackson et al. (2010) `. For each of 33 distinct regions across the globe and four urban density classes [tall building district (TBD), and high, medium, and low density (HD, MD, LD)], thermal (e.g., heat capacity and thermal conductivity), radiative (e.g., albedo and emissivity) and morphological (e.g., height to width ratio, roof fraction, average building height, and pervious fraction of the canyon floor) properties, are provided for each of the density classes. Building interior minimum and maximum temperatures are prescribed based on climate and socioeconomic considerations. As described in :ref:`Oleson and Feddema (2020) ` the urban properties dataset in :ref:`Jackson et al. (2010) ` was modified with respect to wall and roof thermal properties to correct for biases in heat transfer due to layer and building type averaging. Further changes to the dataset reflect the need for scenario development, thus allowing for the creation of hypothetical wall types, and the easier interchange of wall facets. This slightly modified dataset was an option in CLM5.0. diff --git a/doc/source/users_guide/adding-new-resolutions/Adding-or-Changing-Default-Filenames.rst b/doc/source/users_guide/adding-new-resolutions/Adding-or-Changing-Default-Filenames.rst index a39ffa9426..47cbad9dc6 100644 --- a/doc/source/users_guide/adding-new-resolutions/Adding-or-Changing-Default-Filenames.rst +++ b/doc/source/users_guide/adding-new-resolutions/Adding-or-Changing-Default-Filenames.rst @@ -17,17 +17,3 @@ To add or change the default filenames you edit the ``$CTSMROOT/bld/namelist_fil Other ``fsurdat`` files are distinguished from this one by their resolution (``hgrid``), simulation year (``sim_year``) and prognostic crop (``use_crop``) attributes. ----------------------------- -What are the required files? ----------------------------- - -Different types of simulations and different types of configurations for CLM require different lists of files. The |version|-BGC or Carbon Nitrogen (cn) Biogeochemistry model for example requires ``stream_fldfilename_ndep`` files, which are NOT required by CLMSP. Transient simulations also require transient datasets, and the names of these datasets are sometimes different from the static versions (sometimes both are required as in the dynamic PFT cases). - -In the following table we list the different files used by CLM, they are listed in order of importance, dependencies, and customizing. So the required files are all near the top, and the files used only under different conditions are listed later, and files with the fewest dependencies are near the top, as are the files that are least likely to be customized. - -.. _reqd-files-table: - -Table 3-1. Required Files for Different Configurations and Simulation Types ---------------------------------------------------------------------------- -.. todo:: - Insert table 3-1 diff --git a/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst index 8376c280b1..4372c946f0 100644 --- a/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst +++ b/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst @@ -3,101 +3,124 @@ .. _spinning-up-clm-bgc: ============================= - Spinup of |version|-BGC-Crop + Spinup of CLM-BGC-Crop ============================= -To get the |version|-BGC model to a steady state, you first run it from arbitrary initial conditions using the "accelerated decomposition spinup" (``-bgc_spinup on`` in CLM ``configure``, see example below) mode for about 200 simulation years. :numref:`Figure BGC AD spinup plot for 1850 GSWP3` shows spinup behavior for an 1850 BGC accelerated decomposition (AD) case using GSWP3 atmospheric forcing. Generally, the criteria that less than 3% of the land surface be in total ecosystem carbon disequilibrium takes the longest to satisfy due to slow soil carbon (TOTSOMC) turnover times in the Arctic. +To get the CLM-BGC-Crop model to a steady state, you start it from arbitrary initial conditions using the "accelerated decomposition spinup" (``CLM_ACCELERATED_SPINUP on`` in CLM `env_run.xml`, see example below) mode for 300-400 simulation years. :numref:`Figure BGC-Crop AD spinup plot for 1850` shows spinup behavior for an 1850 BGC-Crop accelerated decomposition (AD) case using CRUJRA atmospheric forcing. Generally, the criterion that less than 3% of the land surface be in total ecosystem carbon disequilibrium takes the longest to satisfy due to slow soil carbon (TOTSOMC) turnover times in the Arctic. -.. _Figure BGC AD spinup plot for 1850 GSWP3: +.. _Figure BGC-Crop AD spinup plot for 1850: -.. figure:: image3.png +.. figure:: ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_AD_Spinup-0.png - BGC AD spinup plot for a year 1850 case with GSWP3 atmospheric forcing. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. + BGC-Crop AD spinup plot for a year 1850 case with CRUJRA atmospheric forcing. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability_BGC_v11.ncl. -After this you branch from this mode in the "final spinup" (``-bgc_spinup off`` in CLM ``configure``, see example below), and run for several hundred simulation years. :numref:`Figure BGC pAD spinup plot for 1850 GSWP3` shows spinup behavior for an 1850 BGC post accelerated decomposition (pAD) case using GSWP3 atmospheric forcing. As before, the criteria that less than 3% of the land surface be in total ecosystem carbon disequilibrium takes the longest to satisfy. It can be difficult to meet this strict criteria in less than 1000 years and users may want to relax this criteria depending on their application. +After this you continue in "SASU" mode (``CLM_ACCELERATED_SPINUP sasu`` in CLM `env_run.xml`, see example below), and run for 300-350 simulation years. :numref:`Figure BGC-Crop SASU spinup plot for 1850` shows spinup behavior for an 1850 BGC-Crop SASU case using CRUJRA atmospheric forcing. The criterion that less than 3% of the land surface be in total ecosystem carbon disequilibrium takes the longest to satisfy and need not be met for this step. -.. _Figure BGC pAD spinup plot for 1850 GSWP3: +.. _Figure BGC-Crop SASU spinup plot for 1850: -.. figure:: image4.png +.. figure:: ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_SASU_Spinup-0.png - BGC pAD spinup plot for a year 1850 case with GSWP3 atmospheric forcing and initialization from the end of the BGC AD spinup case. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. + BGC-Crop SASU spinup plot for a year 1850 case with CRUJRA atmospheric forcing and initialization from the end of the BGC-Crop AD spinup case. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability_BGC_v11.ncl. -You can also start from a default initial file that is setup as part of the selected compset. :numref:`Figure BGC initialized spinup plot for 1850` shows spinup behavior for an 1850 pAD BGC case that loops over one year of coupler history output for atmospheric forcing (generated from the fully coupled model), initialized with a BGC initial file generated from a GSWP3 atmospheric forcing case. Note that it takes about 10 years for variables such as TLAI (total leaf area index), GPP (gross primary production), and TWS (total water storage) to reach a specified equilibrium state (denoted by the dotted lines) due to the different atmospheric forcing. +After this you continue in standard mode for 200 years. We refer to this phase as post-SASU, pSASU, or normal mode (``CLM_ACCELERATED_SPINUP off`` in CLM `env_run.xml`, see example below). :numref:`Figure BGC-Crop normal mode plot for 1850` shows spinup behavior for an 1850 BGC-Crop normal mode case using CRUJRA atmospheric forcing. As before, the criterion that less than 3% of the land surface be in total ecosystem carbon disequilibrium takes the longest to satisfy. -.. _Figure BGC initialized spinup plot for 1850: +.. _Figure BGC-Crop normal mode plot for 1850: -.. figure:: image5.png +.. figure:: ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_pSASU_Spinup-0.png - BGC initialized spinup plot for year 1850. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. + BGC-Crop normal mode plot for a year 1850 case with CRUJRA atmospheric forcing and initialization from the end of the BGC-Crop SASU spinup case. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability_BGC_v11.ncl. -:numref:`Figure BGC initialized spinup plot for 2000 CO2` shows spinup behavior for the same case but also changes CO2 to present-day conditions (379ppmv). Again, it takes about 10 years to reach equilibrium for TLAI, GPP, and TWS. +As an alternative to spinning up, one may start from a default initial file that is setup as part of the selected compset. When the simulation's spatial resolution is identical to the initial file's resolution, it may still take 10 or more years for variables such as TLAI (total leaf area index), GPP (gross primary production), and TWS (total water storage) to reach a new equilibrium state due to the different atmospheric forcing. Similarly, it may take 10 or more years for these variables to reach a new equilibrium when switching atmospheric CO2 from 1850 to a present-day value. -.. _Figure BGC initialized spinup plot for 2000 CO2: - -.. figure:: image6.png - - BGC initialized spinup plot for year 2000 CO2. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. - -If you use the default initial file and you signficantly change model behavior or atmospheric forcing, and you are concerned about the carbon equilibrium (e.g., TOTECOSYSC, TOTSOMC, TOTVEGC), particularly at high latitudes, then we recommend you put the model back into AD mode to reach a new equilibrium. In this configuration, this will also automatically reseed "dead" plant functional types in the initial file with a bit of leaf carbon to give those plant functional types another chance to grow under the new atmospheric forcing or model conditions. - -**1. |version| accelerated-decomposition (AD) spinup** - For the first step of running 200+ years in ``-bgc_spinup on`` mode, you will setup a case, and then edit the values in env_build.xml and env_run.xml so that the right configuration is turned on and the simulation is setup to run for the required length of simulation time. So do the following: - -Example: AD_SPINUP Simulation for |version|-BGC +Example: AD_spinup Simulation for CLM-BGC-Crop -------------------------------------------------------- +For the first step of running in ``CLM_ACCELERATED_SPINUP on`` mode, you will setup a case, and then edit the values in env_build.xml and env_run.xml so that the right configuration is turned on and the simulation is setup to run for the required length of simulation time. Try the following: + :: > cd cime/scripts - > ./create_newcase -case BGC_spinup -res f19_g17_gl4 -compset I1850Clm50BgcCropCru - > cd BGC_spinup + > ./create_newcase -case AD_spinup -res f19_g17 -compset I1850Clm60BgcCrop --run-unsupported + > cd AD_spinup # Change accelerated spinup mode > ./xmlchange CLM_ACCELERATED_SPINUP="on" # Now setup - > ./case.setup -case + > ./case.setup + # The following makes sure we run with MOSART off + > ./xmlchange MOSART_MODE=NULL # Now build > ./case.build - # The following sets RESUBMIT to 3 times in env_run.xml (you could also use an editor) - # The following sets STOP_DATE,STOP_N and STOP_OPTION to Jan/1/0201, 20, "nyears" in env_run.xml (you could also use an editor) - > ./xmlchange RESUBMIT=3,STOP_N=50,STOP_OPTION=nyears,STOP_DATE=02010101 - # Now run normally + # The following sets RESUBMIT to 7 times, STOP_N to 50, and STOP_OPTION to "nyears" in env_run.xml (you could also modify these with an editor) + > ./xmlchange RESUBMIT=7,STOP_N=50,STOP_OPTION=nyears + # Now run > ./case.submit -.. note:: This same procedure works for |version|-CN as well. +While this simulation progresses, use SpinupStability_BGC_v11.ncl to assess whether the simulation is approaching equilibrium. When the simulation ends, save the last restart file for use in the SASU_spinup step. + +Using the SpinupStability.ncl scripts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In CLM's /tools/contrib directory there are three versions of this .ncl script: + +- SpinupStability_BGC_v11.ncl for Bgc and BgcCrop compsets run on 2D lat/lon grids. +- SpinupStability_BGC_v12_SE.ncl for Bgc, BgcCrop, or Fates compsets run on certain spectral element grids (currently ne120, ne30, ne16). +- SpinupStability_SP_v10.ncl for Sp compsets run on 2D lat/lon grids. See section :numref:`spinning-up-sp` for helpful pointers about this script that may also apply to the BGC-Crop versions. -Afterwards save the last restart file from this simulation to use in the next step. +To run one of these scripts on derecho, one loads ncl (``module load ncl``) and submits with ``ncl SpinupStability_BGC_v11.ncl``, for example. Before running one needs to confirm a few easy settings appearing near the top of each script. -**2. Final spinup for |version|-BGC** - Next save the last restart file from this step and use it as the ``finidat`` file to use for one more spinup for at least 400+ years in normal mode. So do the following: +One of the settings that may not be intuitive at first glance is ``annual_hist``. By default the phases AD_spinup and SASU_spinup generate annual history, so set this to "True", while normal mode generates monthly history, so set this to "False". -.. _eg-final-clmbgc-spinup: +.. _eg-sasu-spinup: -Example: Final CLMBGC Spinup Simulation for |version|-BGC +Example: SASU_spinup Simulation for CLM-BGC-Crop ------------------------------------------------------------------ :: > cd cime/scripts - > ./create_newcase -case BGC_finalspinup -res f19_g17_gl4 -compset I1850Clm50BgcCropCru - > cd BGC_finalspinup - # Now, Copy the last CLM restart file from the earlier case into your run directory - > cp /ptmp/$LOGIN/archive/BGC_spinup/rest/BGC_spinup.clm*.r*.0201-01-01-00000.nc \ - /glade/scratch/$LOGIN/CN_finalspinup/run - # Set the runtype to startup - > ./xmlchange RUN_TYPE=startup - # And copy the rpointer files for datm and drv from the earlier case - > cp /glade/scratch/$LOGIN/archive/BGC_spinup/rest/rpointer.atm /glade/scratch/$LOGIN/CN_finalspinup/run - # Set the finidat file to the last restart file saved in previous step - > echo ' finidat = "BGC_spinup.clm2.r.0201-01-01-00000.nc"' > user_nl_clm + > ./create_newcase -case SASU_spinup -res f19_g17 -compset I1850Clm60BgcCrop --run-unsupported + > cd SASU_spinup + # Change accelerated spinup mode, turn off coldstart, and change runtype to hybrid to allow use of a finidat + > ./xmlchange CLM_ACCELERATED_SPINUP="sasu",CLM_FORCE_COLDSTART=off,RUN_TYPE=hybrid # Now setup > ./case.setup - > Now build + # Copy the last restart files from the AD_spinup case into your run directory + # On NSF-NCAR's derecho computer, cd to /glade/derecho/scratch/$USER + > cp archive/AD_spinup/rest/0401-01-01-00000/* SASU_spinup/run + # Set finidat to the restart file copied in the previous step + > echo ' finidat = "AD_spinup.clm2.r.0401-01-01-00000.nc"' > user_nl_clm + # The following makes sure we run with MOSART off + > ./xmlchange MOSART_MODE=NULL + # Now build > ./case.build - # The following sets RESUBMIT to 7 times in env_run.xml (you could also use an editor) - # The following sets STOP_N and STOP_OPTION to 50 and "nyears" in env_run.xml (you could also use an editor) - > ./xmlchange RESUBMIT=7,STOP_OPTION=nyears,STOP_N=50 - > Now run as normal + # The following sets RESUBMIT to 6 times, STOP_N to 50, and STOP_OPTION to "nyears" in env_run.xml (you could also modify these with an editor) + > ./xmlchange RESUBMIT=6,STOP_OPTION=nyears,STOP_N=50 + # Now run > ./case.submit -To assess if the model is spunup, plot trends for CLMBGC variables of interest using .../tools/contrib/SpinupStability.ncl. If you don't meet the equilibrium criteria, you may need to run the simulation longer. Finally save the restart file from the end of this simulation to use as an "finidat" file for future simulations. +Save the last restart file from this step and use it as the ``finidat`` file for the normal mode simulation. Save the restart file from the end of the normal mode simulation to use as a "finidat" file for future simulations. + -.. note:: This same final spinup procedure works for |version|-CN as well. +Example: Normal mode simulation for CLM-BGC-Crop +-------------------------------------------------- +:: + + > cd cime/scripts + > ./create_newcase -case pSASU_spinup -res f19_g17 -compset I1850Clm60BgcCrop --run-unsupported + > cd pSASU_spinup + # Change accelerated spinup mode, turn off coldstart, and change runtype to hybrid to allow use of a finidat + > ./xmlchange CLM_ACCELERATED_SPINUP="off",CLM_FORCE_COLDSTART=off,RUN_TYPE=hybrid + # Now setup + > ./case.setup + # Copy the last restart files from the SASU_spinup case into your run directory + # On NSF-NCAR's derecho computer, cd to /glade/derecho/scratch/$USER + > cp archive/SASU_spinup/rest/0351-01-01-00000/* pSASU_spinup/run + # Set finidat to the restart file copied in the previous step + > echo ' finidat = "SASU_spinup.clm2.r.0351-01-01-00000.nc"' > user_nl_clm + # The following makes sure we run with MOSART off + > ./xmlchange MOSART_MODE=NULL + # Now build + > ./case.build + # The following sets RESUBMIT to 3 times, STOP_N to 50, and STOP_OPTION to "nyears" in env_run.xml (you could also modify these with an editor) + > ./xmlchange RESUBMIT=3,STOP_OPTION=nyears,STOP_N=50 + # Now run + > ./case.submit diff --git a/doc/source/users_guide/running-special-cases/ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_AD_Spinup-0.png b/doc/source/users_guide/running-special-cases/ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_AD_Spinup-0.png new file mode 100644 index 0000000000..0db353da62 --- /dev/null +++ b/doc/source/users_guide/running-special-cases/ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_AD_Spinup-0.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5019303d5d02530c1ad6a58512ee956072e8c793774bceecbc84041c7d7fa95d +size 67505 diff --git a/doc/source/users_guide/running-special-cases/ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_SASU_Spinup-0.png b/doc/source/users_guide/running-special-cases/ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_SASU_Spinup-0.png new file mode 100644 index 0000000000..d7e5787054 --- /dev/null +++ b/doc/source/users_guide/running-special-cases/ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_SASU_Spinup-0.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5b12cbf832a022eb6390eb3c75b0fe97dd47b2704206d282e2c2c65b30420855 +size 72370 diff --git a/doc/source/users_guide/running-special-cases/ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_pSASU_Spinup-0.png b/doc/source/users_guide/running-special-cases/ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_pSASU_Spinup-0.png new file mode 100644 index 0000000000..f41afe0036 --- /dev/null +++ b/doc/source/users_guide/running-special-cases/ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_pSASU_Spinup-0.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5b1eae04e80108750a2f7770ba151f419196dd5ddb51dd9a11d9c3e5c8170c56 +size 62444 diff --git a/doc/source/users_guide/running-special-cases/image3.png b/doc/source/users_guide/running-special-cases/image3.png deleted file mode 100644 index 0c11688829..0000000000 --- a/doc/source/users_guide/running-special-cases/image3.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:347a4e32e072c6b5d9f87ae7fd36ee3621c8436910691b18f63d9365f853d8de -size 280086 diff --git a/doc/source/users_guide/running-special-cases/image4.png b/doc/source/users_guide/running-special-cases/image4.png deleted file mode 100644 index 09456b93af..0000000000 --- a/doc/source/users_guide/running-special-cases/image4.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:4587fe62aa8c34906e56d13c99749b69d2600f4c770c50781d81faf2480b8842 -size 287344 diff --git a/doc/source/users_guide/running-special-cases/image5.png b/doc/source/users_guide/running-special-cases/image5.png deleted file mode 100644 index f0d073565f..0000000000 --- a/doc/source/users_guide/running-special-cases/image5.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:991c6fa7d321f0a0e50f38c82f951eb978ba3ae62efe184bc941fcacaf4352c5 -size 316593 diff --git a/doc/source/users_guide/running-special-cases/image6.png b/doc/source/users_guide/running-special-cases/image6.png deleted file mode 100644 index 949acde48d..0000000000 --- a/doc/source/users_guide/running-special-cases/image6.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:65a5121d47597ae3d508a8bda8989708c928e3f0b9e183009dfc4bcd661ad4b6 -size 311278 diff --git a/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst b/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst index 71f4783b92..54c48e5e03 100644 --- a/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst +++ b/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst @@ -6,9 +6,8 @@ Observational Sites Datasets ******************************* -.. todo:: - Update this. +A way to customize the model input datasets is to customize the inputs to the tools that create the datasets. One can also overwrite the data of already generated datasets. Depending on the tool, the dataset, and the planned simulation, one way or the other may be simpler, or a combination of both methods may make sense. -There are two ways to customize datasets for a particular observational site. The first is to customize the input to the tools that create the dataset, and the second is to overwrite the default data after you've created a given dataset. Depending on the tool it might be easier to do it one way or the other. In Table :numref:`reqd-files-table` we list the files that are most likely to be customized and the way they might be customized. Of those files, the ones you are most likely to customize are: ``fatmlndfrc``, ``fsurdat``, ``faerdep`` (for DATM), and ``stream_fldfilename_ndep``. Note ``mksurfdata_esmf`` as documented previously has options to overwrite the vegetation and soil types. For more information on this also see :ref:`generic_single_point_runs`. +Files that you may customize include ``fatmlndfrc``, ``fsurdat``, ``faerdep`` (for DATM), and ``stream_fldfilename_ndep``. To customize ``fsurdat`` files, one may modify the inputs needed by the ``mksurfdata_esmf`` tool. In addition (or instead) we strongly recommend using the ``subset_data`` tool for single-point and regional simulations (see :ref:`generic_single_point_runs`). A combination of methods may make the most sense in some cases. -Another aspect of customizing your input datasets is customizing the input atmospheric forcing datasets; see :ref:`generic_single_point_runs` for more information on this. +Another aspect of customizing your input datasets is customizing the input atmospheric forcing datasets; see :ref:`generic_single_point_runs` for information on this. diff --git a/share b/share index 9aa0b449c4..f210ab4b32 160000 --- a/share +++ b/share @@ -1 +1 @@ -Subproject commit 9aa0b449c47f0f22badf27eff2e6fd37ecdd2def +Subproject commit f210ab4b326ce9da5f8b062953eef0bb023ec188 diff --git a/src/biogeochem/ch4Mod.F90 b/src/biogeochem/ch4Mod.F90 index 95c3762d8d..79d8e3fa97 100644 --- a/src/biogeochem/ch4Mod.F90 +++ b/src/biogeochem/ch4Mod.F90 @@ -365,7 +365,7 @@ subroutine InitHistory(this, bounds) ! ! !LOCAL VARIABLES: character(8) :: vr_suffix - character(10) :: active + character(10) :: active_via_hist_wrtch4diag integer :: begc,endc integer :: begg,endg real(r8), pointer :: data2dptr(:,:) ! temp. pointers for slicing larger arrays @@ -381,9 +381,9 @@ subroutine InitHistory(this, bounds) endif if (hist_wrtch4diag) then - active = "active" + active_via_hist_wrtch4diag = "active" else - active = "inactive" + active_via_hist_wrtch4diag = "inactive" end if this%finundated_col(begc:endc) = spval @@ -466,196 +466,156 @@ subroutine InitHistory(this, bounds) avgflag='A', long_name='CH4 soil Concentration for non-inundated area', & ptr_col=this%conc_ch4_unsat_col, l2g_scale_type='veg', default='inactive') - if (hist_wrtch4diag) then - this%ch4_prod_depth_sat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='CH4_PROD_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & - avgflag='A', long_name='CH4 soil production for inundated / lake area', & - ptr_col=this%ch4_prod_depth_sat_col) - end if - - if (hist_wrtch4diag) then - this%ch4_prod_depth_unsat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='CH4_PROD_DEPTH_UNSAT', units='mol/m3/s', type2d='levgrnd', & - avgflag='A', long_name='CH4 soil production for non-inundated area', & - ptr_col=this%ch4_prod_depth_unsat_col) - end if - - if (hist_wrtch4diag) then - this%ch4_oxid_depth_sat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='CH4_OXID_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & - avgflag='A', long_name='CH4 soil oxidation for inundated / lake area', & - ptr_col=this%ch4_oxid_depth_sat_col) - end if - - if (hist_wrtch4diag) then - this%ch4_oxid_depth_unsat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='CH4_OXID_DEPTH_UNSAT', units='mol/m3/s', type2d='levgrnd', & - avgflag='A', long_name='CH4 soil oxidation for non-inundated area', & - ptr_col=this%ch4_oxid_depth_unsat_col) - end if - - if (hist_wrtch4diag) then - this%ch4_aere_depth_sat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='CH4_AERE_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & - avgflag='A', long_name='CH4 soil aerenchyma loss for inundated / lake area '// & - ' (including transpiration flux if activated)', & - ptr_col=this%ch4_aere_depth_sat_col) - end if - - if (hist_wrtch4diag) then - this%ch4_aere_depth_unsat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='CH4_AERE_DEPTH_UNSAT', units='mol/m3/s', type2d='levgrnd', & - avgflag='A', long_name='CH4 soil aerenchyma loss for non-inundated area '// & - ' (including transpiration flux if activated)', & - ptr_col=this%ch4_aere_depth_unsat_col) - end if - - if (hist_wrtch4diag) then - this%o2_aere_depth_sat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='O2_AERE_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & - avgflag='A', long_name='O2 aerenchyma diffusion into soil for inundated / lake area', & - ptr_col=this%o2_aere_depth_sat_col) - end if - - if (hist_wrtch4diag) then - this%o2_aere_depth_unsat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='O2_AERE_DEPTH_UNSAT', units='mol/m3/s', type2d='levgrnd', & - avgflag='A', long_name='O2 aerenchyma diffusion into soil for non-inundated area', & - ptr_col=this%o2_aere_depth_unsat_col) - end if - - if (hist_wrtch4diag) then - call hist_addfld2d (fname='O2_DECOMP_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & - avgflag='A', long_name='O2 consumption from HR and AR for inundated / lake area', & - ptr_col=this%o2_decomp_depth_sat_col) - end if + this%ch4_prod_depth_sat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='CH4_PROD_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & + avgflag='A', long_name='CH4 soil production for inundated / lake area', & + ptr_col=this%ch4_prod_depth_sat_col, default=active_via_hist_wrtch4diag) + + this%ch4_prod_depth_unsat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='CH4_PROD_DEPTH_UNSAT', units='mol/m3/s', type2d='levgrnd', & + avgflag='A', long_name='CH4 soil production for non-inundated area', & + ptr_col=this%ch4_prod_depth_unsat_col, default=active_via_hist_wrtch4diag) + + this%ch4_oxid_depth_sat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='CH4_OXID_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & + avgflag='A', long_name='CH4 soil oxidation for inundated / lake area', & + ptr_col=this%ch4_oxid_depth_sat_col, default=active_via_hist_wrtch4diag) + + this%ch4_oxid_depth_unsat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='CH4_OXID_DEPTH_UNSAT', units='mol/m3/s', type2d='levgrnd', & + avgflag='A', long_name='CH4 soil oxidation for non-inundated area', & + ptr_col=this%ch4_oxid_depth_unsat_col, default=active_via_hist_wrtch4diag) + + this%ch4_aere_depth_sat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='CH4_AERE_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & + avgflag='A', long_name='CH4 soil aerenchyma loss for inundated / lake area '// & + ' (including transpiration flux if activated)', & + ptr_col=this%ch4_aere_depth_sat_col, default=active_via_hist_wrtch4diag) + + this%ch4_aere_depth_unsat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='CH4_AERE_DEPTH_UNSAT', units='mol/m3/s', type2d='levgrnd', & + avgflag='A', long_name='CH4 soil aerenchyma loss for non-inundated area '// & + ' (including transpiration flux if activated)', & + ptr_col=this%ch4_aere_depth_unsat_col, default=active_via_hist_wrtch4diag) + + this%o2_aere_depth_sat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='O2_AERE_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & + avgflag='A', long_name='O2 aerenchyma diffusion into soil for inundated / lake area', & + ptr_col=this%o2_aere_depth_sat_col, default=active_via_hist_wrtch4diag) + + this%o2_aere_depth_unsat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='O2_AERE_DEPTH_UNSAT', units='mol/m3/s', type2d='levgrnd', & + avgflag='A', long_name='O2 aerenchyma diffusion into soil for non-inundated area', & + ptr_col=this%o2_aere_depth_unsat_col, default=active_via_hist_wrtch4diag) + + call hist_addfld2d (fname='O2_DECOMP_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & + avgflag='A', long_name='O2 consumption from HR and AR for inundated / lake area', & + ptr_col=this%o2_decomp_depth_sat_col, default=active_via_hist_wrtch4diag) this%o2_decomp_depth_unsat_col(begc:endc,1:nlevgrnd) = spval call hist_addfld2d (fname='O2_DECOMP_DEPTH_UNSAT', units='mol/m3/s', type2d='levgrnd', & avgflag='A', long_name='O2 consumption from HR and AR for non-inundated area', & - ptr_col=this%o2_decomp_depth_unsat_col, default=active) - - if (hist_wrtch4diag) then - this%ch4_tran_depth_sat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='CH4_TRAN_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & - avgflag='A', long_name='CH4 soil loss from transpiration for inundated / lake area', & - ptr_col=this%ch4_tran_depth_sat_col) - end if + ptr_col=this%o2_decomp_depth_unsat_col, default=active_via_hist_wrtch4diag) + + this%ch4_tran_depth_sat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='CH4_TRAN_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & + avgflag='A', long_name='CH4 soil loss from transpiration for inundated / lake area', & + ptr_col=this%ch4_tran_depth_sat_col, default=active_via_hist_wrtch4diag) + + this%ch4_tran_depth_unsat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='CH4_TRAN_DEPTH_UNSAT', units='mol/m3/s', type2d='levgrnd', & + avgflag='A', long_name='CH4 soil loss from transpiration for non-inundated area', & + ptr_col=this%ch4_tran_depth_unsat_col, default=active_via_hist_wrtch4diag) + + this%ch4_ebul_depth_sat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='CH4_EBUL_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & + avgflag='A', long_name='CH4 soil ebullition for inundated / lake area', & + ptr_col=this%ch4_ebul_depth_sat_col, default=active_via_hist_wrtch4diag) + + this%ch4_ebul_depth_unsat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='CH4_EBUL_DEPTH_UNSAT', units='mol/m3/s', type2d='levgrnd', & + avgflag='A', long_name='CH4 soil ebullition for non-inundated area', & + ptr_col=this%ch4_ebul_depth_unsat_col, default=active_via_hist_wrtch4diag) + + this%o2stress_sat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='O2STRESS_SAT', units='unitless', type2d='levgrnd', & + avgflag='A', long_name='Ratio of oxygen available to demanded for non-inundated area', & + ptr_col=this%o2stress_sat_col, default=active_via_hist_wrtch4diag) + + this%o2stress_unsat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='O2STRESS_UNSAT', units='unitless', type2d='levgrnd', & + avgflag='A', long_name='Ratio of oxygen available to demanded for inundated / lake area', & + ptr_col=this%o2stress_unsat_col, default=active_via_hist_wrtch4diag) + + this%ch4stress_unsat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='CH4STRESS_UNSAT', units='unitless', type2d='levgrnd', & + avgflag='A', long_name='Ratio of methane available to total potential sink for inundated / lake area', & + ptr_col=this%ch4stress_unsat_col, default=active_via_hist_wrtch4diag) + + this%ch4stress_sat_col(begc:endc,1:nlevgrnd) = spval + call hist_addfld2d (fname='CH4STRESS_SAT', units='unitless', type2d='levgrnd', & + avgflag='A', long_name='Ratio of methane available to total potential sink for non-inundated area', & + ptr_col=this%ch4stress_sat_col, default=active_via_hist_wrtch4diag) - if (hist_wrtch4diag) then - this%ch4_tran_depth_unsat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='CH4_TRAN_DEPTH_UNSAT', units='mol/m3/s', type2d='levgrnd', & - avgflag='A', long_name='CH4 soil loss from transpiration for non-inundated area', & - ptr_col=this%ch4_tran_depth_unsat_col) - end if - - if (hist_wrtch4diag) then - this%ch4_ebul_depth_sat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='CH4_EBUL_DEPTH_SAT', units='mol/m3/s', type2d='levgrnd', & - avgflag='A', long_name='CH4 soil ebullition for inundated / lake area', & - ptr_col=this%ch4_ebul_depth_sat_col) - end if - - if (hist_wrtch4diag) then - this%ch4_ebul_depth_unsat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='CH4_EBUL_DEPTH_UNSAT', units='mol/m3/s', type2d='levgrnd', & - avgflag='A', long_name='CH4 soil ebullition for non-inundated area', & - ptr_col=this%ch4_ebul_depth_unsat_col) - end if - - if (hist_wrtch4diag) then - this%o2stress_sat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='O2STRESS_SAT', units='unitless', type2d='levgrnd', & - avgflag='A', long_name='Ratio of oxygen available to demanded for non-inundated area', & - ptr_col=this%o2stress_sat_col) - end if - - if (hist_wrtch4diag) then - this%o2stress_unsat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='O2STRESS_UNSAT', units='unitless', type2d='levgrnd', & - avgflag='A', long_name='Ratio of oxygen available to demanded for inundated / lake area', & - ptr_col=this%o2stress_unsat_col) - end if - - if (hist_wrtch4diag) then - this%ch4stress_unsat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='CH4STRESS_UNSAT', units='unitless', type2d='levgrnd', & - avgflag='A', long_name='Ratio of methane available to total potential sink for inundated / lake area', & - ptr_col=this%ch4stress_unsat_col) - end if - - if (hist_wrtch4diag) then - this%ch4stress_sat_col(begc:endc,1:nlevgrnd) = spval - call hist_addfld2d (fname='CH4STRESS_SAT', units='unitless', type2d='levgrnd', & - avgflag='A', long_name='Ratio of methane available to total potential sink for non-inundated area', & - ptr_col=this%ch4stress_sat_col) - end if - - if (hist_wrtch4diag .and. allowlakeprod) then + if (allowlakeprod) then this%ch4_prod_depth_sat_col(begc:endc,1:nlevgrnd) = spval call hist_addfld2d (fname='CH4_PROD_DEPTH_LAKE', units='mol/m3/s', type2d='levgrnd', & avgflag='A', long_name='CH4 production in each soil layer, lake col. only', & - ptr_col=this%ch4_prod_depth_sat_col) + ptr_col=this%ch4_prod_depth_sat_col, default=active_via_hist_wrtch4diag) end if - if (hist_wrtch4diag .and. allowlakeprod) then + if (allowlakeprod) then this%conc_ch4_sat_col(begc:endc,1:nlevgrnd) = spval call hist_addfld2d (fname='CONC_CH4_LAKE', units='mol/m3', type2d='levgrnd', & avgflag='A', long_name='CH4 Concentration each soil layer, lake col. only', & - ptr_col=this%conc_ch4_sat_col) + ptr_col=this%conc_ch4_sat_col, default=active_via_hist_wrtch4diag) end if - if (hist_wrtch4diag .and. allowlakeprod) then + if (allowlakeprod) then this%conc_o2_sat_col(begc:endc,1:nlevgrnd) = spval call hist_addfld2d (fname='CONC_O2_LAKE', units='mol/m3', type2d='levgrnd', & avgflag='A', long_name='O2 Concentration each soil layer, lake col. only', & - ptr_col=this%conc_o2_sat_col) + ptr_col=this%conc_o2_sat_col, default=active_via_hist_wrtch4diag) end if - if (hist_wrtch4diag .and. allowlakeprod) then + if (allowlakeprod) then this%ch4_surf_diff_sat_col(begc:endc) = spval call hist_addfld1d (fname='CH4_SURF_DIFF_LAKE', units='mol/m2/s', & avgflag='A', long_name='diffusive surface CH4 flux, lake col. only (+ to atm)', & - ptr_col=this%ch4_surf_diff_sat_col) + ptr_col=this%ch4_surf_diff_sat_col, default=active_via_hist_wrtch4diag) end if - if (hist_wrtch4diag .and. allowlakeprod) then + if (allowlakeprod) then this%ch4_surf_ebul_sat_col(begc:endc) = spval call hist_addfld1d (fname='CH4_SURF_EBUL_LAKE', units='mol/m2/s', & avgflag='A', long_name='ebullition surface CH4 flux, lake col. only (+ to atm)', & - ptr_col=this%ch4_surf_ebul_sat_col) + ptr_col=this%ch4_surf_ebul_sat_col, default=active_via_hist_wrtch4diag) end if - if (hist_wrtch4diag .and. allowlakeprod) then + if (allowlakeprod) then this%ch4_oxid_depth_sat_col(begc:endc,1:nlevgrnd) = spval call hist_addfld2d (fname='CH4_OXID_DEPTH_LAKE', units='mol/m2/s', type2d='levgrnd', & avgflag='A', long_name='CH4 oxidation in each soil layer, lake col. only', & - ptr_col=this%ch4_oxid_depth_sat_col) - end if - - if (hist_wrtch4diag) then - this%layer_sat_lag_col(begc:endc,1:nlevgrnd) = spval - ! Using l2g_scale_type='veg' to exclude mass in special landunits, which can arise - ! from dynamic column adjustments. (We also exclude lakes here, because they don't - ! have any unsaturated area.) - call hist_addfld2d (fname='LAYER_SAT_LAG', units='unitless', type2d='levgrnd', & - avgflag='A', long_name='lagged saturation status of layer in unsat. zone', & - ptr_col=this%layer_sat_lag_col, l2g_scale_type='veg') + ptr_col=this%ch4_oxid_depth_sat_col, default=active_via_hist_wrtch4diag) end if - if (hist_wrtch4diag) then - this%annavg_finrw_col(begc:endc) = spval - call hist_addfld1d (fname='ANNAVG_FINRW', units='unitless', & - avgflag='A', long_name='annual average respiration-weighted FINUNDATED', & - ptr_col=this%annavg_finrw_col) - end if - - if (hist_wrtch4diag) then - this%sif_col(begc:endc) = spval - call hist_addfld1d (fname='SIF', units='unitless', & - avgflag='A', long_name='seasonal inundation factor calculated for sat. CH4 prod. (non-lake)', & - ptr_col=this%sif_col) - end if + this%layer_sat_lag_col(begc:endc,1:nlevgrnd) = spval + ! Using l2g_scale_type='veg' to exclude mass in special landunits, which can arise + ! from dynamic column adjustments. (We also exclude lakes here, because they don't + ! have any unsaturated area.) + call hist_addfld2d (fname='LAYER_SAT_LAG', units='unitless', type2d='levgrnd', & + avgflag='A', long_name='lagged saturation status of layer in unsat. zone', & + ptr_col=this%layer_sat_lag_col, l2g_scale_type='veg', default=active_via_hist_wrtch4diag) + + this%annavg_finrw_col(begc:endc) = spval + call hist_addfld1d (fname='ANNAVG_FINRW', units='unitless', & + avgflag='A', long_name='annual average respiration-weighted FINUNDATED', & + ptr_col=this%annavg_finrw_col, default=active_via_hist_wrtch4diag) + + this%sif_col(begc:endc) = spval + call hist_addfld1d (fname='SIF', units='unitless', & + avgflag='A', long_name='seasonal inundation factor calculated for sat. CH4 prod. (non-lake)', & + ptr_col=this%sif_col, default=active_via_hist_wrtch4diag) this%conc_o2_sat_col(begc:endc,1:nlevgrnd) = spval ! Using l2g_scale_type='veg_plus_lake' to exclude mass in non-lake special landunits, diff --git a/tools/contrib/prep_co2_wiemip_files.m b/tools/contrib/prep_co2_wiemip_files.m new file mode 100644 index 0000000000..38b7fe25a9 --- /dev/null +++ b/tools/contrib/prep_co2_wiemip_files.m @@ -0,0 +1,48 @@ +% prep_co2_wiemip_files.m +% +% Reminder: MODIFY file_raw and file_wiemip below for each individual case +% +% Workflow: +% - Before running this matlab script, I renamed the TRENDY2025 co2 file (fco2_datm_global_simyr_1700-2024_TRENDY_c250625.nc) to the name of the wiemip co2 file (used below) +% - The script, extends CO2 and time vars in the file from 2024 (TRENDY2025) to 2300 (wiemip) +% - and brings in wiemip co2 to the file +% - After running the matlab script, I used nco to append to each file's history, for example: +% ncatted -h -a history,global,o,c,"06/25/2025 21:30: converted by TRENDY2024_Data_Prep.ipynb; 06/04/2026: slevis used matlab script tools/contrib/prep_co2_wiemip_files.m to extend the co2 and time variables from 2024 to 2300 and to append the co2 from WIEMIP_hl_co2_ann_2024_2300.txt" WIEMIP_hl_co2_ann_2024_2300_copied_to_fco2_datm_global_simyr_1700-2024_TRENDY_c250625.nc +% +% More information appears in issues +% github.com/ESCOMP/CTSM/issues/4072 +% github.com/ESCOMP/CTSM/issues/3936 +% +% slevis 2026/06/03 + +clear + +% get trendy CO2, time, time_bnds +file_trendy = 'fco2_datm_global_simyr_1700-2024_TRENDY_c250625.nc'; +co2_trendy = ncread(file_trendy, 'CO2'); +time_trendy = ncread(file_trendy, 'time'); +time_bnds_trendy = ncread(file_trendy, 'time_bnds'); + +% extend CO2, time, time_bnds +co2_wiemip = co2_trendy; % orig. to 2024 +time_wiemip = time_trendy; % orig. to 2024 +time_bnds_wiemip = time_bnds_trendy; % orig. to 2024 +for yr = 1:276 % out to 2300 + co2_wiemip(:,:,end+1) = co2_wiemip(:,:,end); % dims (lon, lat, time) + time_wiemip(end+1) = time_wiemip(end) + 365; % dims (time) + time_bnds_wiemip(:,end+1) = time_bnds_wiemip(:,end); % dims (bnds, time) +end +% Fix time_bnds preexisting glitch in 2021 +time_bnds_wiemip(:,322) = time_bnds_wiemip(:,321); % dims (bnds, time) + +% get wiemip co2 for the years 2024-2300 +file_raw = '/glade/derecho/scratch/swensosc/WIEMIP/co2/WIEMIP_m_co2_ann_2024_2300.txt'; +co2 = readmatrix(file_raw); +co2_wiemip(1,1,325:end) = squeeze(co2(:,2)); + +% write modified time, time_bnds, and CO2 to the renamed trendy file +file_wiemip = 'WIEMIP_m_co2_ann_2024_2300_copied_to_fco2_datm_global_simyr_1700-2024_TRENDY_c250625.nc'; +ncwrite(file_wiemip, 'time', time_wiemip); +ncwrite(file_wiemip, 'time_bnds', time_bnds_wiemip); +ncwrite(file_wiemip, 'CO2', co2_wiemip); +