New documentation for the CTSM dust emission module #3624

dmleung · 2025-11-24T09:10:27Z

… New CTSM dust emission documentation by @dmleung.

Description of changes

This PR is on updating the ctsm tech note / documentation on the CTSM dust emission modules, Leung_2023 and Zender_2003.

Specific notes

Contributors other than yourself, if any:
@samsrabin @ekluzek
@tilmes

CTSM Issues Fixed (include github issue #):
#3170

Are answers expected to change (and if so in what way)?
No, this is a documentation to the dust emission module

Any User Interface Changes (namelist or namelist defaults changes)?
No

Does this create a need to change or add documentation? Did you do so?
This PR is on changing the documentation.

Testing performed, if any:

… dmleung.

dmleung · 2025-11-24T09:13:47Z

Hi @samsrabin I do need to make a few more commits to clean up the doc, check section numbers, and add references before it's ready for review. I will make updates soon, but I do want to put a draft PR here. Thanks!

ekluzek · 2025-11-24T20:37:00Z

I rebased this to come to b4b-dev rather than master.

ekluzek · 2025-11-24T20:41:01Z

I rebased this to come in on b4b-dev rather than master.

dmleung · 2025-11-25T05:51:30Z

Oh, I don't know we are merging to b4b-dev. Thanks for doing that Erik!

…tation.

… pass the initial check.

dmleung · 2026-01-12T20:31:28Z

Hi @samsrabin and @ekluzek, I just wanted to ping you and say that I think this PR is ready for review when you have time.
Let me know if there are issues and I can edit the files further. Thanks!

ekluzek

@dmleung thanks for your work here! It's nice to have this update in place, and not to have to worry about getting it in later.

I have a couple suggestions about handling "g" and changing rho _{a} to rho _{atm} as that seems to be more consistent in other places in the tech note. We should also just remove the details about Zender, as that will be documented in the CLM50 tech note, and it would be confusing here. You might mention it as the previous method and say details on it are in the CLM50 tech note. But, it adds too much complexity to give the full details of both here.

ekluzek · 2026-01-12T21:14:44Z

doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst

-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<Mahowaldetal2006>` accounts for these factors based on the DEAD (Dust Entrainment and Deposition model of :ref:`Zender et al. (2003)<Zenderetal2003>`. Please refer to the :ref:`Zender et al. (2003)<Zenderetal2003>` 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<Leungetal2023>`; :ref:`Leung et al. 2024<Leungetal2024>`) which is the default for the CLM6 physics, and the other is Zender_2003 (:ref:`Mahowald et al. 2006<Mahowaldetal2006>`) based on the DEAD (Dust Entrainment and Deposition model of :ref:`Zender et al. (2003)<Zenderetal2003>`.
+
+One can control the use of the dust emission scheme by setting the namelist variable: 


@dmleung this is a detail on running that code that doesn't need to be here. I don't think we give the same instruction for other parameterizations.

ekluzek · 2026-01-12T21:18:18Z

doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst

 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

 .. math::
-   :label: 29.1


@samsrabin and @dmleung I don't think we could keep the old description of Zender. The CLM5.0 tech note gives that, so I think we should just add the new and remove the old bits about Zender. I'm pretty sure this is how we've handled things in the past as well.

@dmleung could you take on removing the Zender bits? It's not completely clear to where that would be done. But, I suspect you could do it easily.

If Zender isn't an option anymore, it should be removed, yes.

@samsrabin it is an option -- you can specify a namelist variable to switch between the two dust emission schemes. And, Zender_2003 is the default for CLM5 physics.
@ekluzek, do you mean since Zender is only for CLM5 physics, we can go ahead and delete it? If so, I can do that. And I briefly note that people can refer to the old CLM5.0 tech note for Zender?

ekluzek · 2026-01-13T01:00:31Z

doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst

+   u_{*ft0}(D_{p},\rho_{a}) = \sqrt{\frac{A(\rho_{p} g D_{p} + \gamma / D_{p}) }{\rho_{a}} } 
+
+
+where :math:`g = 9.81` m s\ :sup:`-2` is gravity, :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. 


There is a table of constants in the back Table 2.2.7, at least "g" is there. The "where" style is used in other places though, so the empirical constants should be handled that way. rho_{p} isn't anywhere else so can be here as well.

It's handled like this in the Lake part:

Lake/CLM50_Tech_Note_Lake.rst:where :math:`\alpha` = 0.1, :math:`\nu` is the kinematic viscosity of air given below, ...., and *g* is the acceleration of gravity (:numref:`Table Physical Constants`).

ekluzek · 2026-01-13T01:03:27Z

doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst

+
+   w=\theta\frac{ \rho _{water} }{\rho_{bulk} }
+
+Note that :math:`w` in CTSM is conventionally (since CLM3; :ref:`Mahowald et al. 2006<Mahowaldetal2006>`) treated as a sum of both liquid and ice/frozen soil moisture at the topmost soil layer, i.e., :math:`w = w_{liq,1} + w_{ice,1}`. :math:`\rho_{water} = 1000 kg\ m^{-3}` is typical water density, and bulk density :math:`\rho_{bulk}` is given by 


As above rho _{liq} and rho _{ice} are defined in the table of physical constants. So reference those here.

ekluzek · 2026-01-13T01:09:46Z

doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst

+
+   F_{d} = \eta C_{tune} C_{d} f_{bare} f_{clay} \frac{ \rho_{a} (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, and :math:`F_{d}` is the total emission flux summed across modes/bins following a revised form of :ref:`Kok et al. (2014b)<Koketal2014b>`. The dust emission flux goes to zero when :math:`u_{*s} \, < \, u_{*it}`. :math:`\rho_{a}` is surface air density from CAM (the atm model). 


It looks like rho {atm} is what's used elsewhere in the tech note to refer to atmospheric air density. Seems like we should consistently use it, rather than rho{a} here.

@samsrabin it seems like a worthwhile task could be to describe rho _{atm} in one place and reference it elsewhere. At first I thought it should be in the physical constants table, but it's NOT a physical constant, just derived in a small equation. I'll make this into an issue if you think that makes sense.

That sounds good. Another idea (but this should be a separate issue, if we even want to bother as it'll be a heavy lift) would be to start using the glossary and term features.

initial commit of a new documentation for the dust emission module by…

c66459e

… dmleung.

ekluzek changed the base branch from master to b4b-dev November 24, 2025 20:36

samsrabin added documentation additions or edits to user-facing documentation or its infrastructure docs:update Significant update or fix needed to existing documentation docs-loc:tech-note Relates to Technical Note (science) labels Nov 25, 2025

samsrabin linked an issue Nov 25, 2025 that may be closed by this pull request

Docs needed: Dust updates #3170

Open

8 tasks

samsrabin added this to the cesm3.0.0 release branch tag milestone Nov 25, 2025

samsrabin added this to CLM documentation Nov 25, 2025

samsrabin moved this to In Progress in CLM documentation Nov 25, 2025

dmleung and others added 4 commits December 23, 2025 17:58

Adding citations and more changes to the dust emission scheme documen…

90a67d5

…tation.

adding back two references that were accidentally deleted in order to…

bb0dec6

… pass the initial check.

Some cleanup, shortening, and rewriting of the dust doc

2306242

Merge branch 'b4b-dev' into docs-playground

b05b018

dmleung marked this pull request as ready for review January 12, 2026 20:27

ekluzek requested changes Jan 13, 2026

View reviewed changes

slevis-lmwg assigned dmleung Jan 13, 2026

ekluzek changed the title ~~A new documentation for the CTSM dust emission module~~ New documentation for the CTSM dust emission module Jan 15, 2026

		u_{*ft0}(D_{p},\rho_{a}) = \sqrt{\frac{A(\rho_{p} g D_{p} + \gamma / D_{p}) }{\rho_{a}} }


		where :math:`g = 9.81` m s\ :sup:`-2` is gravity, :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.


		w=\theta\frac{ \rho _{water} }{\rho_{bulk} }

		Note that :math:`w` in CTSM is conventionally (since CLM3; :ref:`Mahowald et al. 2006<Mahowaldetal2006>`) treated as a sum of both liquid and ice/frozen soil moisture at the topmost soil layer, i.e., :math:`w = w_{liq,1} + w_{ice,1}`. :math:`\rho_{water} = 1000 kg\ m^{-3}` is typical water density, and bulk density :math:`\rho_{bulk}` is given by


		F_{d} = \eta C_{tune} C_{d} f_{bare} f_{clay} \frac{ \rho_{a} (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, and :math:`F_{d}` is the total emission flux summed across modes/bins following a revised form of :ref:`Kok et al. (2014b)<Koketal2014b>`. The dust emission flux goes to zero when :math:`u_{s} \, < \, u_{it}`. :math:`\rho_{a}` is surface air density from CAM (the atm model).

New documentation for the CTSM dust emission module #3624

Are you sure you want to change the base?

New documentation for the CTSM dust emission module #3624

Conversation

dmleung commented Nov 24, 2025

Description of changes

Specific notes

Uh oh!

dmleung commented Nov 24, 2025

Uh oh!

ekluzek commented Nov 24, 2025

Uh oh!

ekluzek commented Nov 24, 2025

Uh oh!

dmleung commented Nov 25, 2025

Uh oh!

dmleung commented Jan 12, 2026

Uh oh!

ekluzek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants