diff --git a/.github/workflows/docs-pr-failure-post-comment.yml b/.github/workflows/docs-pr-failure-post-comment.yml new file mode 100644 index 0000000000..2a8928b28c --- /dev/null +++ b/.github/workflows/docs-pr-failure-post-comment.yml @@ -0,0 +1,66 @@ +name: Post PR comment with doc-build failure log + +env: + DOCS_FAILURE_ARTIFACT: test-build-docs-container_failed + +on: + workflow_run: + workflows: ["Test building docs when they're updated"] + types: [completed] + +jobs: + comment: + if: >- + github.event.workflow_run.event == 'pull_request' + && github.event.workflow_run.conclusion == 'failure' + runs-on: ubuntu-latest + permissions: + pull-requests: write + actions: read + steps: + - name: Check for failure artifact + id: check + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPO: ${{ github.repository }} + run: | + gh api repos/$REPO/actions/runs/${{ github.event.workflow_run.id }}/artifacts \ + --jq '.artifacts[] | select(.name == "${{ env.DOCS_FAILURE_ARTIFACT }}") | .id' > artifact_id.txt + + if [ -s artifact_id.txt ]; then + echo "found=true" >> $GITHUB_OUTPUT + else + echo "found=false" >> $GITHUB_OUTPUT + fi + + - name: Download logs + if: steps.check.outputs.found == 'true' + uses: actions/download-artifact@v4 + with: + name: ${{ env.DOCS_FAILURE_ARTIFACT }} + path: ${{ env.DOCS_FAILURE_ARTIFACT }} + run-id: ${{ github.event.workflow_run.id }} + github-token: ${{ secrets.GITHUB_TOKEN }} + + - name: Post comment + if: steps.check.outputs.found == 'true' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPO: ${{ github.repository }} + run: | + PR_NUMBER=$(cat "${DOCS_FAILURE_ARTIFACT}/pr_number.txt") + + { + echo "### ❌ Docs build failed" + echo + echo '
' + echo "Build logs" + echo + echo '```' + cat "${DOCS_FAILURE_ARTIFACT}/build.log" + echo '```' + echo + echo "
" + } > comment-body.md + + gh pr comment "$PR_NUMBER" --repo "$REPO" --body-file comment-body.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 780ba31b64..6c211d2a3c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -61,4 +61,24 @@ jobs: - name: Build docs using Docker (Podman has trouble on GitHub runners) id: build-docs run: | - cd doc && ./build_docs -b ${PWD}/_build -c -d + set -o pipefail + mkdir -p build-logs + cd doc && PYTHONUNBUFFERED=1 ./build_docs -b ${PWD}/_build -c -d 2>&1 | tee >(sed -E $'s/\x1b\\[[0-9;]*[a-zA-Z]//g' > "${GITHUB_WORKSPACE}/build-logs/build.log") + # The tee writes build.log for the PR comment (posted by docs-pr-failure-post-comment.yml); the inner sed strips ANSI color codes that would otherwise render as garbage in the comment. + # PYTHONUNBUFFERED=1 because otherwise the teed log will be out of order + + # The rest of the steps only trigger on failure of above build-docs step. + # They upload logs that will be used by the docs-pr-failure-post-comment.yml workflow. + + - name: Record PR number on failure + if: failure() && steps.build-docs.outcome == 'failure' && github.event_name == 'pull_request' + run: | + mkdir -p build-logs + echo "${{ github.event.pull_request.number }}" > build-logs/pr_number.txt + + - name: Upload logs on failure + if: failure() && steps.build-docs.outcome == 'failure' + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: test-build-docs-container_failed + path: build-logs/ diff --git a/.gitmodules b/.gitmodules index 81873b7867..734aecca0c 100644 --- a/.gitmodules +++ b/.gitmodules @@ -68,7 +68,7 @@ fxDONOTUSEurl = https://github.com/ESCOMP/mizuRoute [submodule "ccs_config"] path = ccs_config url = https://github.com/ESMCI/ccs_config_cesm.git -fxtag = ccs_config_cesm1.0.79 +fxtag = ccs_config_cesm1.0.83 fxrequired = ToplevelRequired # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed fxDONOTUSEurl = https://github.com/ESMCI/ccs_config_cesm.git @@ -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.169 +fxtag = cime6.1.176 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.37 +fxtag = cmeps1.1.44 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 diff --git a/bld/CLMBuildNamelist.pm b/bld/CLMBuildNamelist.pm index fa54a6466f..bfa4d2d44e 100755 --- a/bld/CLMBuildNamelist.pm +++ b/bld/CLMBuildNamelist.pm @@ -2083,13 +2083,16 @@ sub setup_logic_irrigate { my ($opts, $nl_flags, $definition, $defaults, $nl) = @_; add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'irrigate', - 'use_crop'=>$nl_flags->{'use_crop'}, 'use_cndv'=>$nl_flags->{'use_cndv'}, + 'use_crop'=>$nl_flags->{'use_crop'}, 'use_cndv'=>$nl_flags->{'use_cndv'}, 'use_fates'=>$nl_flags->{'use_fates'}, 'sim_year'=>$nl_flags->{'sim_year'}, 'sim_year_range'=>$nl_flags->{'sim_year_range'}, ); if ( &value_is_true($nl->get_value('irrigate') ) ) { $nl_flags->{'irrigate'} = ".true."; if ( $nl_flags->{'sim_year'} eq "PtVg" ) { $log->fatal_error("irrigate=TRUE does NOT make sense with the Potential Vegetation dataset, leave irrigate=FALSE"); } + if (&value_is_true($nl_flags->{'use_fates'})) { + $log->fatal_error("irrigate=TRUE is NOT possible with use_fates=TRUE, leave irrigate=FALSE"); + } } else { $nl_flags->{'irrigate'} = ".false."; } diff --git a/bld/namelist_files/namelist_defaults_ctsm.xml b/bld/namelist_files/namelist_defaults_ctsm.xml index 130dd2737b..c52593d0b8 100644 --- a/bld/namelist_files/namelist_defaults_ctsm.xml +++ b/bld/namelist_files/namelist_defaults_ctsm.xml @@ -200,10 +200,11 @@ attributes from the config_cache.xml file (with keys converted to upper-case). 1700 -.false. -.true. -.true. -.false. +.false. +.false. +.true. +.true. +.false. .false. diff --git a/bld/unit_testers/build-namelist_test.pl b/bld/unit_testers/build-namelist_test.pl index 3cbd92cb24..75a5199bea 100755 --- a/bld/unit_testers/build-namelist_test.pl +++ b/bld/unit_testers/build-namelist_test.pl @@ -165,7 +165,7 @@ sub cat_and_create_namelistinfile { # # Figure out number of tests that will run # -my $ntests = 3403; +my $ntests = 3405; if ( defined($opts{'compare'}) ) { $ntests += 2061; @@ -1271,6 +1271,10 @@ sub cat_and_create_namelistinfile { namelst=>"z0param_method=Meier2022", phys=>"clm5_0", }, + "FATES_w_irrig" =>{ options=>"-envxml_dir . -res 0.9x1.25 -bgc fates -use_case 20thC_transient", + namelst=>"irrigate=T", + phys=>"clm6_0", + }, "noanthro_w_crop" =>{ options=>"-envxml_dir . -res 0.9x1.25 -bgc bgc -crop -use_case 1850_noanthro_control", namelst=>"", phys=>"clm5_0", diff --git a/ccs_config b/ccs_config index 8fe3339bd2..39683243b4 160000 --- a/ccs_config +++ b/ccs_config @@ -1 +1 @@ -Subproject commit 8fe3339bd2b75c2090e06b054972bcd805c9d408 +Subproject commit 39683243b4e8e5b4576fd1b828c3ec4c9e15bc6b diff --git a/cime b/cime index ffbf6c596c..51cfec52f2 160000 --- a/cime +++ b/cime @@ -1 +1 @@ -Subproject commit ffbf6c596c5736538690af1bc9269d830abcd53c +Subproject commit 51cfec52f297eb4d30dd34548bf4b69b9ab72d1e diff --git a/components/cmeps b/components/cmeps index 480bfc1502..ebcfeafa52 160000 --- a/components/cmeps +++ b/components/cmeps @@ -1 +1 @@ -Subproject commit 480bfc1502d42ae1decdc56c731f0dd80fbf9139 +Subproject commit ebcfeafa524f29181058f64809d165a58733236e diff --git a/doc/.ChangeLog_template b/doc/.ChangeLog_template index bc14f4ff75..95ea01885b 100644 --- a/doc/.ChangeLog_template +++ b/doc/.ChangeLog_template @@ -53,6 +53,8 @@ Substantial timing or memory changes: [e.g., check PFS test in the test suite and look at timings, if you expect possible significant timing changes] +Contributors: + Notes of particular relevance for developers: --------------------------------------------- NOTE: Be sure to review the steps in README.CHECKLIST.master_tags as well as the coding style in the Developers Guide @@ -62,8 +64,6 @@ Caveats for developers (e.g., code that is duplicated that requires double maint Changes to tests or testing: -Contributors: - Testing summary: ---------------- [... Remove before making master tag. diff --git a/doc/ChangeLog b/doc/ChangeLog index 2d367f8a85..0434db547f 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,4 +1,82 @@ =============================================================== +Tag name: ctsm5.4.035 +Originator(s): erik (Erik Kluzek,UCAR/TSS,303-497-1326) +Date: Sun Apr 26 09:38:17 PM MDT 2026 +One-line Summary: Merge b4b-dev to master + +Purpose and description of changes +---------------------------------- + +Update submodules, enforce irrigate to off for FATES transient cases, and several documentation updates. Including a github action that will trigger when a PR has a build failure for the documentation. It will then add a comment to the PR summarizing the error. Hopefully, this will be easier for doc editors to understand what broke in the build for their PR. + +When a PR has the "build docs" tests fail, it's hard to figure out why. This PR will make it so that the doc build log is posted in a PR comment after the test failure. Example samsrabin#17 (comment). + +Since ctsm5.3.046: patch%itype is set to -999, which produces out-of-bounds error, when running HIST with fates, since the defaults point to irrigate=.true.. + +Though there is irrigate=.true. in use_cases, all the statements with .true. value have use_crop=.true. which can not be true when fates is on. + +Bugs fixed +---------- + +List of CTSM issues fixed (include CTSM Issue # and description) [one per line]: + +Fixes #3170 +Most of #3861 except #3968 + +Notes of particular relevance for users +--------------------------------------- + +Changes made to namelist defaults (e.g., changed parameter values): + For FATES ensure that irrigate is off for transient cases + +Changes to documentation: Updates to the mizuRoute and dust emission chapters + +Contributors: @dmleung @nmizukami @samsrabin @olyson @mvdebolskiy Claude Sonnet 4.6 and Opus 4.7 1M + +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 - + + python testing (if python code has changed; see instructions in python/README.md; document testing done): + + derecho - + + regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing): + + derecho ----- + izumi ------- + +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.): ccs_config, cime, cmeps + Update to the latest submodules for the time. This is beyond the versions in cesm3_0_beta08 + + ccs_config to ccs_config_cesm1.0.83 (includes grids for the new t233 ocean mask for MOM) + cime to cime6.1.176 + cmeps to cmeps1.1.44 + +Pull Requests that document the changes (include PR ids): +(https://github.com/ESCOMP/ctsm/pull) + +#3624 -- dust emission chapter in Tech Note +#3925 -- mizuRoute chapter in Tech Note +#3955 -- New workflow to add comments to PR about a failure in the doc-build action +#3938 -- Update submodules +#3812 -- Ensure irrigate is FALSE for FATES for transient cases + +=============================================================== +=============================================================== Tag name: ctsm5.4.034 Originator(s): afoster (Adrianna Foster,UCAR/TSS,303-497-1728) Date: Wed Apr 22 11:02:13 AM MDT 2026 diff --git a/doc/ChangeSum b/doc/ChangeSum index eefd3e03b8..1d05e5e78a 100644 --- a/doc/ChangeSum +++ b/doc/ChangeSum @@ -1,5 +1,6 @@ Tag Who Date Summary ============================================================================================================================ + ctsm5.4.035 erik 04/26/2026 Merge b4b-dev to master ctsm5.4.034 afoster 04/22/2026 bug fix to the FATES land use driver input code ctsm5.4.033 glemieux 04/17/2026 Update fates tag with missing land use data check fix ctsm5.4.032 samrabin 04/10/2026 Simplify doc build messaging. 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 ad593b6060..299d559e34 100644 --- a/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst +++ b/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst @@ -1,124 +1,326 @@ .. _rst_Dust Model: -Dust Model +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 speed, the vegetation cover, and the soil moisture The CLM dust mobilization scheme (:ref:`Mahowald et al. 2006` accounts for these factors based on the DEAD (Dust Entrainment and Deposition model of :ref:`Zender et al. (2003)`. Please refer to the :ref:`Zender et al. (2003)` article for additional information regarding the equations presented in this section. +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. -The total vertical mass flux of dust, :math:`F_{j}` (kg m\ :sup:`-2` s\ :sup:`-1`), from the ground into transport bin :math:`j` is given by +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. + + +.. _Dust Emission Thresholds: + +Dust Emission Thresholds +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _Fluid Threshold: + +Fluid Threshold +--------------------- + +Dust emission modeling is a threshold parameterization of an aeolian (wind-driven) process for both Leung_2023 and Zender_2003. For Leung_2023, in any given timestep the soil surface wind velocity :math:`u_{*s}` has to be greater than the fluid threshold friction velocity :math:`u_{*ft}` to generate saltation and dust emission: + +.. math:: + :label: wet_fluid_threshold + + u_{*ft} = u_{*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)`: + +.. math:: + :label: dry_fluid_threshold + + u_{*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. + +.. _Impact of Soil Moisture: + +Impact of Soil Moisture +------------------------- + +The soil moisture effect :math:`f_{m}(w)` is a function of gravimetric soil moisture :math:`w` (kg water / kg soil) at the topmost soil layer. + +:math:`w` is converted from the CLM volumetric soil moisture :math:`\theta` and porosity (saturation moisture :math:`\theta_{sat}`) at the topmost soil layer: + +.. math:: + :label: volumetric_moisture_to_gravimetric_moisture + + w=\theta\frac{ \rho _{liq} }{\rho_{bulk} } + +Note that :math:`w` or :math:`\theta` in CTSM is conventionally (:ref:`Mahowald et al. 2006`) treated as a sum of both liquid and ice/frozen soil moisture at the topmost soil layer, i.e., :math:`w_{1} = w_{liq,1} + w_{ice,1}`. We skip :math:`w_{1}` and use :math:`w` for simplicity. :math:`\theta` is the volumetric soil moisture (water+ice) in the topmost soil layer (m\ :sup:`-3`\ water \ m\ :sup:`-3` soil) (section :numref:`Soil Water`), :math:`\rho _{liq}` is the density of liquid water (kg m\ :sup:`-3`) (:numref:`Table Physical constants`), and :math:`\rho _{bulk}` is the bulk density of soil in the top soil layer (kg m\ :sup:`-3`) defined as in section :numref:`Soil and Snow Thermal Properties` rather than as in :ref:`Zender et al. (2003)`. :math:`\rho_{bulk}` is given by + +.. math:: + :label: soil_bulk_density + + \rho_{bulk} = (1 - \theta_{sat} ) \rho_{p} + +Then, the soil moisture effect :math:`f_{m}(w)` on increasing the fluid threshold is given by :ref:`Fecan et al. (1999)`: + +.. math:: + :label: moisture_factor_on_fluid_threshold + + f_{m}(w) =\left\{\begin{array}{l} {1{\rm \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; for\; }w\le w_{t} } \\ {\sqrt{1+1.21\left[100\left(w-w_{t} \right)\right]^{0.68} } {\rm \; \; for\; }w>w_{t} } \end{array}\right. + + +where :math:`w_{t}` is the minimum gravimetric moisture threshold required to increase the interparticle force and :math:`u_{*ft}`. :math:`w_{t}` increases with clay fraction :math:`f_{clay}`: + +.. math:: + :label: minimum_moisture + + w_{t} =0.01a\left(17f_{clay} +14f_{clay}^{2} \right){\rm \; \; \; \; \; \; 0}\le f_{clay} =\% clay\times 0.01\le 1 + + +where :math:`a=f_{clay}^{-1}` for tuning purposes. Note that this is different from the paper (:ref:`Leung et al. 2023`; :ref:`Leung et al. 2024`) in which :math:`a=1` was chosen. The coefficient 0.01 is used for converting :math:`w_{t}` from % to fraction (kg water / kg soil). :math:`f_{clay}` is the mass fraction of clay particles in the topmost soil layer and %clay comes from the surface dataset (section :numref:`Surface Data`). + +.. _Impact Threshold: + +Impact Threshold +---------------------- + +Another essential dust emission threshold is the impact/dynamic threshold :math:`u_{*it}`, which is the lowest friction velocity or wind stress to matintain saltation: + +.. math:: + :label: impact_threshold + + u_{*it} = B_{*it} u_{*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}`. + +.. _Dust Emission Flux: + +Dust Emission Flux +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The total vertical mass emission flux of dust, :math:`F_{d}` (kg m\ :sup:`-2` s\ :sup:`-1`), from the ground into a transport mode/bin :math:`j` of aerosol is based on :ref:`Kok et al. (2014a)`: + +.. 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 + +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). +: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:: + :label: clay_sandblast_fact_zender + + f_{clay'} = \textnormal{max}(f_{clay}, 0.2) + +:math:`f_{clay'}` is later adopted by :ref:`Kok et al. (2014a)` to indicate the amount of fine dust particles for sandblasting. The same :math:`f_{clay'}` is used in :ref:`Leung et al. (2024)`. But we later further limit :math:`f_{clay'}` to be within 0.1 and 0.2 to further reduce the impact of how the abundance of fine dust particles can scale the total dust emission flux, as part of the CESM tuning: + +.. math:: + :label: clay_sandblast_fact_leung + + f_{clay'} = \textnormal{max}(0.1+0.5f_{clay}, 0.2) + +Then, :math:`\kappa` is the fragmentation exponent, and :math:`C_{d}` is the dust emission coefficient (or the soil erodibility coefficient): + +.. math:: + :label: dust_emiss_coefficient + + C_{d} = C_{d0} \exp{ (-C_{e} \frac{ u_{*st} - u_{st0} }{ u_{st0} } ) } .. math:: - :label: 29.1 + :label: fragment_exponent + + \kappa = C_{\kappa} \frac{ u_{*st} - u_{st0} }{ u_{st0} } - F_{j} =TSf_{m} \alpha Q_{s} \sum _{i=1}^{I}M_{i,j} +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): + +.. math:: + :label: standard_fluid_threshold -where :math:`T` is a global factor that compensates for the DEAD model's sensitivity to horizontal and temporal resolution and equals 5 x 10\ :sup:`-4` in the CLM instead of 7 x 10\ :sup:`-4` in :ref:`Zender et al. (2003)`. :math:`S` is the source erodibility factor set to 1 in the CLM and serves as a place holder at this time. + u_{*st} = u_{*ft} \sqrt{ \rho_{atm} / \rho_{0atm}} -The grid cell fraction of exposed bare soil suitable for dust mobilization :math:`f_{m}` is given by +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. + +: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. + +The grid cell fraction of exposed bare soil suitable for dust mobilization :math:`f_{bare}` is given by .. math:: - :label: 29.2 + :label: grid_bare_land_frac - f_{m} =\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} } + 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: 29.3 + :label: grid_vegetated_frac + + 0\le f_{v} =\frac{\mathrm{VAI}}{\mathrm{VAI_{thr}} } \le 1{\rm \; \; \; \; where\; } \mathrm{VAI_{thr}} =0.6{\rm \; m}^{2} {\rm m}^{-2} - 0\le f_{v} =\frac{L+S}{\left(L+S\right)_{t} } \le 1{\rm \; \; \; \; where\; }\left(L+S\right)_{t} =0.3{\rm \; m}^{2} {\rm m}^{-2} +where :math:`\mathrm{VAI}=\mathrm{LAI}+\mathrm{SAI}` is the vegetation area index as a sum of the CLM leaf and stem area index values (m :sup:`2` leaf m\ :sup:`-2` grid) averaged at the land unit level so as to include all the pfts and the bare ground present in a vegetated land unit. Currently, Leung_2023 in CTSM sets the areas with :math:`\mathrm{VAI_{thr}}` smaller than or equal to 0.6 m :sup:`2` m\ :sup:`-2` to be dust-emitting grids, different from the :ref:`Leung et al. (2024)` paper that set :math:`\mathrm{VAI_{thr}}` to be 1 m :sup:`2` m\ :sup:`-2`. :math:`\mathrm{LAI}` and :math:`\mathrm{SAI}` may be prescribed from the CLM input data (section :numref:`Phenology and vegetation burial by snow`) or simulated by the CLM biogeochemistry model (section :numref:`rst_Vegetation Phenology and Turnover`). + +.. _Drag Partition Effect On Reducing Wind Stress: + +Drag Partition Effect On Reducing Wind Stress +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On top of :ref:`Kok et al. (2014a)`, Leung_2023 introduced the soil surface friction velocity :math:`u_{*s}` as the friction velocity :math:`u_{*}` from CLM corrected by the surface roughness due to the presented rocks and vegetation on the soil surface, encapsulated by the so-called drag partition factor :math:`F_{eff}`. + +.. math:: + :label: soil_surface_ustar + + u_{*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: + +.. math:: + :label: rock_drag_partition + + F_{eff} = f_{rock} + +And for a patch/PFT with short vegetation (shrub, grass, crop) we use: + +.. math:: + :label: veg_drag_partition -where equation :eq:`29.3` applies only for dust mobilization and is not related to the plant functional type fractions prescribed from the CLM input data or simulated by the CLM dynamic vegetation model (Chapter 22). :math:`L` and :math:`S` are the CLM leaf and stem area index values (m :sup:`2` m\ :sup:`-2`) averaged at the land unit level so as to include all the pfts and the bare ground present in a vegetated land unit. :math:`L` and :math:`S` may be prescribed from the CLM input data (section :numref:`Phenology and vegetation burial by snow`) or simulated by the CLM biogeochemistry model (Chapter :numref:`rst_Vegetation Phenology and Turnover`). + F_{eff} = f_{veg} -The sandblasting mass efficiency :math:`\alpha` (m :sup:`-1`) is calculated as +The rock drag partition factor scales with the surface roughness density of rocks, captured by the aeolian roughness length :math:`z_{0a}` from the satellite-derived dataset from :ref:`Prigent et al. (2005)`. The expression was first developed by :ref:`Marticorena and Bergametti (1995)`, which is more valid for the low-roughness surfaces: .. math:: - :label: 29.4 + :label: rock_drag_partition_fact - \alpha =100e^{\left(13.4M_{clay} -6.0\right)\ln 10} {\rm \; \; }\left\{\begin{array}{l} {M_{clay} =\% clay\times 0.01{\rm \; \; \; 0}\le \% clay\le 20} \\ {M_{clay} =20\times 0.01{\rm \; \; \; \; \; \; \; \; 20<\% }clay\le 100} \end{array}\right. + f_{rock} = 1 - \frac{\ln(\frac{z_{0a}}{z_{0s}})}{\ln[b_{1}(\frac{X}{z_{0s}})^{b_{2}}]} -where :math:`M_{clay}` is the mass fraction of clay particles in the soil and %clay is determined from the surface dataset (section :numref:`Surface Data`). :math:`M_{clay} =0` corresponds to sand and :math:`M_{clay} =0.2` to sandy loam. +where :math:`X = 10` m is the distance downstream the point of discontinuity in surface obstacle, :math:`b_{1} = 0.7` and :math:`b_{2} = 0.8` are coefficients (:ref:`Darmenova et al., 2009`), :math:`z_{0s}` is the soil roughness length. :math:`z_{0a}` is from :ref:`Prigent et al. (2005)` and should not be confused with the aerodynamic roughness length :math:`Z_{0}` from the model. This equation only applies for gridcells with VAI smaller than the VAI threshold for dust emission. -:math:`Q_{s}` is the total horizontally saltating mass flux (kg m\ :sup:`-1` s\ :sup:`-1`) of "large" particles (:numref:`Table Dust Mass fraction`), also referred to as the vertically integrated streamwise mass flux +The vegetation drag partition factor scales with vegetation density as captured by VAI following :ref:`Okin (2008)` and :ref:`Pierre et al. (2014)`: .. math:: - :label: 29.5 + :label: veg_drag_partition_effect - Q_{s} = \left\{ - \begin{array}{lr} - \frac{c_{s} \rho _{atm} u_{*s}^{3} }{g} \left(1-\frac{u_{*t} }{u_{*s} } \right)\left(1+\frac{u_{*t} }{u_{*s} } \right)^{2} {\rm \; } & \qquad {\rm for\; }u_{*t} `, in which a statistical substepping method was proposed to account for the temporary shutoff of dust emission fluxes. + +The fraction of time :math:`\eta` is parameterized using the surface winds and thresholds at the saltation height. Therefore, the friction velocities are translated using the log law of the wall to the saltation height, which was defined as :math:`z_{sal}` = 0.1 m by :ref:`Comola et al. (2019)`: .. math:: - :label: 29.6 + :label: mean_wind_sal_height - u_{*t} =f_{z} \left[Re_{*t}^{f} \rho _{osp} gD_{osp} \left(1+\frac{6\times 10^{-7} }{\rho _{osp} gD_{osp}^{2.5} } \right)\right]^{\frac{1}{2} } \rho _{atm} ^{-\frac{1}{2} } f_{w} + u_{s} = \frac{u_{*s}}{k} \ln(z_{sal}/z_{0a}) -where :math:`f_{z}` is a factor dependent on surface roughness but set to 1 as a place holder for now, :math:`\rho _{osp}` and :math:`D_{osp}` are the density (2650 kg m\ :sup:`-3`) and diameter (75 x 10\ :math:`{}^{-6}` m) of optimal saltation particles, and :math:`f_{w}` is a factor dependent on soil moisture: +.. math:: + :label: fluid_threshold_sal_height + + u_{ft} = \frac{u_{*ft}}{k} \ln(z_{sal}/z_{0a}) .. math:: - :label: 29.7 + :label: imapct_threshold_sal_height - f_{w} =\left\{\begin{array}{l} {1{\rm \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; for\; }w\le w_{t} } \\ {\sqrt{1+1.21\left[100\left(w-w_{t} \right)\right]^{0.68} } {\rm \; \; for\; }w>w_{t} } \end{array}\right. + u_{it} = \frac{u_{*it}}{k} \ln(z_{sal}/z_{0a}) -where +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: 29.8 + :label: instant_wind_sal_height - w_{t} =a\left(0.17M_{clay} +0.14M_{clay}^{2} \right){\rm \; \; \; \; \; \; 0}\le M_{clay} =\% clay\times 0.01\le 1 + \tilde{u}_s \sim N(u_s, \sigma_{u_s}) -and +And the fluctuation strength is parameterized by the similarity theory: .. math:: - :label: 29.9 + :label: fluctuation_sal_height + + \sigma_{u_s} = u_{*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. - w=\frac{\theta _{1} \rho _{liq} }{\rho _{d,1} } -where :math:`a=M_{clay}^{-1}` for tuning purposes, :math:`\theta _{1}` is the volumetric soil moisture in the top soil layer (m :math:`{}^{3 }`\ m\ :sup:`-3`) (section :numref:`Soil Water`), :math:`\rho _{liq}` is the density of liquid water (kg m\ :sup:`-3`) (:numref:`Table Physical constants`), and :math:`\rho _{d,\, 1}` is the bulk density of soil in the top soil layer (kg m\ :sup:`-3`) defined as in section :numref:`Soil and Snow Thermal Properties` rather than as in :ref:`Zender et al. (2003)`. :math:`Re_{*t}^{f}` from equation :eq:`29.6` is the threshold friction Reynolds factor +Then, the total fraction of time :math:`\eta` when saltation is active within a model timestep is then formulated as .. math:: - :label: 29.10 + :label: intermittency_fact - Re_{*t}^{f} =\left\{\begin{array}{l} {\frac{0.1291^{2} }{-1+1.928Re_{*t} } {\rm \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; for\; 0.03}\le Re_{*t} \le 10} \\ {0.12^{2} \left(1-0.0858e^{-0.0617(Re_{*t} -10)} \right)^{2} {\rm \; for\; }Re_{*t} >10} \end{array}\right. + \eta = 1 - P_{ft} + \alpha \left( P_{ft} - P_{it} \right) -and :math:`Re_{*t}` is the threshold friction Reynolds number approximation for optimally sized particles +where :math:`P_{it}` is the cumulative probability that the instantaneous wind :math:`\tilde{u}_s` does not exceed the impact threshold :math:`u_{it}`, and :math:`P_{ft}` is the cumulative probability that :math:`\tilde{u}_s` does not exceed the fluid threshold :math:`u_{ft}`. The fluid threshold crossing fraction :math:`\alpha` is defined as the rate of :math:`\tilde{u}_s` sweeping across :math:`u_{ft}` divided by the rate of sweeping across :math:`u_{it}` and :math:`u_{ft}` summed up. The detailed physical interpretation of this formula is in :ref:`Leung et al. (2023)`. Here we just document the equations for each term: + +.. For instance, if :math:`\tilde{u}_s` sweeps across :math:`u_{ft}` often and does not sweep across :math:`u_{it}` much, it means that :math:`\tilde{u}_s` (and thus the timestep-mean :math:`u_s`) should be closer to :math:`u_{ft}` and generally higher than :math:`u_{it}`. Then, :math:`\alpha` is close to 1, and the fraction of time :math:`\eta` (with active emission within a timestep) should also be close to 1. :math:`\alpha` can be represented as .. math:: - :label: 29.11 + :label: threshold_crossing_fraction - Re_{*t} =0.38+1331\left(100D_{osp} \right)^{1.56} + \alpha \approx \left\{ \exp\left[ + \frac{u_{ft}^2 - u_{it}^2 - 2u_s(u_{ft}-u_{it})}{2 \sigma^2_{u_s} } + \right] + 1 \right\}^{-1} -In :eq:`29.5`, :math:`u_{*s}` is defined as the wind friction speed (m s\ :sup:`-1`) accounting for the Owen effect (:ref:`Owen 1964`) +Then, the fraction of time in :math:`\Delta t` when :math:`\tilde{u}_s` is above :math:`u_{ft}` is given by :math:`1 - P_{ft}`, where .. math:: - :label: 29.12 + :label: probability_cross_fluid_threshold + + P_{ft} = \frac{1}{2} \left[ 1 + \operatorname{erf} + \left( \frac{u_{ft} - u_s}{\sqrt{2} \sigma_{u_s}} \right) \right] - u_{*s} = \left\{ - \begin{array}{lr} - u_{*} & \quad {\rm \; for \;} U_{10} ` but here for 10 m above the ground, and :math:`U_{10,\, t}` is the threshold wind speed at 10 m (m s\ :sup:`-1`) + P_{it} = \frac{1}{2} \left[ 1 + \operatorname{erf} + \left( \frac{u_{it} - u_s}{\sqrt{2} \sigma_{u_s}} \right) \right] + +And so the fraction of time :math:`\eta` within :math:`\Delta t` with active emission is determined for :eq:`dust_emiss_flux`. + +.. _Emitted Dust Size Distribution And Dust Transport In Atmosphere: + +Emitted Dust Size Distribution And Dust Transport In Atmosphere +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The total vertical mass emission flux of dust, :math:`F_{d}` (kg m\ :sup:`-2` s\ :sup:`-1`) is then computed with all the above equations and terms. The emission flux is then passed through the coupler to the atmospheric model (CAM) to simulate dust aerosol transport and deposition. The default aerosol model supported in the CAM6 and CAM7 physics is the Modal Aerosol Model (MAM). CAM7 uses the 5-mode MAM (MAM5), in which three modes (Aitken, accumulation, and coarse modes) by default contain dust. + +.. _Brittle Fragmentation Theory For Modal Aerosol Model: + +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. + +.. _Conventional Bin Partition: + +Conventional Bin Partition +------------------------------ + +In the early CESM versions, CAM employed the Bulk Aerosol Model (BAM) as the default aerosol model. Thus, the emission fluxes in CTSM is by default partitioned into 4 bins before passing to the coupler: .. math:: - :label: 29.13 + :label: bin_partition_convention - U_{10,t} =u_{*t} \frac{U_{10} }{u_{*} } + F_{j} = F_d \sum _{i=1}^{I}M_{i,j} -In equation :eq:`29.1` we sum :math:`M_{i,\, j}` over :math:`I=3` source modes :math:`i` where :math:`M_{i,\, j}` is the mass fraction of each source mode :math:`i` carried in each of *:math:`J=4`* transport bins :math:`j` +where :math:`F_{j}` is the mass emission flux from the :math:`j` th aerosol bin. The current way of paritioning the emission fluxes before passing to the coupler is still being used, but the partition into the different bins is only required by BAM, not the current default MAM in CAM6 and CAM7. Therefore, for MAM, the four :math:`F_{j}` are summed up to become one total flux :math:`F_d` again inside MAM. It is then redistributed inside MAM to different individual MAM modes following the BFT. So, the following details are inherited from previous versions of the code and still works fine, but we may clean up the code in the future. + +Equation :eq:`bin_partition_convention` comes from :ref:`Zender et al. (2003)` and used by :ref:`Mahowald et al. (2006)`. It sums :math:`M_{i,\, j}` over :math:`I=3` source modes :math:`i` where :math:`M_{i,\, j}` is the mass fraction of each source mode :math:`i` carried in each of :math:`J=4` transport bins :math:`j` .. math:: - :label: 29.14 + :label: bin_partition_fraction M_{i,j} =\frac{m_{i} }{2} \left[{\rm erf}\left(\frac{\ln {\textstyle\frac{D_{j,\max } }{\tilde{D}_{v,i} }} }{\sqrt{2} \ln \sigma _{g,i} } \right)-{\rm erf}\left(\frac{\ln {\textstyle\frac{D_{j,\min } }{\tilde{D}_{v,i} }} }{\sqrt{2} \ln \sigma _{g,i} } \right)\right] where :math:`m_{i}`, :math:`\tilde{D}_{v,\, i}`, and :math:`\sigma _{g,\, i}` are the mass fraction, mass median diameter, and geometric standard deviation assigned to each particle source mode :math:`i` (:numref:`Table Dust Mass fraction`), while :math:`D_{j,\, \min }` and :math:`D_{j,\, \max }` are the minimum and maximum diameters (m) in each transport bin :math:`j` (:numref:`Table Dust Minimum and maximum particle diameters`). +Note that in CAM, dust emission flux will be scaled by another global dust tuning factor for matching the observed atmospheric dust constraints. + + .. _Table Dust Mass fraction: .. table:: Mass fraction :math:`m_{i}` , mass median diameter :math:`\tilde{D}_{v,\, i}` , and geometric standard deviation :math:`\sigma _{g,\, i}` , per dust source mode :math:`i` 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 3aa6be1b71..58ab424a81 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -239,6 +239,10 @@ Collatz, G.J., Ribas-Carbo, M., and Berry, J.A. 1992. Coupled photosynthesis-sto Colmer, T.D., 2003. Long-distance transport of gases in plants: a perspective on internal aeration and radial oxygen loss from roots. Plant Cell and Environment 26:17-36. +.. _Comolaetal2019: + +Comola, F., Kok, J.F., Chamecki, M. and Martin, R.L., 2019. The intermittency of wind‐driven sand transport. Geophysical Research Letters, 46(22), pp.13430-13440. DOI:10.1029/2019GL085739. + .. _Conwayetal1996: Conway, H., Gades, A., and Raymond, C.F. 1996. Albedo of dirty snow during conditions of melt. Water Resour. Res. 32:1713-1718. @@ -275,6 +279,10 @@ Dai, Y., Dickinson, R.E., and Wang, Y.-P. 2004. A two-big-leaf model for canopy Dai, A., and Trenberth, K.E. 2002. Estimates of freshwater discharge from continents: Latitudinal and seasonal variations. J. Hydrometeor. 3:660-687. +.. _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. + .. _DeFriesetal2000: DeFries, R.S., Hansen, M.C., Townshend, J.R.G., Janetos, A.C., and Loveland, T.R. 2000. A new global 1-km dataset of percentage tree cover derived from remote sensing. Global Change Biol. 6:247-254. @@ -351,6 +359,10 @@ Farquhar, G.D., von Caemmerer, S., and Berry, J.A. 1980. A biochemical model of Farquhar, G.D., and von Caemmerer, S. 1982. Modeling of photosynthetic response to environmental conditions. pp. 549-587. In: O.L. Lange, P.S. Nobel, C.B. Osmond, and H. Zeigler (editors) Encyclopedia of Plant Physiology. Vol. 12B. Physiological Plant Ecology. II. Water Relations and Carbon Assimilation. Springer-Verlag, New York. +.. _Fecanetal1999: + +Fécan, F., Marticorena, B. and Bergametti, G., 1998, December. Parametrization of the increase of the aeolian erosion threshold wind friction velocity due to soil moisture for arid and semi-arid areas. In Annales Geophysicae (Vol. 17, No. 1, pp. 149-157). Berlin/Heidelberg: Springer-Verlag. DOI:10.1007/s00585-999-0149-7. + .. _FeddemaKauffman2016: Feddema, J., Kauffman, B. 2016. Urban Properties Tool (Version 1.2). NCAR THESIS Tools Library. Retrieved from: https://svn-iam-thesis-release.cgd.ucar.edu/urban_properties/. doi:10.5065/D6R78CMT. @@ -627,6 +639,18 @@ Kimball, J.S., Thornton, P.E., White, M.A. and Running, S.W. 1997. Simulating fo Kohyama, T., Suzuki, E., Partomihardjo, T., and Yamada, T. 2001. Dynamic steady state of patch-mosaic tree size structure of a mixed diptocarp forest regulated by local crowding. Ecological Research 16:85-98. +.. _Koketal2012: + +Kok, J.F., Parteli, E.J., Michaels, T.I. and Karam, D.B., 2012. The physics of wind-blown sand and dust. Reports on progress in Physics, 75(10), p.106901. DOI:10.1088/0034-4885/75/10/106901. + +.. _Koketal2014a: + +Kok, J.F., Mahowald, N.M., Fratini, G., Gillies, J.A., Ishizuka, M., Leys, J.F., Mikami, M., Park, M.S., Park, S.U., Van Pelt, R.S. and Zobeck, T.M., 2014a. An improved dust emission model–Part 1: Model description and comparison against measurements. Atmospheric Chemistry and Physics, 14(23), pp.13023-13041. + +.. _Koketal2014b: + +Kok, J.F., Albani, S., Mahowald, N.M. and Ward, D.S., 2014b. An improved dust emission model–Part 2: Evaluation in the Community Earth System Model, with implications for the use of dust source functions. Atmospheric Chemistry and Physics, 14(23), pp.13043-13061. DOI: 10.5194/acp-14-13043-2014. + .. _Kourzeneva2009: Kourzeneva, E., 2009. Global dataset for the parameterization of lakes in Numerical Weather Prediction and Climate modeling. ALADIN Newsletter, No 37, July-December, 2009, F. Bouttier and C. Fischer, Eds., Meteo-France, Toulouse, France, 46-53. @@ -751,6 +775,14 @@ Lerman, A., 1979. Geochemical processes: Water and sediment environments. John W Letts, M.G., Roulet, N.T., Comer, N.T., Skarupa, M.R., and Verseghy, D.L. 2000. Parametrization of peatland hydraulic properties for the Canadian Land Surface Scheme. Atmos.-Ocean 38:141-160. +.. _Leungetal2023: + +Leung, D.M., Kok, J.F., Li, L., Okin, G.S., Prigent, C., Klose, M., Pérez García-Pando, C., Menut, L., Mahowald, N.M., Lawrence, D.M. and Chamecki, M., 2023. A new process-based and scale-aware desert dust emission scheme for global climate models–Part I: Description and evaluation against inverse modeling emissions. Atmos. Chem. Phys., 23(11), pp.6487-6523. DOI:10.5194/acp-23-6487-2023. + +.. _Leungetal2024: + +Leung, D.M., Kok, J.F., Li, L., Mahowald, N.M., Lawrence, D.M., Tilmes, S., Kluzek, E., Klose, M. and Pérez García-Pando, C., 2024. A new process-based and scale-aware desert dust emission scheme for global climate models–Part II: Evaluation in the Community Earth System Model version 2 (CESM2). Atmos. Chem. Phys., 24(4), pp.2287-2318. DOI:10.5194/acp-24-2287-2024. + .. _Levisetal2003: Levis, S., Wiedinmyer, C., Bonan, G.B., and Guenther, A. 2003. Simulating biogenic volatile organic compound emissions in the Community Climate System Model. J. Geophys. Res. 108:4659. DOI:10.1029/2002JD003203. @@ -875,6 +907,10 @@ Mao, J., Thornton, P.E., Shi, X., Zhao, M., and Post, W.M. 2012. Remote sensing Mao, J., Shi, X., Thornton, P.E., Hoffman, F.M., Zhu, Z., and Ranga B. Myneni, R.B. 2013. Global latitudinal-asymmetric vegetation growth trends and their driving mechanisms: 1982-2009. Remote Sensing 5:1484-1497. +.. _MarticorenaBergametti1995: + +Marticorena, B. and Bergametti, G., 1995. Modeling the atmospheric dust cycle: 1. Design of a soil‐derived dust emission scheme. Journal of geophysical research: atmospheres, 100(D8), pp.16415-16430. DOI: 10.1029/95JD00690. + .. _Martinetal1980: Martin, J.P., Haider, K. and Kassim, G., 1980. Biodegradation and stabilization after 2 years of specific crop, lignin, and polysaccharide carbons in soils. Soil Science Society of America Journal 44:1250-1255. @@ -908,6 +944,10 @@ https://doi.org/10.5194/gmd-15-2365-2022 Melzer, E., and O'Leary, M.H. 1987. Anapleurotic CO2 Fixation by Phosphoenolpyruvate Carboxylase in C3 Plants. Plant. Physiol. 84:58. +.. _Mengetal2022: + +Meng, J., Huang, Y., Leung, D.M., Li, L., Adebiyi, A.A., Ryder, C.L., Mahowald, N.M. and Kok, J.F., 2022. Improved parameterization for the size distribution of emitted dust aerosols reduces model underestimation of super coarse dust. Geophysical Research Letters, 49(8), p.e2021GL097287. DOI:10.1029/2021GL097287. + .. _Milleretal1994: Miller, J.R., Russell, G.L., and Caliri, G. 1994. Continental-scale river flow in climate models. J. Climate 7:914-928. @@ -980,6 +1020,10 @@ Oikawa, S., Hikosaka, K. and Hirose, T., 2005. Dynamics of leaf area and nitroge Oke, T. 1987. Boundary Layer Climates (2:math:`{}^{nd}` edition). Routledge, London and New York. +.. _Okin2008: + +Okin, G.S., 2008. A new model of wind erosion in the presence of vegetation. Journal of Geophysical Research: Earth Surface, 113(F2). DOI: 10.1029/2007JF000758. + .. _OlesonBonan2000: Oleson, K.W., and Bonan, G.B. 2000. The effects of remotely-sensed plant functional type and leaf area index on simulations of boreal forest surface fluxes by the NCAR land surface model. J. Hydrometeor. 1:431-446. @@ -1040,6 +1084,10 @@ Ozdogan, M., Rodell, M., Beaudoing, H.K., and Toll, D.L. 2010. Simulating the ef Page, S.E., Siegert, F., Rieley, J.O., Boehm, H-D.V., Jaya, A., and Limin, S. 2002. The amount of carbon released from peat and forest fires in Indonesia in 1997. Nature 420:61-65. +.. _Panofskyetal1977: + +Panofsky, H.A., Tennekes, H., Lenschow, D.H. and Wyngaard, J.C., 1977. The characteristics of turbulent velocity components in the surface layer under convective conditions. Boundary-Layer Meteorology, 11(3), pp.355-361. DOI:10.1007/BF02186086. + .. _PanofskyDutton1984: Panofsky, H.A., and Dutton, J.A. 1984. Atmospheric Turbulence: Models and Methods for Engineering Applications. John Wiley and Sons, New York. @@ -1092,6 +1140,10 @@ Philip, J.R. 1957. Evaporation, and moisture and heat fields in the soil. J. Met Piao, S.L., et al. 2012. The carbon budget of terrestrial ecosystems in East Asia over the last two decades. Biogeosciences 9:3571-3586. +.. _Pierreetal2014: + +Pierre, C., Bergametti, G., Marticorena, B., Kergoat, L., Mougin, E. and Hiernaux, P., 2014. Comparing drag partition schemes over a herbaceous Sahelian rangeland. Journal of Geophysical Research: Earth Surface, 119(10), pp.2291-2313. DOI: 10.1002/2014JF003177. + .. _Pivovarov1972: Pivovarov, A.A., 1972. Thermal Conditions in Freezing Lakes and Reservoirs. John Wiley, New York. @@ -1112,6 +1164,10 @@ Portmann, F.T., Siebert, S., and Döll, P. 2010. MIRCA2000 - Global monthly irri Press, W.H., Teukolsky, S.A., Vetterling, W.T., and Flannery, B.P. 1992. Numerical Recipes in FORTRAN: The Art of Scientific Computing. Cambridge University Press, New York. +.. _Prigentetal2005: + +Prigent, C., Tegen, I., Aires, F., Marticorena, B. and Zribi, M., 2005. Estimation of the aerodynamic roughness length in arid and semi‐arid regions over the globe with the ERS scatterometer. Journal of Geophysical Research: Atmospheres, 110(D9). DOI:10.1029/2004JD005370. + .. _Prigentetal2007: Prigent, C., Papa, F., Aires, F., Rossow, W.B. and Matthews, E. 2007. Global inundation dynamics inferred from multiple satellite observations, 1993-2000. J. Geophys. Res. 112(D12). @@ -1248,6 +1304,10 @@ Sellers, P.J., Randall, D.A., Collatz, G.J., Berry, J.A., Field, C.B., Dazlich, Sellers, Piers J et al. (1996). A revised land surface parameterization (SiB2) for atmospheric GCMs. Part II: The generation of global fields of terrestrial biophysical parameters from satellite data. Journal of climate 9.4, pp. 706-737. +.. _ShaoLu2000: + +Shao, Y. and Lu, H., 2000. A simple expression for wind erosion threshold friction velocity. Journal of Geophysical Research: Atmospheres, 105(D17), pp.22437-22443. DOI:10.1029/2000JD900304. + .. _Shietal2013: Shi, X., Mao, J., Thornton, P.E., and Huang, M. 2013. Spatiotemporal patterns of evapotranspiration in response to multiple environmental factors simulated by the Community Land Model. Environ. Res. Lett. 8:024012. diff --git a/doc/source/tech_note/mizuRoute/Tech_Note_mizuRoute.rst b/doc/source/tech_note/mizuRoute/Tech_Note_mizuRoute.rst index 45e86bd2dc..299f000a90 100644 --- a/doc/source/tech_note/mizuRoute/Tech_Note_mizuRoute.rst +++ b/doc/source/tech_note/mizuRoute/Tech_Note_mizuRoute.rst @@ -1,6 +1,6 @@ .. _rst_mizuRoute: -River Routing Model (mizuRoute) +River Routing Model (MizuRoute) ==================================================== .. _Overview mizuRoute: @@ -8,18 +8,24 @@ River Routing Model (mizuRoute) Overview --------- -mizuRoute is a river transport model designed for applications across local, regional and global scales that can use either regular grids or more intricate unstructured grids on Hydrologic Response Units (HRU's). -When run with regular grids those grids still need to be formatted to an unstructured grid format, for use by mizuRoute. And mizuRoute currently only handles data over land and not data over ocean. +MizuRoute is a river transport model designed for applications across local, regional and global scales that can use either regular grids or more intricate unstructured grids on Hydrologic Response Units (HRU's). +When run with regular grids those grids still need to be formatted to an unstructured grid format for use by mizuRoute, as mizuRoute currently only handles data over land and not data over ocean. The name corresponds to the Japanese word for water, "mizu", and the English word "route," reflecting its purpose in modeling water flow through river systems. -mizuRoute is a significant advancement beyond the MOSART model used in CLM50. -A few notable mizuRoute features include: -1. Ability to run on HRU's allows for more sophisticated hydrology applications. -1. A lake model which allows the modelling of lake volumes and flow from natural and managed lakes. -1. mizuRoute like MOSART can also be run connected to the Hillslope option in CTSM. -mizuRoute Technical Note +MizuRoute is a significant advancement beyond the MOSART model used in CLM50. A few notable mizuRoute features include: + +#. Ability to run on HRU's allows for more sophisticated hydrology applications. + +#. Hybrid (MPI Distributed Memory + OpenMP Shared Memory) parallelization. + +#. A lake model which enables the simulations of lake volumes and flow from natural and managed lakes. + +#. MizuRoute like MOSART can also be run connected to the Hillslope option in CTSM. + +Further reading ------------------------- -The mizuRoute web page is here: https://escomp.github.io/mizuRoute/ -And the mizuRoute Technical Note is here: https://mizuroute.readthedocs.io/en/latest/tech_note/index.html +For more information about mizuRoute, please read `mizuRoute Technical note`_. + +.. _mizuRoute Technical note: https://mizuroute.readthedocs.io/en/latest/tech_note/index.html diff --git a/src/main/clm_driver.F90 b/src/main/clm_driver.F90 index 38d13a71f8..05fa6145ba 100644 --- a/src/main/clm_driver.F90 +++ b/src/main/clm_driver.F90 @@ -120,6 +120,7 @@ subroutine clm_drv(doalb, nextsw_cday, declinp1, declin, rstwr, nlend, rdate, ro use FATESFireFactoryMod , only : scalar_lightning use FatesInterfaceTypesMod, only : fates_dispersal_cadence_none use CIsoAtmTimeseriesMod, only : C14BombSpike, C13TimeSeries + use shr_log_mod, only : errMsg => shr_log_errMsg ! ! !ARGUMENTS: implicit none @@ -822,6 +823,12 @@ subroutine clm_drv(doalb, nextsw_cday, declinp1, declin, rstwr, nlend, rdate, ro if (irrigate) then + if (use_fates) then + call endrun(msg=' ERROR: Can not have ' // & + 'use_fates = .true. and irrigate = .true. ' // & + 'Set one of them to .false. in your user_nl_clm. ' // & + errMsg(sourcefile, __LINE__)) + endif ! ============================================================================ ! Determine irrigation needed for future time steps ! ============================================================================